设置 ASP.NET Core Web API 中响应数据的格式 AddNewtonsoftJson

ASP.NET Core MVC 支持设置响应数据的格式。可以使用特定格式或响应客户端请求的格式，来设置响应数据的格式。

特定于格式的操作结果

一些操作结果类型特定于特殊格式，例如 JsonResult 和 ContentResult。操作可以返回使用特定格式设置格式的结果，而不考虑客户端首选项。例如，返回 JsonResult 返回 JSON 格式的数据。返回 ContentResult 或字符串，将返回纯文本格式的字符串数据。

无需操作返回任意特定类型。 ASP.NET Core 支持任何对象返回值。对于返回非 IActionResult 类型对象的操作的结果，将使用相应的 IOutputFormatter 实现来对这些结果进行序列化。有关详细信息，请参阅 ASP.NET Core Web API 中的控制器操作返回类型。

内置帮助程序方法 Ok 返回 JSON 格式的数据：

// GET: api/authors
[HttpGet]
public ActionResult Get()
{
    return Ok(_authors.List());
}

示例下载返回作者列表。在 F12 浏览器开发人员工具或 Postman 中使用上述代码：

将显示包含内容类型的响应标头。application/json; charset=utf-8
将显示请求标头。例如 Accept 标头。上述代码将忽略 Accept 标头。

若要返回纯文本格式数据，请使用 ContentResult 和 Content 帮助程序：

// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
    return Content("An API listing authors of docs.asp.net.");
}

在上述代码中，返回的 text/plain 为 Content-Type。返回字符串，将提供 text/plain 类型的 Content-Type：

// GET api/authors/version
[HttpGet("version")]
public string Version()
{
    return "Version 1.0.0";
}

对于包含多个返回类型的操作，将返回 IActionResult。例如，基于执行的操作的结果返回不同的 HTTP 状态代码。

内容协商

当客户端指定 Accept 标头时，会发生内容协商。 ASP.NET Core使用的默认格式为 JSON。内容协商有以下特点：

由 ObjectResult 实现。
内置于从帮助程序方法返回的特定于状态代码的操作结果中。操作结果帮助程序方法基于 ObjectResult。

返回一个模型类型时，返回类型为 ObjectResult。

以下操作方法使用 Ok 和 NotFound 帮助程序方法：

// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    var result = _authors.GetByNameSubstring(namelike);
    if (!result.Any())
    {
        return NotFound(namelike);
    }
    return Ok(result);
}

默认情况下，ASP.NET Core 支持 application/json、text/json 和 text/plain 媒体类型。 Fiddler 或 Postman 等工具可以设置 Accept 请求标头，来指定返回格式。 Accept 标头包含服务器支持的类型时，将返回该类型。下一节将介绍如何添加其他格式化程序。

控制器操作可以返回 POCO（普通旧 CLR 对象）。返回 POCO 时，运行时自动创建包装该对象的 ObjectResult。客户端将获得已格式化和序列化的对象。若将返回的对象为 null，将返回 204 No Content 响应。

返回对象类型：

// GET api/authors/RickAndMSFT
[HttpGet("{alias}")]
public Author Get(string alias)
{
    return _authors.GetByAlias(alias);
}

在前面的代码中，请求有效作者别名将返回具有作者数据的 200 OK 响应。请求无效别名将返回 204 No Content 响应。

Accept 标头

内容协商在 Accept 标头出现在请求中时发生。请求包含 Accept 标头时，ASP.NET Core 将执行以下操作：

按首选顺序枚举 Accept 标头中的媒体类型。
尝试找到可以生成某种指定格式的响应的格式化程序。

若未找到可以满足客户端请求的格式化程序，ASP.NET Core 将指定以下操作：

如果 MvcOptions.ReturnHttpNotAcceptable 设为 true，返回 406 Not Acceptable，否则 -
尝试找到第一个可以生成响应的格式化程序。

如果没有配置实现所请求格式的格式化程序，那么使用第一个可以设置对象格式的格式化程序。若请求中没有 Accept 标头：

将使用第一个可以处理对象的格式化程序来将响应序列化。
不执行任何协商。服务器将决定要返回的格式。

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

浏览器和内容协商

与典型的 API 客户端不同的是，Web 浏览器提供 Accept 标头。 Web 浏览器指定多种格式，包括通配符。默认情况下，当框架检测到请求来自浏览器时，将执行以下操作：

忽略 Accept 标头。
除非另有配置，否则内容在 ON 中 JS返回。

这样，在使用 API 时，各种浏览器中的体验将更加一致。

若要将应用配置为采用浏览器 Accept 标头，请将 RespectBrowserAcceptHeader 设置为 true：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.RespectBrowserAcceptHeader = true; // false by default
    });
}

配置格式化程序

需要支持其他格式的应用可以添加相应的 NuGet 包，并配置支持。输入和输出的格式化程序不同。模型绑定使用输入格式化程序。格式响应使用输出格式化程序。有关创建自定义格式化程序的信息，请参阅自定义格式化程序。

添加 XML 格式支持

调用 AddXmlSerializerFormatters 来配置使用 XmlSerializer 实现的 XML 格式化程序：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddXmlSerializerFormatters();
}

前面的代码将使用 XmlSerializer 将结果序列化。

使用前面的代码时，控制器方法会基于请求的 Accept 标头返回相应的格式。

配置基于 `System.Text.Json` 的格式化程序

可以使用 Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions 配置基于 System.Text.Json 的格式化程序的功能。默认格式为 camelCase。以下突出显示的代码设置 PascalCase 格式：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddJsonOptions(options =>
            options.JsonSerializerOptions.PropertyNamingPolicy = null);
}

以下操作方法调用 ControllerBase.Problem 创建 ProblemDetails 响应：

[HttpGet("error")]
public IActionResult GetError()
{
    return Problem("Something went wrong!");
}

通过使用上述代码：

https://localhost:5001/WeatherForecast/temperature 返回 PascalCase。
https://localhost:5001/WeatherForecast/error 返回 camelCase。错误响应始终为 camelCase 格式，即使应用将格式设置为 PascalCase 也是如此。 ProblemDetails 遵循 RFC 7807，这将指定为小写

以下代码设置 PascalCase 并添加自定义转换器：

services.AddControllers().AddJsonOptions(options =>
{
    // Use the default property (Pascal) casing.
    options.JsonSerializerOptions.PropertyNamingPolicy = null;

    // Configure a custom converter.
    options.JsonSerializerOptions.Converters.Add(new MyCustomJsonConverter());
});

可以使用 JsonResult 配置基于每个操作的输出序列化选项。例如：

public IActionResult Get()
{
    return Json(model, new JsonSerializerOptions
    {
        WriteIndented = true,
    });
}

添加基于 Newtonsoft.Json 的 JSON 格式支持

默认 JSON 格式化程序基于 System.Text.Json。通过安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet 包并在 Startup.ConfigureServices 中进行配置可以实现对基于 Newtonsoft.Json 的格式化程序和功能的支持。

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddNewtonsoftJson();
}

在上述代码中，对 AddNewtonsoftJson 的调用会将以下 Web API、MVC 和 Razor Pages 功能配置为使用 Newtonsoft.Json：

读取和写入 JSON 的输入和输出格式化程序
JsonResult
JSON Patch
IJsonHelper
TempData

某些功能可能不适用于基于 System.Text.Json 的格式化程序，而需要引用基于 Newtonsoft.Json 的格式化程序。当应用符合以下情况时，请继续使用基于 Newtonsoft.Json 的格式化程序：

使用 Newtonsoft.Json 属性。例如，[JsonProperty] 或 [JsonIgnore]。
自定义序列化设置。
依赖 Newtonsoft.Json 提供的功能。

可以使用 Microsoft.AspNetCore.Mvc.MvcNewtonsoftJsonOptions.SerializerSettings 配置基于 Newtonsoft.Json 的格式化程序的功能：

services.AddControllers().AddNewtonsoftJson(options =>
{
    // Use the default property (Pascal) casing
    options.SerializerSettings.ContractResolver = new DefaultContractResolver();

    // Configure a custom converter
    options.SerializerSettings.Converters.Add(new MyCustomJsonConverter());
});

可以使用 JsonResult 配置基于每个操作的输出序列化选项。例如：

public IActionResult Get()
{
    return Json(model, new JsonSerializerSettings
    {
        Formatting = Formatting.Indented,
    });
}

指定格式

应用 [Produces] 筛选器，以限制响应格式。如同大多筛选器，[Produces] 可以在操作层面、控制器层面或全局范围内应用：

[ApiController]
[Route("[controller]")]
[Produces("application/json")]
public class WeatherForecastController : ControllerBase
{

上述 [Produces] 筛选器将执行以下操作：

强制控制器中的所有操作返回 JSPOCO 的 ON 格式响应， (普通旧 CLR 对象) 或其 ObjectResult 派生类型。
如果配置了其他格式化程序，并且客户端指定了不同的格式， JS则返回 ON。

有关详细信息，请参阅筛选器。

特例格式化程序

一些特例是使用内置格式化程序实现的。默认情况下，string如果通过Accept标头) 请求，则返回类型的格式为文本/纯 (文本/html。可以通过删除 StringOutputFormatter 删除此行为。在 ConfigureServices 方法中删除格式化程序。有模型对象返回类型的操作将在返回 null 时返回 204 No Content。可以通过删除 HttpNoContentOutputFormatter 删除此行为。以下代码删除 StringOutputFormatter 和 HttpNoContentOutputFormatter。

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        // requires using Microsoft.AspNetCore.Mvc.Formatters;
        options.OutputFormatters.RemoveType<StringOutputFormatter>();
        options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
    });
}

StringOutputFormatter如果没有内置 JSON 格式化程序格式string，则返回类型。如果删除了内置的 JSON 格式化程序，并且 XML 格式化程序可用，则 XML 格式化程序格式 string 返回类型。否则，string 返回类型返回 406 Not Acceptable。

没有 HttpNoContentOutputFormatter，null 对象将使用配置的格式化程序来进行格式设置。例如：

JSON 格式化程序返回具有正文的null响应。
设置属性 xsi:nil="true" 时，XML 格式化程序返回空 XML 元素。

响应格式 URL 映射

客户端可以在 URL 中请求特定格式，例如：

在查询字符串中，或在路径中。
使用格式特定的文件扩展名，如 .xml 或 .json。

请求路径的映射必须在 API 使用的路由中指定。例如：

[Route("api/[controller]")]
[ApiController]
[FormatFilter]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}.{format?}")]
    public Product Get(int id)
    {

上述路由将允许指定所请求格式为可选文件扩展名。 [FormatFilter] 属性检查 RouteData 中格式值是否存在，并在响应创建时将响应格式映射到相应格式化程序。

路由	格式化程序
`/api/products/5`	默认输出格式化程序
`/api/products/5.json`	如果配置了) ，则 JSON 格式化程序 (
`/api/products/5.xml`	XML 格式化程序（如配置）

建议的内容

ASP.NET Core Web API 中控制器操作的返回类型

ActionResult 与 IActionResult
在 ASP.NET Core 中路由到控制器操作

了解 ASP.NET Core MVC 如何使用路由中间件来匹配传入请求的 URL 并将它们映射到操作。
ASP.NET Web API中的参数绑定 - ASP.NET 4.x

介绍 Web API 如何绑定参数以及如何在 ASP.NET 4.x 中自定义绑定过程。
ASP.NET Web API中的模型验证 - ASP.NET 4.x

ASP.NET 4.x ASP.NET Web API中的模型验证概述。
ASP.NET Core MVC 中的模型验证

了解 ASP.NET Core MVC 和 Razor Pages 中的模型验证。
在 ASP.NET Web API 2

在 ASP.NET Web API 2 中创建具有属性路由的 REST API
ASP.NET Core 中的模型绑定

了解 ASP.NET Core 中模型绑定的工作原理以及如何自定义模型绑定的行为。
ApiController.BadRequest 方法 (System.Web.Http)

创建 (BadRequestResult 400 错误的请求) 。

本文内容

标签：返回,Core,ASP,格式化,Web,程序,格式,NET
From： https://www.cnblogs.com/webenh/p/16995607.html

设置 ASP.NET Core Web API 中响应数据的格式 AddNewtonsoftJson

特定于格式的操作结果

内容协商

Accept 标头

浏览器和内容协商

配置格式化程序

添加 XML 格式支持

配置基于 `System.Text.Json` 的格式化程序

添加基于 Newtonsoft.Json 的 JSON 格式支持

指定格式

特例格式化程序

响应格式 URL 映射

建议的内容

ASP.NET Core Web API 中控制器操作的返回类型

在 ASP.NET Core 中路由到控制器操作

ASP.NET Web API中的参数绑定 - ASP.NET 4.x

ASP.NET Web API中的模型验证 - ASP.NET 4.x

ASP.NET Core MVC 中的模型验证

在 ASP.NET Web API 2

ASP.NET Core 中的模型绑定

ApiController.BadRequest 方法 (System.Web.Http)

相关文章

赞助商

阅读排行

设置 ASP.NET Core Web API 中响应数据的格式 AddNewtonsoftJson

特定于格式的操作结果

内容协商

Accept 标头

浏览器和内容协商

配置格式化程序

添加 XML 格式支持

配置基于 System.Text.Json 的格式化程序

添加基于 Newtonsoft.Json 的 JSON 格式支持

指定格式

特例格式化程序

响应格式 URL 映射

建议的内容

ASP.NET Core Web API 中控制器操作的返回类型

在 ASP.NET Core 中路由到控制器操作

ASP.NET Web API中的参数绑定 - ASP.NET 4.x

ASP.NET Web API中的模型验证 - ASP.NET 4.x

ASP.NET Core MVC 中的模型验证

在 ASP.NET Web API 2

ASP.NET Core 中的模型绑定

ApiController.BadRequest 方法 (System.Web.Http)

相关文章

赞助商

阅读排行

配置基于 `System.Text.Json` 的格式化程序