设置 ASP.NET Core Web API 中响应数据的格式 AddNewtonsoftJson 使用NewtonsoftJson替换掉默认的System.Text.Json序列化组件

 #region 使用NewtonsoftJson替换掉默认的json序列化组件
.AddNewtonsoftJson(options =>
{
    修改属性名称的序列化方式，首字母小写
    //options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    修改时间的序列化方式
    //options.SerializerSettings.Converters.Add(new IsoDateTimeConverter() { DateTimeFormat = "yyyy/MM/dd HH:mm:ss" });
    //解决命名不一致问题
    options.SerializerSettings.ContractResolver = new DefaultContractResolver();
});
#endregion

　　

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

查看或下载示例代码（如何下载）

特定于格式的操作结果

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

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

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

C#复制

 

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

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

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

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

C#复制

 

// 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：

C#复制

 

// 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 帮助程序方法：

C#复制

 

// 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 响应。

返回对象类型：

C#复制

 

// 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：

C#复制

 

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

配置格式化程序

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

添加 XML 格式支持

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

C#复制

 

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

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

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

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

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

C#复制

 

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

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

C#复制

 

[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 并添加自定义转换器：

C#复制

 

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 配置基于每个操作的输出序列化选项。 例如：

C#复制

 

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 的格式化程序和功能的支持。

C#复制

 

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 的格式化程序的功能：

C#复制

 

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 配置基于每个操作的输出序列化选项。 例如：

C#复制

 

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

指定格式

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

C#复制

 

[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。

C#复制

 

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 使用的路由中指定。 例如：

C#复制

 

[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 错误的请求) 。

显示较少选项

本文内容

• 特定于格式的操作结果
• 内容协商