ASP.NET Core WebAPI响应数据的格式设置

最新推荐文章于 2023-09-03 11:25:25 发布
最新推荐文章于 2023-09-03 11:25:25 发布
阅读量3.2k 收藏
点赞数
分类专栏： ASP.NET Core Web API 文章标签： asp.net
原文链接：https://blog.csdn.net/WuLex
版权

ASP.NET Core WebAPI响应数据的格式设置

原文参考链接：https://docs.microsoft.com/zh-cn/aspnet/core/web-api/advanced/formatting?view=aspnetcore-2.2

当Web API控制器操作返回结果时，可以对结果进行格式设置。

特定于格式的操作结果

这类操作结果的类型特定于特殊格式，例如JsonResult和ContentResult。

返回非 IActionResult 类型对象的操作结果将使用相应的 IOutputFormatter 实现来进行序列化。

对于有多个返回类型或选项的重要操作（例如基于所执行操作的结果的不同 HTTP 状态代码），请首选 IActionResult 作为返回类型。

内容协商（Content Negotiation）

当客户端指定 Accept 标头时，会发生内容协商（简称 conneg）。

ASP.NET Core MVC 使用的默认格式是 JSON。

内容协商由 ObjectResult 实现，并且还内置于从帮助程序方法（全部基于 ObjectResult）返回的特定于状态代码的操作结果中。 还可以返回一个模型类型（已定义为数据传输类型的类），框架将自动将其打包在 ObjectResult 中。

例如，下述代码中使用了OK()和NotFound()帮助程序方法：

[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    if (_context.TodoItems.Any(a => a.Name == namelike))
    {
        return Ok();
    }
    return NotFound(namelike);
}

这两个方法都将返回JSON格式的响应。

默认情况下，ASP.NET Core MVC 仅支持 JSON。所以，即使指定另一种格式，返回的结果仍然是 JSON 格式。（可以通过配置格式化程序改变这一行为，但是大多数情况下，不需要进行格式化配置）

即使控制器操作返回的是一个普通的类对象（例如Student），在这种情况下，ASP.NET Core MVC 将自动创建打包对象的 ObjectResult。 客户端将获取设有格式的序列化对象（默认为 JSON 格式，可以配置 XML 或其他格式）。 如果返回的对象为 null，那么框架将返回 204 No Content 响应。

例如：

public Student Get(string stuNo)
{
    return GetByStudent(stuNo);
}

上述代码中，如果获取到有效的Student，将会返回“200 正常”响应，如果获取的是null，将会返回“204 无内容”响应。

注意：该示例更加说明了不同的HTTP状态码特定于不同的场景，实际中应该结合相应的场景，使用特定于此场景的具有语义的HTTP状态码对应的返回IActionResult的方法。

内容协商过程

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

说明：

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

浏览器和内容协商

不同于传统 API 客户端，Web 浏览器倾向于提供包括各种格式（含通配符）的 Accept 标头。 默认情况下，当框架检测到请求来自浏览器时，它将忽略 Accept 标头转而以应用程序的配置默认格式（JSON，除非有其他配置）返回内容。 这在使用不同浏览器使用 API 时提供更一致的体验。

如果首选应用程序服从浏览器 accept 标头，则可以将此配置为 MVC 配置的一部分，方法是在 Startup.cs 中以 ConfigureServices方法将 RespectBrowserAcceptHeader 设置为 true。

services.AddMvc(options =>
{
   options.RespectBrowserAcceptHeader = true; // 默认为false
});

配置格式化程序

如果应用程序需要支持默认 JSON 格式以外的其他格式，那么可以添加 NuGet 包并配置 MVC 来支持它们。

输入和输出的格式化程序不同：输入格式化程序由模型绑定使用；输出格式化程序用来设置响应格式。

添加 XML 格式支持

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

将 XmlSerializerFormatters 添加到 Startup.cs 中 MVC 的配置：

services.AddMvc()
    .AddXmlSerializerFormatters();

或者，可以仅添加输出格式化程序：

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

这两个方法将使用 System.Xml.Serialization.XmlSerializer 来序列化结果。 如果愿意，可以通过添加相关联的格式化程序使用 System.Runtime.Serialization.DataContractSerializer：

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

强制执行特定格式

如果需要限制特定操作的响应格式，那么可以应用 [Produces] 筛选器。 [Produces] 筛选器指定特定操作（或控制器）的响应格式。 如同大多筛选器，这可以在操作层面、控制器层面或全局范围内应用。

[Produces("application/json")]
public class AuthorsController

[Produces] 筛选器将强制 AuthorsController 中的所有操作返回 JSON 格式的响应，即使已经为应用程序配置其他格式化程序且客户端提供了请求其他可用格式的 Accept 标头也是如此。

特例格式化程序

一些特例是使用内置格式化程序实现的。 默认情况下，string 返回类型的格式将设为 text/plain（如果通过 Accept 标头请求则为 text/html）。可以通过删除 TextOutputFormatter 删除此行为。 有模型对象返回类型的操作将在返回 null 时返回“204 无内容”响应。 可以通过删除 HttpNoContentOutputFormatter 删除此行为。（具体见下述示例）

在 Startup.cs 中通过 Configure 方法删除格式化程序，以下代码删除 TextOutputFormatter 和 HttpNoContentOutputFormatter：

services.AddMvc(options =>
{
    options.OutputFormatters.RemoveType<TextOutputFormatter>();
    options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});

没有 TextOutputFormatter 时，string 返回类型将返回“406 不可接受”等内容。 请注意，如果 XML 格式化程序存在，当删除 TextOutputFormatter 时，它将设置 string 返回类型的格式。

没有 HttpNoContentOutputFormatter，null 对象将使用配置的格式化程序来进行格式设置。 例如，JSON 格式化程序仅返回正文为 null 的响应，而 XML 格式化程序将返回属性设为 xsi:nil="true" 的空 XML 元素。

响应格式URL文件扩展名映射

客户端可要求特定格式作为 URL 一部分，例如在查询字符串中或在路径的一部分中，或者通过使用特定格式的文件扩展名（例如 .xml 或 .json）。 请求路径的映射必须在 API 使用的路由中指定。 例如:

[FormatFilter]
public class ProductsController
{
    [Route("[controller]/[action]/{id}.{format?}")]
    public Product GetById(int id)

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

路由格式化程序
/products/GetById/5默认输出格式化程序
/products/GetById/5.jsonJSON 格式化程序（如配置）
/products/GetById/5.xmlXML 格式化程序（如配置）

自定义格式化程序

默认情况下，ASP.NET Core MVC 使用 JSON 或 XML，为 Web API 中的数据交换提供内置支持。通过创建自定义格式化程序，可以添加对其他格式的支持。例如上文中提到的内容协商，如果希望在内容协商的过程中支持内置格式化程序（JSON 和 XML）所不支持的其他内容类型，可使用自定义格式化程序。

创建和使用自定义格式化程序的步骤

  • 如果想对服务器端发送的数据进行序列化，则创建输出格式化程序类
  • 如果想对服务器端接收的数据进行反序列化，则创建输入格式化程序类
  • 将格式化程序的实例添加到 MvcOptions 中的 InputFormatters 和 OutputFormatters 集合

创建自定义格式化程序类

若要创建格式化程序，需要执行以下操作：

  • 创建派生自相应基类的程序类
  • 在构造函数中指定有效的媒体类型和编码
  • 重写 CanReadType/CanWriteType(或CanWriteResult) 方法
  • 重写 ReadRequestBodyAsync/WriteResponseBodyAsync 方法
第一步：创建派生自相应基类的程序类
第二步：在构造函数中，指定有效的媒体类型和编码

在构造函数中，通过添加到 SupportedMediaTypes 和 SupportedEncodings 集合来指定有效的媒体类型和编码。

VcardOutputFormatter.cs：

public class VcardOutputFormatter : TextOutputFormatter
{
    public VcardOutputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }
}

VcardInputFormatter.cs：

public class VcardInputFormatter : TextInputFormatter
{
    public VcardInputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }
}

**注意：**不能在格式化程序类中执行构造函数依赖关系注入。 例如，不能通过向构造函数添加记录器参数来获取记录器。 若要访问服务，必须使用传递到方法的上下文对象。 下文中的代码示例（见第四步）展示了如何执行此操作。

第三步：重写 CanReadType/CanWriteType（或CanWriteResult）方法

通过重写 CanReadType 或 CanWriteType 方法，指定可反序列化为的类型，或从其序列化的类型。

下面示例指定只能从Contact类型创建vCard文本，反之亦然：

VcardOutputFormatter.cs：

public class VcardOutputFormatter : TextOutputFormatter
{
    public VcardOutputFormatter()
    {
       ...//见上文代码
    }

    protected override bool CanWriteType(Type type)
    {
        if (typeof(Contact).IsAssignableFrom(type) 
            || typeof(IEnumerable<Contact>).IsAssignableFrom(type))
        {
            return base.CanWriteType(type);
        }
        return false;
    }
}

VcardInputFormatter.cs：

public class VcardInputFormatter : TextInputFormatter
{
    public VcardInputFormatter()
    {
        ...//见上文
    }

    protected override bool CanReadType(Type type)
    {
        if (type == typeof(Contact))
        {
            return base.CanReadType(type);
        }
        return false;
    }
}
CanWriteResult 方法

在某些情况下，必须重写 CanWriteResult，而不是 CanWriteType。 如果同时满足以下条件，则使用 CanWriteResult：

  • 操作方法返回模型类。
  • 具有可能在运行时返回的派生类。
  • 需要知道操作在运行时返回了哪个派生类。

例如，假设操作方法签名返回 Person 类型，但它可能返回从 Person 派生的 Student 或 Instructor 子类型。 如果希望格式化程序仅处理 Student 对象，请检查提供给 CanWriteResult 方法的上下文对象中的OutputFormatterCanWriteContext类型。 请注意，当操作方法返回 IActionResult 时，不必使用 CanWriteResult；在这种情况下，CanWriteType 方法可接收运行时类型。

第四步：重写 ReadRequestBodyAsync/WriteResponseBodyAsync 方法

实际的反序列化或序列化工作在 ReadRequestBodyAsync 或 WriteResponseBodyAsync 中执行。

下述代码展示了如何从依赖关系注入容器中获取服务（不能从构造函数参数中获取它们）。

VcardOutputFormatter.cs：

public class VcardOutputFormatter : TextOutputFormatter
{
    public VcardOutputFormatter()
    {
    	...//见上文
    }

    protected override bool CanWriteType(Type type)
    {
    	...//见上文
    }

    public override async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        IServiceProvider serviceProvider = context.HttpContext.RequestServices;
        var logger = serviceProvider.GetService(typeof(ILogger<VcardOutputFormatter>)) as ILogger;

        var response = context.HttpContext.Response;

        var buffer = new StringBuilder();
        if (context.Object is IEnumerable<Contact>)
        {
            foreach (Contact contact in context.Object as IEnumerable<Contact>)
            {
                FormatVcard(buffer, contact, logger);
            }
        }
        else
        {
            var contact = context.Object as Contact;
            FormatVcard(buffer, contact, logger);
        }
        await response.WriteAsync(buffer.ToString());
    }

    private static void FormatVcard(StringBuilder buffer, Contact contact, ILogger logger)
    {
        buffer.AppendLine("BEGIN:VCARD");
        buffer.AppendLine("VERSION:2.1");
        buffer.AppendFormat($"N:{contact.LastName};{contact.FirstName}\r\n");
        buffer.AppendFormat($"FN:{contact.FirstName} {contact.LastName}\r\n");
        buffer.AppendFormat($"UID:{contact.ID}\r\n");
        buffer.AppendLine("END:VCARD");
        logger.LogInformation($"Writing {contact.FirstName} {contact.LastName}");
    }
}

VcardInputFormatter.cs：

public class VcardInputFormatter : TextInputFormatter
{
    public VcardInputFormatter()
    {
    	...//见上文
    }

    protected override bool CanReadType(Type type)
    {
    	...//见上文
    }

    public override async Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context, Encoding effectiveEncoding)
    {
        if (context == null)
        {
            throw new ArgumentNullException(nameof(context));
        }

        if (effectiveEncoding == null)
        {
            throw new ArgumentNullException(nameof(effectiveEncoding));
        }

        var request = context.HttpContext.Request;

        using (var reader = new StreamReader(request.Body, effectiveEncoding))
        {
            try
            {
                await ReadLineAsync("BEGIN:VCARD", reader, context);
                await ReadLineAsync("VERSION:2.1", reader, context);

                var nameLine = await ReadLineAsync("N:", reader, context);
                var split = nameLine.Split(";".ToCharArray());
                var contact = new Contact() { LastName = split[0].Substring(2), FirstName = split[1] };

                await ReadLineAsync("FN:", reader, context);

                var idLine = await ReadLineAsync("UID:", reader, context);
                contact.ID = idLine.Substring(4);

                await ReadLineAsync("END:VCARD", reader, context);

                return await InputFormatterResult.SuccessAsync(contact);
            }
            catch
            {
                return await InputFormatterResult.FailureAsync();
            }
        }
    }

    private async Task<string> ReadLineAsync(string expectedText, StreamReader reader, InputFormatterContext context)
    {
        var line = await reader.ReadLineAsync();
        if (!line.StartsWith(expectedText))
        {
            var errorMessage = $"Looked for '{expectedText}' and got '{line}'";
            context.ModelState.TryAddModelError(context.ModelName, errorMessage);
            throw new Exception(errorMessage);
        }
        return line;
    }
}

将 MVC 配置为使用自定义格式化程序

若要使用自定义格式化程序，需要将格式化程序类的实例添加到 InputFormatters 或 OutputFormatters 集合。

services.AddMvc(options =>
{
    options.InputFormatters.Insert(0, new VcardInputFormatter());
    options.OutputFormatters.Insert(0, new VcardOutputFormatter());
})
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

按格式化程序的插入顺序对其进行计算。 第一个优先。

该程序运行说明：

若要查看 vCard 输出，请运行该应用程序，并向 http://localhost:63313/api/contacts/（从 Visual Studio 运行时）或 http://localhost:5000/api/contacts/（从命令行运行时）发送具有 Accept 标头“text/vcard”的 Get 请求。
若要将 vCard 添加到内存中联系人集合，请向相同的 URL 发送具有 Content-Type 标头“text/vcard”且正文中包含 vCard 文本的 Post 请求，格式化方式与上面的示例类似。

.NET跨平台
关注
专栏目录
webapi接收Post-Body- text或text/plain 的请求
yangshiqing的专栏
07-20 3464
需求是提供一个WEBAPI给对方平台调用，对方平台只能按照POST方式，参数放在BODY中，格式是Text或Text/plain。效果如下图 但是在调试过程中，发现但是string无法接收Text或Text/plain，一直是NULL。经查询资料，发现普通的webapi 是不支持这个请求的。需要进行格式定义，借鉴https://www.cnblogs.com/chenhuzi/p/61233...
ASP.NET Core Web API设置响应输出的Json数据格式的两种方式
最新发布
专注于C#/.NET/.NET Core学习、工作、面试干货和实战教程分享。这里聚焦了大量的C#/.NET/.NET Core优质文章、开源项目、实用工具和学习、工作、面试心得。
07-19 1541
在ASP.NET Core Web API中设置响应输出Json数据格式有两种方式，可以通过添加或JSON序列化和反序列化库在应用程序中全局设置接口响应的Json数据格式，本文示例使用的是新的Minimal API模式。
ASP.NET Core中的响应时间标头
寒冰屋的专栏
11-27 544
在本技巧中，您将学习如何在ASP.NET Core中添加执行时间作为响应标头。
ASP.NET Core 自定义响应报文头
生活在底层的低级码农
03-04 1631
新建一个中间件 public async Task Invoke(HttpContext httpContext) { // set Headers httpContext.Response.Headers.Add("Server", new StringValues("Apache-Coyote/1.1")); httpContext.Response.Headers.A...
ASP.NET Core Web API 描述文档-使用Swagger
zhulongxi的博客
12-09 8206
1.获取Swagger的引用包： 右击项目：Manage Nuget Packages: 输入Swashbuckle： 点击安装 2.将Swagger加入到.net core的中间件Middleware中： startup.cs： public void ConfigureServices(IServiceCollection services) { // Ad
详解ASP.NET Core WebApi 返回统一格式参数
10-17
在ASP.NET Core Web API开发中，确保返回的响应数据具有统一的格式是非常重要的，这有助于提高接口的可读性、可维护性和用户体验。本篇文章将详细介绍如何在ASP.NET Core WebAPI中实现返回统一格式参数。 首先，...
ASP.NET Core WebApi中使用FluentValidation验证数据模型的方法
01-20
ASP.NET Core WebAPI中使用FluentValidation验证数据模型是一种高效且灵活的方式，它极大地简化了对用户输入数据的验证过程。FluentValidation库允许开发者创建强类型的验证规则，使得代码更加整洁，易于维护。 ...
ASP.NET Core Web API，具有单个控制器的多个Get或Post方法
04-05
ASP.NET Core Web API 是微软开发的一个用于构建网络API的强大框架，尤其适用于跨平台的应用服务。在ASP.NET Core中，Web API控制器是实现HTTP操作（如GET、POST等）的主要组件。本文将深入探讨如何在一个控制器中...
使用ASP.NET Core 5.0构建WebApi框架源码
05-14
ASP.NET Core 5.0是微软推出的一个跨平台的开源框架，用于构建现代云应用程序，包括WebAPI。相比之前的3.0版本，5.0带来了许多改进和新特性，使得开发更加高效且易于维护。本篇文章将深入探讨如何使用ASP.NET Core ...
.net core webapi通过中间件获取请求和响应内容的方法
01-02
本文主要根据中间件来实现对.net core webapi中产生的请求和响应数据进行获取并存入日志文件中； 这里不详细介绍日志文件的使用。你可以自己接入NLog,log4net，Exceptionless等 创建接口记录的中间件 using ...
webapi 支持 text/plain 请求
weixin_30747253的博客
12-01 338
今天遇到一个需求，请求以HTTPS + XML 访问我的API ,普通的webapi 是不支持这个请求的，故做以下代码进行支持 新增一个类，类名为PlainTextTypeFormatter public class PlainTextTypeFormatter : MediaTypeFormatter { public PlainTextTypeFormatter() ...
.Net Core WebApi返回的json数据，自定义日期格式
飞翔的学习笔记
02-02 1507
基本上所有的人都在DateTime类型的字段，被序列化成json的时候，遇到过可恨的Date(1294499956278+0800)；但是又苦于不能全局格式化设置，比较难受。以往的方式，要么使用全局的Newtonsoft的配置，要么自己重写ActionResult，总之都比较麻烦。在Core提供了更为简单更为明了的办法；不多说，直接上代码！ //代码位置：Startup.cs public vo...
添加.net core web Api 对XML数据格式的支持
魍魉
09-03 1573
.net core web api 添加对XML数据格式的支持
c# webapi处理请求文件接口返回的Content-Type →text/plain
DearXia的博客
09-03 2701
c# webapi处理请求文件接口返回的Content-Type →text/plain通过Header中的Content-Disposition属性获取文件名称和扩展名称HttpWebResponseWebClient 通过Header中的Content-Disposition属性获取文件名称和扩展名称 HttpWebResponse HttpWebResponse response = request.GetResponse() as HttpWebResponse; //文件名称 string f
webapi接收text/plain数据（笔记）
u014170719的博客
08-28 1055
新建类TextPlainType，继承InputFormatter。Program注册该类。
webapi从js取值（webapi从request取值）
图纸的博客
04-03 758
首先打印对象request 然后发现值存在这里，就直接用form取值就行了 var request = HttpContext.Current.Request; var ss = request.Form["selectid"];
.Net Core WebApi返回日期格式的问题
design_in_1988的博客
11-05 1757
环境：.net core 2.1 webapi 问题简介： 返回DateTime，前端接收到的字符有时候为2018-01-01T12:01:01，有时候为2018-01-01T01:01:01.722+08:00，无法正常解析 原因： WebApi的Json解析采用的是NewtonSoft的Json.net类库，其格式化日期默认采用的是ISO-8601 格式，该标准规定，日期...
06 Response对象的encoding属性修改字符编码格式
weixin_63986098的博客
06-18 2121
爬虫的第一步是获取网页。 获取网页主要有以下6步： 1.找到要爬取的网址； 2.找到网站的字符编码格式； 3.发送网络请求； 4.打印状态码检验请求是否成功； 5.修改字符编码格式； 6.查看HTML代码。 ...
webapi中配置返回的时间数据格式
weixin_30955617的博客
07-18 405
webapi返回的是标准格式UTC时间，如果要转成我们需要的格式，可以在WebApiConfig.cs的Register函数中新增以下配置来定义返回的时间类型格式： //配置返回的时间类型数据格式 GlobalConfiguration.Configuration.Formatters.JsonFormatter.SerializerSettings.Converters.Add( ...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值