使用 ASP.NET Core MVC 建立 Web API——响应数据的内容协商（七）

使用 ASP.NET Core MVC 建立 Web API

使用 ASP.NET Core MVC 建立 Web API（一）

使用 ASP.NET Core MVC 建立 Web API（二）

 使用 ASP.NET Core MVC 建立 Web API（三）

使用 ASP.NET Core MVC 建立 Web API（四）

使用 ASP.NET Core MVC 建立 Web API（五）

使用 ASP.NET Core MVC 建立 Web API（六）

 

     ASP.NET Core MVC 包含对经过固定格式或根据客户端规范来设置响应数据格式的内置支持。

     ASP.NET Web API的内容协商（Content Negotiation）机制的理想状况是这样的：客户端在请求头的Accept字段中指定什么样的MIME类型，Web API服务端就返回对应的MIME类型的内容（响应头的中Content-Type就是Accept中指定的MIME类型）。而现实状况是，Web API服务端能返回什么MIME类型的响应类型取决于有没有对应这个MIME类型的MediaTypeFormatter。ASP.NET Core Web API的默认提供JsonMediaTypeFormatter，若是要支持 XmlMediaTypeFormatter须要进行配置。

      ASP.NET Core MVC 使用的默认格式是 JSON。 内容协商由 ObjectResult 实现。 它还内置于从帮助程序方法（所有基于 ObjectResult）返回的特定于状态代码的操做结果中。 还能够返回一个模型类型（已定义为数据传输类型的类），框架将自动将其打包在 ObjectResult 中。

      如下操做方法返回一个对象实例和 NotFound 帮助程序方法：     

[HttpGet("{id}")]
        public async Task<ActionResult<Book>> GetBookItem(int id)
        {
            var bookItem = await _context.Book.FindAsync(id); 

            if (bookItem == null)
            {
                return NotFound();
            }
            return bookItem;
        }

    将返回 JSON 格式的响应，除非请求了另外一个格式且服务器能够返回所请求格式。 能够使用 Rester工具建立包括 Accept 标头的请求并指定另外一种格式。 在此状况下，若是服务器有能够生成所请求格式的响应的格式化程序，则结果会以服务器首选的格式返回。

    1) 在Visual Studio 2017中按F5，启动BookApi应用程序。

    2) 打开Firefox浏览器，并打开 Rester，在Reseter中，将 HTTP 方法设置为 GET。

   3) 而后在URL输入框中输入要获取的对象URI，例如 http://localhost:5000/api/book/25

   4) 选择“Headers”选项卡，选择“Accept”选项，并将值设置为 JSON (application/json)。

    5) 使用鼠标点击“Send”按钮。请求将收到具备做书籍数据的“200 正常”响应。以下图。

 

     6) 选择“Headers”选项卡，选择“Accept”选项，并将值设置为 xml (application/xml)。

     7) 使用鼠标点击“Send”按钮。请求将收到具备做书籍数据的“200 正常”响应。以下图。咱们虽然指定 Accept为 application/xml，可是在默认状况下，ASP.NET Core MVC 仅支持 JSON。因此，即便指定另外一种格式，返回的结果仍然是 JSON 格式，而不是咱们但愿的xml。以下图。

 

      控制器操做能够返回 POCO（普通旧 CLR 对象），在这种状况下，ASP.NET Core MVC 将自动建立打包对象的 ObjectResult。 客户端将获取设有格式的序列化对象（默认为 JSON 格式，能够配置 XML 或其余格式）。 若是返回的对象为 null，那么框架将返回 204 No Content 响应。

    1） 在Visual Studio 2017中打开BookController.cs文件，添加如下 GetBook 方法返回实体对象，代码以下：

[HttpGet("{id}")]
        public  Book GetBook(int id)
        {
            var bookItem =  _context.Book.Find(id);       
            return bookItem;
        }

     2）在Visual Studio 2017中按F5启动Web应用程序。

    3） 打开浏览器，一并打开Rester。

     4) 将 HTTP 方法设置为 GET。将请求 URL 设置为 http://localhost:5000/api/Book/25

    5) 使用鼠标点击“Send”按钮。请求将收到具备做书籍数据的“200 正常”响应。以下图。

   6） 请求无效将收到“204 无内容”响应。 以下图。

 

    配置格式化程序

       若是应用程序须要支持默认 JSON 格式之外的其余格式，那么能够添加 NuGet 包并配置 MVC 来支持它们。输入和输出的格式化程序不一样。输入格式化程序由模型绑定使用；输出格式化程序用来设置响应格式。 还能够配置自定义格式化程序。请求头的Accept中除非指定为application/xml或者application/json，不然指定其它任何MIME，

      添加 XML 格式支持

      在Visual Studio 2017若要添加对 XML 格式的支持，请安装 Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet 包。

     1. 在Visual Studio 2017的菜单>工具>选项对话框中，选择“NuGet包管理器”中的常规，根据本身须要，设置默认包管理格式，以下图。

     2. 在解决方案资源管理器中，右键单击“引用”，选择“管理 NuGet 程序包”，以下图。

 

     3.将“nuget.org”选择为“包源”，选择“浏览”选项卡并搜索“Microsoft.AspNetCore.Mvc.Formatters.Xml”，在列表中选择该包，而后选择“安装”，以下图。

 

      4.在Visual Studio 2017中打开Startup.cs文件，将 XmlSerializerFormatters 配置添加到 Startup类的ConfigureServices方法中。代码以下：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<BookContext>(options =>   options.UseSqlServer(Configuration.GetConnectionString("BookContext"))); 
           services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
                .AddXmlSerializerFormatters();
        }

      或者，能够仅添加输出格式化程序：

services.AddMvc(options =>
{
    options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});

   经过上面的代码咱们添加了对 XML 格式的支持，控制器方法会基于请求的 Accept 标头返回相应的格式。接下来咱们来测试一下。

     1) 在Visual Studio 2017中按F5，启动BookApi应用程序。

     2) 打开Firefox浏览器，并打开 Rester，在Reseter中，将 HTTP 方法设置为 GET。

     3) 选择“Headers”选项卡，选择“Accept”选项，并将值设置为 xml (application/xml)。

     4) 使用鼠标左键，单击“SEND”按钮。 响应返回200，响应窗格显示 Content-Type: application/xml 标头，且 Book 对象已序列化为 XML。以下图。

 

     5) 选择“Headers”选项卡，选择“Accept”选项，并将值设置为 JSON (application/json)。

      6) 使用鼠标左键，单击“SEND”按钮。 响应返回200，响应窗格显示 Content-Type: application/json 标头，且 Book 对象已序列化为 JSON。以下图。从图片中能够看到请求了设置 Accept: application/json 的标头，且响应也将它指定为其 Content-Type。 BOOK 对象以 JSON 格式显示在响应正文中。

     内容协商过程

      内容协商仅在 Accept 标头出如今请求中时发生。 请求包含 accept 标头时，框架会以最佳顺序枚举 accept 标头中的媒体类型，而且尝试查找能够生成一种由 accept 标头指定格式的响应的格式化程序。 若是未找到能够知足客户端请求的格式化程序，框架将尝试找到第一个能够生成响应的格式化程序（除非开发人员配置 MvcOptions 上的选项以返回“406 不可接受”）。 若是请求指定 XML，可是未配置 XML 格式化程序，那么将使用 JSON 格式化程序。 通常来讲，若是没有配置能够提供所请求格式的格式化程序，那么使用第一个能够设置对象格式的格式化程序。 若是不提供任何标头，则将使用第一个能够处理要返回的对象的格式化程序来序列化响应。 在此状况下，没有任何协商发生 - 服务器肯定将使用的格式。

         若是 Accept 标头包含 */*，则将忽略该标头，除非 RespectBrowserAcceptHeader 在 MvcOptions 上设置为 true。