Web API

12
OVERVIEW

CREATING AND USING ODATA SERVICES
USING AZURE FUNCTIONS
SUMMARY

概述

Web API目标是使一种通信技术非常灵活并满足所有需求。WCF最初基于SOAP（简单对象访问协议）。如今，我们有许多场景，不需要强大的SOAP增强功能。对于更简单的场景，例如返回JSON的HTTP请求，WCF太复杂了。
Web API提供基于Representational State Transfer（REST）的简单通信技术。REST是一种基于某些约束的架构风格。比较基于REST架构风格的服务与使用SOAP的服务的不同。
相同：

使用SOAP协议的服务和REST服务都使用客户端 - 服务器技术。

不同：

SOAP服务可以是有状态的，也可以是无状态的; REST服务始终是无状态的。
SOAP定义了自己的消息格式，带有标题和正文以选择服务的方法。
使用REST，可以使用GET，POST，PUT和DELETE等HTTP谓词。 GET用于检索资源，POST用于添加新资源，PUT用于更新资源，DELETE用于删除资源。

This chapter takes you through a journey that covers various important aspects of the Web API using ASP.NET Core MVC—creating a service, using different routing methods, creating a client, using OData, securing the service, and using custom hosts. The chapter shows you how you can take the same services created for hosting with ASP.NET Core and use them from Microsoft Azure Functions, which is another option to create a Web API with C# and .NET.

本章将向您介绍使用ASP.NET Core MVC创建服务，使用不同路由方法，创建客户端，使用OData，保护服务和使用自定义主机的Web API的各个重要方面的旅程。本章向您展示了如何使用ASP.NET Core为托管创建的相同服务，并从Microsoft Azure Functions中使用它们，这是使用C＃和.NET创建Web API的另一种选择。

服务

使用默认模板创建WebApi。

`在较大的应用程序中，建议分离为多个库。
如果您创建包含services和models的库，则可以轻松地使用来自不同技术的相同类型（例如，Web API项目以及Azure Functions）。
Web Api 的实现(控制器——controller)也可以从宿主应用程序单独分离出来。`

定义模型

代码: BookChapter.cs

创建服务

定义服务接口
代码: IBookChaptersService.cs(sync部分)

定义服务，用于检索，添加和更新书籍章节。
代码: BookChaptersService.cs(sync部分)

创建SampleChapters，用来填充数据。
代码: SampleChapters.cs

在宿主应用程序中，使用DI注册服务。
代码: Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    IMvcBuilder mvcBuilder = services.AddMvc();
    mvcBuilder.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    #region 改变响应格式
    mvcBuilder.AddXmlSerializerFormatters();
    #endregion
    #region 注册服务
    // BookChaptersService作为单例注册，所以可以同时从多个线程访问它;
    // 这就是为什么在实现中需要ConcurrentDictionary的原因
    services.AddSingleton();
    services.AddSingleton();
    #endregion
}

调用SampleChapters，以便检索。
代码: Startup.cs

public void Configure(IApplicationBuilder app, IHostingEnvironment env,SampleChapters sampleChapters)
{
    //..
    sampleChapters.CreateSampleChapters();
}

创建控制器

代码：BookChaptersController.cs

运行效果

改变响应格式

返回XML——配置如下：

//改变响应格式
[Produces("application/json","application/xml")]
[Route("api/[controller]")]
// [ApiController]
public class BookChaptersController : Controller
{
}

public void ConfigureServices(IServiceCollection services)
{
    IMvcBuilder mvcBuilder = services.AddMvc();
    mvcBuilder.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    #region 改变响应格式
    mvcBuilder.AddXmlSerializerFormatters();
    #endregion
    #region 注册服务
    // BookChaptersService作为单例注册，所以可以同时从多个线程访问它;
    // 这就是为什么在实现中需要ConcurrentDictionary的原因
    services.AddSingleton();
    services.AddSingleton();
    #endregion
}

REST 结果和状态代码(Status Code)

HTTP方法返回的结果：

Http Method	Description	Request Body	Response Body
GET	返回资源	Empty	The resource
POST	增加资源	The resource to add	The resource
PUT	更新资源	The resource to update	None
DELETE	删除资源	Empty	Empty

下表显示了重要的HTTP状态代码。Controller方法返回的实例化对象（带有状态代码）。如果想返回任意的HTTP状态代码，可以返回一个HttpStatusCodeResult对象，该对象可以使用自己需要的状态代码进行初始化：

Http Status Code	Controller Method	Type
200 OK	Ok	OkResult
201 Created	CreatedAtRoute	CreatedAtRouteResult
204 No Content	NoContent	NoContentResult
400 Bad Request	BadRequest	BadRequestResult
401 Unauthorized	Unauthorized	UnauthorizedResult
404 Not Found	NotFound	NotFoundResult
Any status code		StatusCodeResult

异步服务

由于许多技术（例如使用HttpClient类调用其他服务）仅提供异步方法。所以会有异步服务。

定义服务接口
代码: IBookChaptersService.cs(async部分)

定义服务，用于检索，添加和更新书籍章节。
代码: BookChaptersService.cs(async部分)

BookChaptersService类实现异步方法。从字典读取和写入时，不需要异步功能，因此Task使用FromResult方法创建返回值。

客户端配置

发送请求、从客户端接受数据。包括GET、POST、PUT、DELETE。
返回Json和xml格式的字符串。

创建UrlService——提供基地址与uri
代码: UrlService.cs

创建泛型类HttpClientService，以便为不同的数据类型使用一个实现。
代码: HttpClientService.cs

创建Model——BookChapter
代码: BookChapter.cs

创建客户端类，进行对HttpClientService的调用
代码: SampleRequestClient.cs

注册服务、调用SampleRequestClient
代码: Program.cs

连接数据库

创建DbContext
代码: DbContext.cs

创建DBBookChaptersService代替BookChaptersService
代码: DBBookChaptersService.cs

注册服务——配置ConfigureServices
代码: Startup.cs

配置连接字符串
代码: appsettings.json

OpenAPI(Swagger)

添加NuGet——Swashbuckle.AspNetCore

public void ConfigureServices(IServiceCollection services)
{
    // ...
    // OpenAPI
    services.AddSwaggerGen(options =>
    {
        //options.DescribeAllEnumsAsStrings();
        options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
        {
            Title = "Azure Adapter Api - Catalog HTTP API",
            Version = "v1",
            Description = "The Catalog Microservice HTTP API. This is a Data-Driven/CRUD microservice sample",
            TermsOfService = "Terms Of Service"
        });
    });
    //...
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env,SampleChapters sampleChapters)
{
    // ...
    // OpenAPI
    app.UseSwagger().UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

OData

定义Model—Book、BookChapter

定义DBContext—BooksContext

定义Service—CreateBooksService

WebAPI技术介绍