ASP.NET Core Web API

Posted afei-24

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了ASP.NET Core Web API相关的知识,希望对你有一定的参考价值。

1.简单介绍

  ASP.NET Core Web API 是 ASP.NET Core MVC 的一个功能。ASP.NET Core MVC 包含了对 Web API 的支持。可以构建多种客户端的 HTTP 服务。ASP.NET Core Web API可用于在 .NET Core 上构建 RESTful 应用程序。

  框架包含对 HTTP 内容协商的支持,内置支持以 JSON 或 XML 格式化的数据。编写自定义格式化程序已添加对自有格式的支持。

  使用链接生成对超媒体的支持。启用对跨资源共享(CORS)的支持,以便 Web API 可以在多个 Web应用程序之间共享。

  例如,新建一个 API 项目,默认包含一个 ValuesController:

    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        
            return new string[]  "value1", "value2" ;
        

        // GET api/values/5
        [HttpGet("id")]
        public ActionResult<string> Get(int id)
        
            return "value";
        

        // POST api/values
        [HttpPost]
        public void Post([FromBody] string value)
        
        

        // PUT api/values/5
        [HttpPut("id")]
        public void Put(int id, [FromBody] string value)
        
        

        // DELETE api/values/5
        [HttpDelete("id")]
        public void Delete(int id)
        
        
    

  默认包含了 GET,POST,PUT,DELETE 这几个 HTTP 请求操作。这里直接使用特性路由,在控制器上注明 [Route("api/[controller]")]。调试并打开浏览器输入 https://localhost:5000/api/values ,会返回数据。

 

2.自定义格式化(Format)

  ASP.NET Core MVC内建支持对相应数据的格式,用来修正格式或生成客户端指定的格式。

  1.特定格式的操作结果

  某些操作结果的类型是特定的格式,比如 JsonResult 或 ContentResult 。操作可以总是返回格式为特定格式的具体结果。比如返回 JsonResult 时将返回 JSON 格式化数据,而不管客户端要求的是什么格式。

  操作并不要求返回任何特定的类型, MVC 支持任何对象作为返回值。如果操作返回的是 IActionResult 的某个实现,并且控制器继承自 Controller ,那么可以使用更多辅助方法。如果不是,则将使用合适的 IOutputFormatter 实现序列化对象。

  若要从继承 Controller 基类的控制器返回特定格式的数据,可以使用内置的辅助方法 Json 来返回 JSON 格式, 使用 Content 来返回 纯文本。操作方法的返回类型必须是指定的结果类型(如 JsonResult)或 IActionResult。

[HttpGet]
        public JsonResult Get()
        
            return Json(new User());
        

  以上代码 Content-Type 将返回 application/json。

  要想返回纯文本格式的数据,则使用 ContentResult 以及 Content 辅助方法:

[HttpGet]
        public ContentResult Get()
        
            return Content("result");
        

  以上代码 Content-Type 将返回  test/plan 。 也可以使用一个字符串相应类型来实现这个行为:

[HttpGet]
        public string Get()
        
            return "result";
        

  对于具有多个返回类型或选项的复杂操作,请选择 IActionResult 作为返回类型。

  

  2.配置格式化程序

  如果应用程序想支持默认 JSON 之外的格式,可以在 project.json 文件中添加这些额外的依赖项,并配置 MVC 来支持。输入和输出的格式是可以隔离的。输入格式通过使用模型绑定,输出格式通过格式化响应。

 

  3.添加对 XML 格式的支持

  要添加对 XML 格式的支持,需要先安装 Microsoft.AspNetCore.Mvc.Formatters.Xml 包,然后在 ConfigureServices 中配置 XmlSerializerFormatters :

services.AddMvc()
                .AddXmlSerializerFormatters()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

  或者可以只添加输出格式:

services.AddMvc(options => 
                options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
            )
                //.AddXmlSerializerFormatters()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

  这两种方法都将使用 System.Xml.Serialization.XmlSerializer 序列化结果。还可以通过添加其他相关格式来使用 System.Runtime.Serialization.DataContractSerializer :

            services.AddMvc(options => 
                options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
            )
                //.AddXmlSerializerFormatters()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

 

  4.强制特定格式化

  若是想为某个操作限制响应格式,则可以使用 [Produces] 过滤器。[Produces] 过滤器可以为这个控制器或 Action 指定响应格式:

[HttpGet("id", Name = "Get")]
        [Produces("application/json")]
        public string Get(int id)
        
            return "value";
        

  对于一些特殊情况,可能不想使用内建的格式化实现。默认情况下,返回类型为 string 时将格式化为 text/plain 。这种行为可以通过移除 TextOutputFormatter 来改变:

        public void ConfigureServices(IServiceCollection services)
        
            services.AddMvc(options => 
                options.OutputFormatters.RemoveType<TextOutputFormatter>();
                options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
            ).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        

  上面移除了 TextOutputFormatter 和 HttpNoContentOutputFormatter,当返回类型为 string 时,将返回 406 Not Acceptable。如果存在 XML 格式化程序,则将格式化响应结果。

  移除了 HttpNoContentOutputFormatter ,当返回某个返回类型为模型对象的操作返回 null 时,将返回 204 No Content 响应。JSON 格式将简单地返回主体信息为 null 的响应,而 XML 格式将返回一个空的带有 xsi:nil="true" 属性的 XML 元素。

 

  5.响应格式 URL 映射

  客户端可以在 URL 中请求特定的格式,比如在请求字符串或路径中,或者通过使用特定格式的文件扩展名(比如 .xml 或 .json),需要在 API 所使用的路由中指定:

    [FormatFilter]
    public class UserController : Controller
    
        // GET: api/User
        [HttpGet]
        [Route("[controller]/[action]/id.format?")]
        public IActionResult GetById(int id)
        
            return Content("xxx");
        

  这个路由配置将允许使用可选的文件扩展名来指定格式。[FormatFilter] 特性将在 RouteData 中检查该格式的值是否存在,并创建响应时将响应数据映射到相应的格式:

Route    Formatter

/User/GetById/5 :默认输出格式

/User/GetById/5.json :JSON格式(如果配置过)

/User/GetById/5.xml; :XML格式(如果配置过)

 

  6.自定义格式化程序 Protocol Buffers (简称 protobuf)

  Protocol Buffers 是一种轻便高效的结构化数据存储格式,可用于结构化数据串行化,或者说序列化。它很适合做数据存储或 RPC(远程过程调用协议)数据交换格式。可用于通讯协议,数据存储等领域的语言无关,平台无关,可扩展的序列化结构数据格式。比如实现一个程序返回 protobuf 格式:

  创建 API 项目,添加 protobuf-net 引用。

  添加 ProtobufFormatter 类:

    public class ProtobufFormatter:OutputFormatter
    
        public string ContentType  get; private set; 
        public ProtobufFormatter()
        
            ContentType = "application/proto";
            SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("application/proto"));
        

        public override Task WriteResponseBodyAsync(OutputFormatterWriteContext context)
        
            if (context == null)
            
                throw new ArgumentNullException(nameof(context));
            
            var response = context.HttpContext.Response;
            Serializer.Serialize(response.Body,context.Object);
            return Task.FromResult(0);
        

    

  继承 OutputFormatter ,然后实现 WriteResponseBodyAsync 方法,初始化时赋值 ContentType ,并添加支持 MediaType。在 WriteResponseBodyAsync 方法中获取 Response ,调用 protobuf-net 的 Serializer.Serialize 方法将 Object 序列化至输出内容。 protobuf 在序列化时必须指定顺序,添加 User 类,实现 protobuf 实体:

    [ProtoContract]
    public class User
    
        [ProtoMember(1)]
        public int Id  get; set; 
        [ProtoMember(2)]
        public string Name  get; set; 
        [ProtoMember(3)]
        public int Age  get; set; 
    

  类上需要添加 [ProtoContract] 特性,字段上需要 ProtoMember 特性,并指定顺序。然后修改 UserController:

    [Route("api/[controller]")]
    [ApiController]
    [FormatFilter]
    public class UserController : Controller
    
        private IEnumerable<User> users;
        public UserController()
        
            users = new User[] 
                new User() Id=1,Name="Bob",Age = 20,
                new User() Id=2,Name="Tom",Age = 22
            ;
        
        // GET: api/User
        [HttpGet]
        [Produces("application/proto")]
        public IEnumerable<User> Get()
        
            return users;
        

  修改 ConfigureServices :

        public void ConfigureServices(IServiceCollection services)
        
            services.AddMvc(options => 
                options.OutputFormatters.Add(new ProtobufFormatter());
            ).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        

  运行程序,会返回一个二进制文件。

  创建一个控制台,检查序列化:

    class Program
    
        static void Main(string[] args)
        
            HttpClient client = new HttpClient();
            var stream = client.GetStreamAsync("https://localhost:44358/api/User").Result;
            var users = Serializer.Deserialize<List<User>>(stream);
            foreach (var user in users)
            
                Console.WriteLine($"Id:user.Id - Name:user.Name - Age:user.Age");
            
            Console.ReadKey();
        
    

 

 

  

 

以上是关于ASP.NET Core Web API的主要内容,如果未能解决你的问题,请参考以下文章

ASP.NET Core 入门教程 1使用ASP.NET Core 构建第一个Web应用

asp.net web.Config 配置httpHandlers无效 求解,在线等!

ASP.NET Core Web 应用程序系列- 在ASP.NET Core中使用AutoMapper进行实体映射

ASP.NET Core Web Api 自动帮助页面

ASP.NET Core 实战:使用 ASP.NET Core Web API 和 Vue.js 搭建前后端分离项目

ASP.NET Web API 与 ASP.NET Core 中的 URL 匹配差异