基本配置及說明

版本控制有助于及時推出功能，而不會破壞現(xiàn)有系統(tǒng)。 它還可以幫助為選定的客戶提供額外的功能。 API版本可以通過不同的方式完成，例如在URL中添加版本或通過自定義標(biāo)頭和通過Accept-Header作為查詢字符串參數(shù)。 在這篇文章中，我們來看看如何支持多版本的ASP.NET Core Web API

創(chuàng)建一個ASP.NET Core Web API應(yīng)用程序。通過 NuGet 安裝此軟件包：Microsoft.AspNetCore.Mvc.Versioning，打開Startup.cs,修改ConfigureServices方法，代碼如下：

public void ConfigureServices(IServiceCollection services) {services.AddMvc();services.AddApiVersioning(option =>{option.ReportApiVersions = true;option.AssumeDefaultVersionWhenUnspecified = true;option.DefaultApiVersion = new ApiVersion(1, 0);}); }

你可以看到配置了3個不同的選項:

• ReportAPIVersions :這是可選的。 但是當(dāng)設(shè)置為true時，API會在響應(yīng)頭中返回受支持的版本信息。
• AssumeDefaultVersionWhenUnspecified :此選項將用于在沒有版本的情況下提供請求。 假定的API版本默認為1.0
• DefaultApiVersion :此選項用于指定在請求中未指定任何版本時要使用的默認API版本。 這將默認版本為1.0

這就是配置和設(shè)置。 現(xiàn)在我們將看到訪問API版本的不同方法。

Via Query String(通過查詢字符串)

打開Controller 類，然后用ApiVersion屬性裝飾控Controller類。 像下面這樣，

namespace MultipleAPIVersions.Controllers {[ApiVersion("1.0")][Route("api/[controller]")]public class ValuesController : Controller{[HttpGet]public IActionResult Get() => Ok(new string[] { "value1" });} }

以上版本被設(shè)置為1.0，你還可以設(shè)置API版本為2.0，為此你需要在不同命名空間中創(chuàng)建具有相同名稱的另一個Controller類。 像下面這樣，

namespace AspNetCoreWebApi.Controllers2 {[ApiVersion("2.0")][Route("api/[controller]")]public class ValuesController : Controller{[HttpGet]public IActionResult Get() => Ok(new string[] { "value2" });} }

現(xiàn)在去瀏覽器并訪問控制器。 您應(yīng)該看到API版本1.0控制器的輸出，因為默認訪問為1.0的版本。 現(xiàn)在在URL中附加api-version = 2，你應(yīng)該看到API 2.0版控制器的輸出。

Via URL Path Segment(通過URL路徑)

查詢字符串參數(shù)是有用的，但在長URL和其他查詢字符串參數(shù)的情況下可能會很痛苦。 相反，更好的方法是在URL路徑中添加版本。 像這樣,

• api/v1/values
• api/v2/values

所以要做到這一點，我們需要把版本放在route屬性中:

namespace MultipleAPIVersions.Controllers {[ApiVersion("1.0")][Route("api/v{version:apiVersion}/[controller]")]public class ValuesController : Controller{[HttpGet]public IActionResult Get() => Ok(new string[] { "value1" });} }

同樣，您需要將路由參數(shù)更新到所有請求中。 通過此更改，API端點始終需要具有版本號。 您可以通過api/v1/values導(dǎo)航到版本1.0，要想訪問2.0版本，更改URL中的版本號。 簡單，看起來更干凈

Via HTTP Headers(通過HTTP頭傳遞)

在上述兩種方法中，需要修改URL以支持版本控制。 但是，如果您希望您的API URL保持干凈，那么API版本信息也可以通過附加HTTP頭傳遞。 為了使其工作，您需要配置ApiVersionReader選項

services.AddApiVersioning(option => {option.ReportApiVersions = true;option.ApiVersionReader = new HeaderApiVersionReader("api-version");option.DefaultApiVersion = new ApiVersion(1, 0);option.AssumeDefaultVersionWhenUnspecified = true; });

打開Postman添加header api-version測試

當(dāng)您將2.0作為值提供給api-version時，它將調(diào)用2.0版Controller并返回輸出

簡單易用的設(shè)置。 但是，現(xiàn)在查詢字符串參數(shù)(query string parameter)將無法正常工作。 設(shè)置header后，不能指定查詢字符串參數(shù)(query string parameter)。 如果你希望支持,請使用ApiVersionReader.Combine

option.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader("api-version"),new HeaderApiVersionReader("api-version"));

現(xiàn)在，查詢字符串參數(shù)和header都支持
請記住，我們還將ReportApiVersions設(shè)置為true，返回響應(yīng)頭中的版本信息。 見下圖

現(xiàn)在，讓我們來看看另外幾個選項

MapToApiVersion

MapToApiVersion 特性允許將單個API action 映射到任何版本。 換句話說，支持多個版本的單個Controller

namespace MultipleAPIVersions.Controllers {[ApiVersion("1.0")][ApiVersion("3.0")][Route("api/v{version:apiVersion}/[controller]")]public class ValuesController : Controller{[HttpGet]public IActionResult Get() => Ok(new string[] { "value1" });[HttpGet, MapToApiVersion("3.0")]public IActionResult GetV3() => Ok(new string[] { "value3" });} }

Deprecated(棄用)

當(dāng)支持多個API版本時，一些版本最終將被淘汰。 要想標(biāo)明一個或多個API版將被棄用，只需將準(zhǔn)備棄用的API版本標(biāo)記。 這并不意味著不支持API版本，這些被標(biāo)記的API仍然可以調(diào)用。 這只是讓用戶意識到以后版本將被廢棄的一種方式
[ApiVersion("1.0", Deprecated = true)]

ApiVersionNeutral(版本中立)

ApiVersionNeutral特性定義該API是版本中立的。 這對于行為方式完全相同的API非常有用，不論是支持API版本的Controller還是不支持API版本的Controller。 因此，你可以添加ApiVersionNeutral特性以退出版本控制

[ApiVersionNeutral] [RoutePrefix( "api/[controller]" )] public class SharedController : Controller {[HttpGet]public IActionResult Get() => Ok(); }

訪問版本信息

如果你想知道哪個版本的客戶端正在嘗試訪問，那么你可以從中獲取該信息：

public string Get() => HttpContext.GetRequestedApiVersion().ToString();

文章原地址 support-multiple-versions-of-asp-net-core-web-api
相關(guān)文章API-Version-Reader

轉(zhuǎn)載于:https://www.cnblogs.com/MrNice/p/aspnet-core-api-version.html

總結(jié)

以上是生活随笔為你收集整理的支持多个版本的ASP.NET Core Web API的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。