ASP.NET Core之Web API介绍_Asp.net

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 中检查该格式的值是否存在，并创建响应时将响应数据映射到相应的格式：

routeformatter

/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的文章就介绍到这了。希望对大家的学习有所帮助，也希望大家多多支持代码网。