1.2Web API 2中的Action返回值

本主题描述 ASP.NET Web API 将返回值转换从一个控制器动作到 HTTP 响应消息。

一个 Web API 控制器动作可以返回下列任一操作 ︰

1.void

2.IHttpActionResult

3.HttpResponseMessage

4.一些其他类型

根据每种返回，Web API 使用一个不同的机制来创建 HTTP 响应。

返回类型	Web API 如何创建响应
void	返回空 204 （无内容）
HttpResponseMessage	直接将 HTTP 响应消息转换。
IHttpActionResult	调用ExecuteAsync来创建HttpResponseMessage，然后转换到 HTTP 响应消息。
其他类型	序列化返回值写入响应正文;返回 200 (OK)。

一、Void

如果返回类型为void，Web API 只是返回空的 HTTP 响应状态代码 204 （没有内容）。

示例控制器 ︰

 public class ValuesController : ApiController
 {
     public void Post()
     {
     }
 }

响应报文：

TTP/1.1  No Content
Server: Microsoft-IIS/8.0
Date: Mon,  Jan  :: GMT

二、HttpResponseMessage

如果该操作返回HttpResponseMessage，Web API 的返回值直接将转换为 HTTP 响应消息，使用HttpResponseMessage对象的属性来填充响应。

此选项使您大量的响应消息的控制权。例如，以下的控制器操作设置缓存控制标头。

 public class ValuesController : ApiController
 {
     public HttpResponseMessage Get()
     {
         HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value");
         response.Content = new StringContent("hello", Encoding.Unicode);
         response.Headers.CacheControl = new CacheControlHeaderValue()
         {
             MaxAge = TimeSpan.FromMinutes()
         };
         return response;
     }
 }

响应报文：

HTTP/1.1  OK
Cache-Control: max-age=
Content-Length:
Content-Type: text/plain; charset=utf-
Server: Microsoft-IIS/8.0
Date: Mon,  Jan  :: GMT
hello

如果你将一个域模型传递给CreateResponse方法，Web API 使用媒体格式化程序来序列化的模型写入响应正文。

 public HttpResponseMessage Get()
 {
     // Get a list of products from a database.
     IEnumerable<Product> products = GetProductsFromDB();

     // Write the list to the response body.
     HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
     return response;
 }

Web API 使用 Accept 标头在请求中选择格式化程序。

三、IHttpActionResult

IHttpActionResult接口是WebApi2才采用的。本质上，它定义了HttpResponseMessage工厂。下面是使用IHttpActionResult接口的一些优点 ︰

• 简化了单元测试您的控制器。
• 移动普通逻辑到单独的类创建 HTTP 响应。
• 使控制器动作更清晰，意图通过隐藏构建响应的低层细节。

IHttpActionResult包含一个单一的方法， ExecuteAsync，其中以异步方式创建一个HttpResponseMessage实例。

 public interface IHttpActionResult
 {
     Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
 } 

如果一个控制器动作返回IHttpActionResult，Web API 调用ExecuteAsync方法来创建HttpResponseMessage。然后它将HttpResponseMessage转换成 HTTP 响应消息。

这里是IHttpActionResult ，创建纯文本响应简单实施 ︰

 public class TextResult : IHttpActionResult
 {
     string _value;
     HttpRequestMessage _request;

     public TextResult(string value, HttpRequestMessage request)
     {
         _value = value;
         _request = request;
     }
     public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
     {
         var response = new HttpResponseMessage()
         {
             Content = new StringContent(_value),
             RequestMessage = _request
         };
         return Task.FromResult(response);
     }
 }

示例控制器中的操作 ︰

 public class ValuesController : ApiController
 {
     public IHttpActionResult Get()
     {
         return new TextResult("hello", Request);
     }
 }

响应报文：

HTTP/1.1  OK
Content-Length:
Content-Type: text/plain; charset=utf-
Server: Microsoft-IIS/8.0
Date: Mon,  Jan  :: GMT

hello

更多时候，您将使用System.Web.Http.Results命名空间中定义的IHttpActionResult实现。ApiContoller类定义返回这些内置操作结果的帮助器方法。

在以下示例中，如果请求不匹配现有的产品 ID，控制器调用ApiController.NotFound来创建 404 （未找到） 响应。否则，控制器调用ApiController.OK，这将创建包含产品 200 (OK) 响应。

 public IHttpActionResult Get (int id)
 {
     Product product = _repository.Get (id);
     if (product == null)
     {
         return NotFound(); // Returns a NotFoundResult
     }
     return Ok(product);  // Returns an OkNegotiatedContentResult
 }

四、其他返回类型

对于所有其他返回类型，Web API 使用一个media formatter来序列化返回值。Web API 将序列化的值写入到响应正文。响应状态代码是 200 (OK)。

 public class ProductsController : ApiController
 {
     public IEnumerable<Product> Get()
     {
         return GetAllProductsFromDB();
     }
 }

这种方法的一个缺点是你不能直接返回错误代码，例如 404。然而，你可以抛出错误代码为HttpResponseException 。有关详细信息，请参见异常处理在 ASP.NET Web API.

Web API 使用 Accept 标头在请求中选择格式化程序。

请求报文：

GET http://localhost/api/products HTTP/1.1
User-Agent: Fiddler
Host: localhost:
Accept: application/json

响应报文：

HTTP/1.1  OK
Content-Type: application/json; charset=utf-
Server: Microsoft-IIS/8.0
Date: Mon,  Jan  :: GMT
Content-Length: 

[{"Id":,"Name":"Yo-yo","Category":"Toys","Price":6.95}]