本文是针对ASP.NET WepApi 2 的笔记。
Web API 可返回的结果：
1.void
2.HttpResponseMessage
3.IHttpActionResult
4.其他类型
| 返回类型 | Web API创建响应的方式 |
| void | HTTP204(无内容) |
| HttpResponseMessage | 转换为HTTP响应消息 |
| IHttpActionRsult | 调用ExecuteAsync来创建HttpResponseMessage,然后转换为HTTP响应消息 |
| 其他类型 | 将序列化的返回值写到响应正文中，返回HTTP200 |
路由
路由表：Web API的默认路由模板"api/{controller}/{id}",此模板中,"api"是文本路径段,{controller}和{id}是占位符变量。
路由变体：可以显示指定Action的HTTP方法，如HttpGet,HttpPost。
public class ProductsController : ApiController
{
[HttpGet]
public Product FindProduct(id) {}
}
若要允许多个HTTP方法或GET,POST,PUT,DELETE以外的HTTP方法，可以显示使用AcceptVerbs属性：
public class ProductsController : ApiController
{
[AcceptVerbs("GET", "HEAD")]
public Product FindProduct(id) { } // WebDAV method
[AcceptVerbs("MKCOL")]
public void MakeCollection() { }
}
可以通过ActionName属性重写Action名称：
public class ProductsController : ApiController
{
[HttpGet]
[ActionName("Thumbnail")]
public HttpResponseMessage GetThumbnailImage(int id); [HttpPost]
[ActionName("Thumbnail")]
public void AddThumbnailImage(int id);
}
也可以使用NonAction属性指定Action不参与路由匹配:
// Not an action method.
[NonAction]
public string GetPrivateData() { ... }
Web API路由过程的某些部分提供了扩展点：
| 接口 | 描述 |
| IHttpControllerSelector | 选择控制器 |
| IHttpControllerTypeResolver | 获取控制器类型的列表。DefaultHttpControllerSelector从此列表中选择控制器类型 |
| IAssembliesResolver | 获取项目的程序集的列表。IHttpControllerTypeResolver接口使用此列表找到控制器的类型 |
| IHttpControllerActivator | 创建新的控制器实例 |
| IHttpActionSelector | 选择Action |
| IHttpActionInvoker | 调用Action |
若要为这些接口提供自己的实现，在HttpConfiguration对象上操作,HttpConfigutation在App_Start文件夹下的WebApiConfig.cs文件下能找到,也可以自己获取：
var config = GlobalConfiguration.Configuration;
config.Services.Replace(typeof(IHttpControllerSelector), new MyControllerSelector(config));
属性路由：Route是API 2支持的一种新类型的路由，顾名思义，它可以使用属性定义路由:
[Route("customers/{customerId}/orders")]
public IEnumerable<Order> GetOrdersByCustomer(int customerId) { ... }
你可能需要先启用，才能使用属性路由：
using System.Web.Http; namespace WebApplication
{
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// Web API routes
config.MapHttpAttributeRoutes(); // Other Web API configuration not shown.
}
}
}
路由名称：
在Web API 中，每个路由都有一个名称。路由名称可用于生成链接，以便可以在HTTP响应中包含一个链接。
Route可以设置名称属性，下面的代码演示如何设置路由名称，以及如何使用根据路由名称生成的链接：
public class BooksController : ApiController
{
[Route("api/books/{id}", Name="GetBookById")]
public BookDto GetBook(int id)
{
// Implementation not shown...
} [Route("api/books")]
public HttpResponseMessage Post(Book book)
{
// Validate and add book to database (not shown) var response = Request.CreateResponse(HttpStatusCode.Created); // Generate a link to the new book and set the Location header in the response.
string uri = Url.Link("GetBookById", new { id = book.BookId });
response.Headers.Location = new Uri(uri);
return response;
}
}
路由顺序：属性路由还可以指定路由匹配时的顺序，RouteOrder,默认顺序是0，首先计算较低的值。
媒体格式化
媒体类型,也称MIME类型。在HTTP中，媒体类型描述消息正文的格式。例如：
- text/html
- image/png
- application/json
当HTTP消息包含实体正文时，Content-type标头指定消息正文的格式。
例如，如果HTTP响应包含PNG图像，响应可能包含以下标头：
HTTP/1.1 200 OK
Content-Length: 95267
Content-Type: image/png
当客户端发送请求时，它可以包含Accept标头。Accept标头指示客服端想要从服务器获取的响应媒体类型。例如：
Accept: text/html,application/xhtml+xml,application/xml
此标头指示客户端希望获得HTML、XHTML或XML。
媒体类型可以确定Web API 如何序列化和反序列化HTTP消息正文。可以通过编写自己的媒体类型达到扩展Web API序列化和反序列化的目的。
若要创建媒体格式化程序，需要实现以下类：
- MediaTypeFormatter。 此类使用异步的方式读取和写入。
- BufferedMediaTypeFormatter。此类派生自MediaTypeFormatter,但是使用同步的方式读取和写入。
下面的实例演示的媒体类型可以序列化以逗号分割值(CSV)格式的产品对象。下面是Product对象的定义：
namespace ProductStore.Models
{
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public string Category { get; set; }
public decimal Price { get; set; }
}
}
若要实现CSV格式化程序，定义一个类，派生自BufferedMediaTypeFormatter:
namespace ProductStore.Formatters
using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Net.Http.Headers;
using ProductStore.Models; namespace ProductStore.Formatters
{
public class ProductCsvFormatter : BufferedMediaTypeFormatter
{
}
}
在构造函数中，添加格式化程序支持的媒体类型。在此示例中，支持类型"text/csv":
public ProductCsvFormatter()
{
// Add the supported media type.
SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/csv"));
}
重写CanWriteType方法，以指示该类型格式化程序可以序列化：
public override bool CanWriteType(System.Type type)
{
if (type == typeof(Product))
{
return true;
}
else
{
Type enumerableType = typeof(IEnumerable<Product>);
return enumerableType.IsAssignableFrom(type);
}
}
在此示例中，格式化程序可以序列化单个Product对象的集合、Product对象。
同样，重写CanReadType方法，以指示该类型格式化程序可以反序列化。在此示例中，格式化程序不支持反序列化，因此，此方法返回false：
public override bool CanReadType(Type type)
{
return false;
}
最后，重写WriteToStream方法。此方法通过向流写入序列化程序。如果支持反序列化，还可以重写ReadFromStream方法。
public override void WriteToStream(Type type, object value, Stream writeStream, HttpContent content)
{
using (var writer = new StreamWriter(writeStream))
{
var products = value as IEnumerable<Product>;
if (products != null)
{
foreach (var product in products)
{
WriteItem(product, writer);
}
}
else
{
var singleProduct = value as Product;
if (singleProduct == null)
{
throw new InvalidOperationException("Cannot serialize type");
}
WriteItem(singleProduct, writer);
}
}
} // Helper methods for serializing Products to CSV format.
private void WriteItem(Product product, StreamWriter writer)
{
writer.WriteLine("{0},{1},{2},{3}", Escape(product.Id),
Escape(product.Name), Escape(product.Category), Escape(product.Price));
} static char[] _specialChars = new char[] { ',', '\n', '\r', '"' }; private string Escape(object o)
{
if (o == null)
{
return "";
}
string field = o.ToString();
if (field.IndexOfAny(_specialChars) != -1)
{
// Delimit the entire field with quotes and replace embedded quotes with "".
return String.Format("\"{0}\"", field.Replace("\"", "\"\""));
}
else return field;
}
将自定义的媒体格式化程序添加到Web API管道
public static void ConfigureApis(HttpConfiguration config)
{
config.Formatters.Add(new ProductCsvFormatter());
}
WebAPI 提供了对JSON和XML的媒体类型格式化程序。
JSON格式由JsonMediaTypeFormatter类处理，默认情况下JsonMediaTypeFormatter使用Json.NET库以执行序列化。
如果您愿意，可以配置JsonMediaTypeFormatter,以使用DataContractJsonSerializer而不是Json.NET。若要执行此操作，设置UseDataContractJsonSerializer属性true:
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.UseDataContractJsonSerializer = true;
默认情况下，所有公共属性和字段会参与序列化JSON。若要忽略属性或字段，给它装饰JsonIgnore属性。
public class Product
{
public string Name { get; set; }
public decimal Price { get; set; }
[JsonIgnore]
public int ProductCode { get; set; } // omitted
}
你也可以使用DataContract属性装饰你的类，存在此属性，则将忽略所有成员，除非它们具有DataMember（JsonProperty）属性。此外，可以使用DataMember序列化私有成员。
[DataContract]
public class Product
{
[DataMember]
public string Name { get; set; }
[DataMember]
public decimal Price { get; set; }
public int ProductCode { get; set; } // omitted by default
}
默认情况下，只读属性参与序列化。
默认情况下，Json.NET将日期将采用ISO 8601格式。使用"Z"后缀编写日期以 UTC （协调世界时）。 以本地时间日期包含时区偏移量。 例如：
2012-07-27T18:51:45.53403Z // UTC
2012-07-27T11:51:45.53403-07:00 // Local
默认情况下，Json.NET 保留时区。 您可以通过设置 DateTimeZoneHandling 属性覆盖此：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc;
如果想要使用Microsoft JSON 日期格式("\/Date(ticks)\/") 设置而不是 ISO 8601 DateFormatHandling上序列化程序设置属性：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateFormatHandling
= Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat;
编写缩进的JSON，可以如下设置：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.Formatting = Newtonsoft.Json.Formatting.Indented;
JSON属性名称使用驼峰式，无需修改数据模型，设置CamelCasePropertyNamesContractResolver序列化程序：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
可以返回一个匿名对象。
XML媒体类型格式化程序
默认XmlMediaTypeFormatter类。默认使用DataContractSerializer来执行序列化。
如果您愿意，可以配置XmlMediaTypeFormatter若要使用XmlSerializer而不是DataContractSerializer。 若要执行此操作，设置UseXmlSerializer属性设置为true:
var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;
xml.UseXmlSerializer = true;
XmlSerializer类支持一组更窄的类型，而不DataContractSerializer，但提供了更好地控制生成的 XML。 请考虑使用XmlSerializer如果你需要匹配现有 XML 架构。
介绍下DataContractSerializer的序列化行为：
- 所有公共的属性和字段进行序列化。若要忽略，使用IgnoreDataMember属性。
- 不序列私有和受保护成员。
- 只读属性不会序列化（但是，只读集合属性的内容进行序列化）。
- 类和成员名称是用XML类声明中显示完成相同的。
- 使用默认XML命名空间。
如果需要更好地控制序列化，您可以修饰的类DataContract属性。 当存在此属性时，类被序列，如下所示：
- "选择加入"方法： 属性和字段，默认情况下不序列化。 要序列化的属性或字段，给它装饰DataMember属性。
- 要序列化的私有或受保护成员，给它装饰DataMember属性。
- 只读属性不会序列化。
- 若要更改类名称在 XML 中的显示方式，请设置名称中的参数DataContract属性。
- 若要更改成员名称在 XML 中的显示方式，请设置名称中的参数DataMember属性。
- 若要更改的 XML 命名空间，请设置Namespace中的参数DataContract类。
删除JSON或XML格式化程序
如果您不想要使用它们，可以从列表中的格式化程序，删除 JSON 格式化程序或 XML 格式化程序。 若要执行此操作的主要原因是：
- 若要限制为特定媒体类型将 web API 响应。 例如，你可能决定以支持仅将 JSON 响应，并删除 XML 格式化程序。
- 若要使用自定义格式化程序替换默认的格式化程序。 例如，可以使用您自己的 JSON 格式化程序的自定义实现来替换 JSON 格式化程序。
下面的代码演示如何删除默认格式化程序。 调用此成员，从你应用程序_启动Global.asax 中定义的方法。
void ConfigureApi(HttpConfiguration config)
{
// Remove the JSON formatter
config.Formatters.Remove(config.Formatters.JsonFormatter); // or // Remove the XML formatter
config.Formatters.Remove(config.Formatters.XmlFormatter);
}
ASP.NET Web API 中的模型验证
当客户端将数据发送到 web API 时，通常要执行任何处理之前验证数据。
数据注释
在 ASP.NET Web API 中，可以使用中的属性System.ComponentModel.DataAnnotations命名空间来对模型设置属性的验证规则。 请考虑以下模型：
using System.ComponentModel.DataAnnotations; namespace MyApi.Models
{
public class Product
{
public int Id { get; set; }
[Required]
public string Name { get; set; }
public decimal Price { get; set; }
[Range(0, 999)]
public double Weight { get; set; }
}
}
如果已在 ASP.NET MVC 中使用模型验证，这应该很熟悉。 Required属性指出Name属性不能为 null。 Range属性指出Weight必须是介于 0 和 999 之间。
假设客户端发送 POST 请求，其中以下 JSON 表示形式：
{ "Id":4, "Price":2.99, "Weight":5 }
您可以看到客户端未包括Name属性，它被标记为Required。 当 Web API 将转换为 JSONProduct实例，它会验证Product针对验证特性。 在你的控制器操作，可以检查模型是否有效：
using MyApi.Models;
using System.Net;
using System.Net.Http;
using System.Web.Http; namespace MyApi.Controllers
{
public class ProductsController : ApiController
{
public HttpResponseMessage Post(Product product)
{
if (ModelState.IsValid)
{
// Do something with the product (not shown). return new HttpResponseMessage(HttpStatusCode.OK);
}
else
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
}
}
}
}
可以创建一个Action筛选器来调用控制器操作前的模型检查：
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Filters;
using System.Web.Http.ModelBinding; namespace MyApi.Filters
{
public class ValidateModelAttribute : ActionFilterAttribute
{
public override void OnActionExecuting(HttpActionContext actionContext)
{
if (actionContext.ModelState.IsValid == false)
{
actionContext.Response = actionContext.Request.CreateErrorResponse(
HttpStatusCode.BadRequest, actionContext.ModelState);
}
}
}
}
如果模型验证失败，此筛选器将返回 HTTP 响应，其中包含验证错误。 在这种情况下，不会调用控制器操作。
若要将此筛选器应用于所有的 Web API 控制器，将添加到筛选器的实例HttpConfiguration.Filters在配置期间的集合：
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Filters.Add(new ValidateModelAttribute()); // ...
}
}
另一个选项是设置筛选器作为特性上各个控制器或控制器操作：
public class ProductsController : ApiController
{
[ValidateModel]
public HttpResponseMessage Post(Product product)
{
// ...
}
}
ASP.NET Web API 中的参数绑定
Web API 在控制器上调用方法时，必须设置参数的值，此过程称为“绑定”。
默认情况下，Web API 使用以下规则进行参数绑定：
- 如果参数为“简单”类型，Web API 会尝试从 URI 中获取值。 简单类型包括 .NET基元类型（int、 bool、 double等），以及 TimeSpan、DateTime、Guid、decimal 和 string，此外还有**借助类型转换器即可从字符串进行转换的类型。 （稍后介绍有关类型转换器的详细信息。）
- 对于复杂类型，Web API 尝试使用媒体类型格式化程序从消息正文中读取值。
例如，下面是典型的 Web API 控制器方法：
HttpResponseMessage Put(int id, Product item) { ... }
Id 参数是"简单"类型，因此 Web API 尝试从请求 URI 中获取值。 item 参数是复杂类型，因此 Web API 使用媒体类型格式化程序从请求正文中读取值。
使用 [FromUri]
若要强制 Web API 从 URI 读取复杂类型，请向参数添加 [FromUri] 特性。 下面的示例定义 GeoPoint 类型，以及从 URI 获取 GeoPoint 的控制器方法。
public class GeoPoint
{
public double Latitude { get; set; }
public double Longitude { get; set; }
} public ValuesController : ApiController
{
public HttpResponseMessage Get([FromUri] GeoPoint location) { ... }
}
使用 [FromBody]
若要强制 Web API 从请求正文读取简单类型，请向参数添加 [FromBody] 特性：
public HttpResponseMessage Post([FromBody] string name) { ... }
ASP.NET Web API 中的异常处理
HttpResponseException
如果 Web API 控制器引发未捕获的异常，则会发生什么情况？ 默认情况下，大多数异常将转换为状态代码 500 内部服务器错误的 HTTP 响应。
HttpResponseException类型是一种特殊情况。 此异常将返回异常构造函数中指定任何 HTTP 状态代码。 例如，以下方法将返回 404，找不到，如果id参数无效。
public Product GetProduct(int id)
{
Product item = repository.Get(id);
if (item == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
return item;
}
更好地响应的控制，还可以构造的整个响应消息，并将其与包含HttpResponseException:
public Product GetProduct(int id)
{
Product item = repository.Get(id);
if (item == null)
{
var resp = new HttpResponseMessage(HttpStatusCode.NotFound)
{
Content = new StringContent(string.Format("No product with ID = {0}", id)),
ReasonPhrase = "Product ID Not Found"
};
throw new HttpResponseException(resp);
}
return item;
}
异常筛选器
您可以自定义 Web API 通过编写处理异常的方式异常筛选器。 当控制器方法引发任何未处理的异常时执行异常筛选器，除了 HttpResponseException异常。 HttpResponseException类型是一种特殊情况，因为它专为返回的 HTTP 响应。
异常筛选器实现System.Web.Http.Filters.IExceptionFilter接口。 编写异常筛选器的最简单方法是从派生System.Web.Http.Filters.ExceptionFilterAttribute类并重写OnException方法。
下面是将转换的筛选器NotImplementedException异常转化为 HTTP 状态代码 501，未实现：
namespace ProductStore.Filters
{
using System;
using System.Net;
using System.Net.Http;
using System.Web.Http.Filters; public class NotImplExceptionFilterAttribute : ExceptionFilterAttribute
{
public override void OnException(HttpActionExecutedContext context)
{
if (context.Exception is NotImplementedException)
{
context.Response = new HttpResponseMessage(HttpStatusCode.NotImplemented);
}
}
}
}
响应的属性HttpActionExecutedContext对象包含将发送到客户端的 HTTP 响应消息。
注册异常筛选器
有几种方法来注册 Web API 异常筛选器：
- 由Action
- 由控制器
- 全局
筛选器应用到特定的Action，请将作为属性的筛选器添加到操作：
public class ProductsController : ApiController
{
[NotImplExceptionFilter]
public Contact GetContact(int id)
{
throw new NotImplementedException("This method is not implemented");
}
}
筛选器应用到所有控制器上的操作，将筛选器作为属性添加到控制器类：
[NotImplExceptionFilter]
public class ProductsController : ApiController
{
// ...
}
若要对 Web API 的所有控制器全局应用筛选器，将添加到筛选器的实例GlobalConfiguration.Configuration.Filters集合。 在此集合中的异常筛选器适用于任何 Web API 控制器操作。
GlobalConfiguration.Configuration.Filters.Add(
new ProductStore.NotImplExceptionFilterAttribute());
如果使用"ASP.NET MVC 4 Web 应用程序"项目模板来创建你的项目，将 Web API 配置代码内的放WebApiConfig类，该类在应用程序位于_开始文件夹：
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Filters.Add(new ProductStore.NotImplExceptionFilterAttribute()); // Other configuration code...
}
}
HttpError
HttpError对象提供一致的方法来响应正文中返回的错误信息。 下面的示例演示如何返回 HTTP 状态代码 404 （找不到） 与HttpError响应正文中。
public HttpResponseMessage GetProduct(int id)
{
Product item = repository.Get(id);
if (item == null)
{
var message = string.Format("Product with id = {0} not found", id);
return Request.CreateErrorResponse(HttpStatusCode.NotFound, message);
}
else
{
return Request.CreateResponse(HttpStatusCode.OK, item);
}
}
CreateErrorResponse是定义在System.Net.Http.HttpRequestMessageExtensions类里的扩展方法。 在内部， CreateErrorResponse创建HttpError实例，然后创建HttpResponseMessage ，其中包含HttpError.
HttpError 和模型验证
public HttpResponseMessage PostProduct(Product item)
{
if (!ModelState.IsValid)
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
} // Implementation not shown...
}
此示例中可能会返回以下响应：
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 320 {
"Message": "The request is invalid.",
"ModelState": {
"item": [
"Required property 'Name' not found in JSON. Path '', line 1, position 14."
],
"item.Name": [
"The Name field is required."
],
"item.Price": [
"The field Price must be between 0 and 999."
]
}
}
使用 HttpResponseException HttpError
前面的示例返回HttpResponseMessage消息从控制器操作，但您还可以使用HttpResponseException返回HttpError。 这样就可以返回强类型化模型中正常成功的情况下，同时仍返回HttpError如果出现错误：
public Product GetProduct(int id)
{
Product item = repository.Get(id);
if (item == null)
{
var message = string.Format("Product with id = {0} not found", id);
throw new HttpResponseException(
Request.CreateErrorResponse(HttpStatusCode.NotFound, message));
}
else
{
return item;
}
}
全局错误处理 ASP.NET Web API 2 中
如今，在Web API中没有简单的方式记录或处理全局错误。可以通过异常筛选器过滤某些未经处理的异常，但也有一部分异常筛选器不能处理。例如：
- 从控制器的构造函数引发的异常。
- 从消息处理程序引发的异常。
- 在路由期间引发的异常。
- 响应内容序列化期间引发的异常。
我们可以使用异常筛选器，消息处理程序(后面会提到),但是它们都很难处理上面的问题，所以微软提供了两个类：IExceptionLogger和IExceptionHandler。
我们该怎么使用：
- IExceptionLogger用于查看WebAPI捕获到的所有未经过处理的异常。
- IExceptionHandler用于自定义所有可能的响应未经处理WebAPI捕获的异常。
- IExceptionFilter是Controller或者Action下捕捉未经处理的异常的最简单的解决方案。
public interface IExceptionLogger
{
Task LogAsync(ExceptionLoggerContext context,
CancellationToken cancellationToken);
} public interface IExceptionHandler
{
Task HandleAsync(ExceptionHandlerContext context,
CancellationToken cancellationToken);
}