本文是针对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 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 OKContent-Length: 95267Content-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.Formattersusing 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 ); 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 ; 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使用库以执行序列化。
如果您愿意，可以配置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 // UTC2012-07-27T11:51:45.53403-07:00 // Local
默认情况下，Json.NET 保留时区。 您可以通过设置 DateTimeZoneHandling 属性覆盖此：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;json.SerializerSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc;
如果想要使用("\/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 中，可以使用中的属性命名空间来对模型设置属性的验证规则。 请考虑以下模型：
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 RequestContent-Type: application/json; charset=utf-8Content-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);}