WebAPI技術介紹

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<IBookChaptersService, BookChaptersService>();
    services.AddSingleton<SampleChapters>();
    #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<IBookChaptersService, BookChaptersService>();
    services.AddSingleton<SampleChapters>();
    #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