基本配置及說明 版本控制有助於及時推出功能，而不會破壞現有系統。 它還可以幫助為選定的客戶提供額外的功能。 API版本可以通過不同的方式完成，例如在URL中添加版本或通過自定義標頭和通過Accept Header作為查詢字元串參數。 在這篇文章中，我們來看看如何支持多版本的ASP.NET Core ...
基本配置及說明
版本控制有助於及時推出功能，而不會破壞現有系統。 它還可以幫助為選定的客戶提供額外的功能。 API版本可以通過不同的方式完成，例如在URL中添加版本或通過自定義標頭和通過Accept-Header作為查詢字元串參數。 在這篇文章中，我們來看看如何支持多版本的ASP.NET Core Web API
創建一個ASP.NET Core Web API應用程式。通過 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:這是可選的。 但是當設置為true時，API會在響應頭中返回受支持的版本信息。AssumeDefaultVersionWhenUnspecified:此選項將用於在沒有版本的情況下提供請求。 假定的API版本預設為1.0DefaultApiVersion:此選項用於指定在請求中未指定任何版本時要使用的預設API版本。 這將預設版本為1.0
這就是配置和設置。 現在我們將看到訪問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" });
}
}以上版本被設置為1.0，你還可以設置API版本為2.0，為此你需要在不同命名空間中創建具有相同名稱的另一個Controller類。 像下麵這樣，
namespace AspNetCoreWebApi.Controllers2
{
[ApiVersion("2.0")]
[Route("api/[controller]")]
public class ValuesController : Controller
{
[HttpGet]
public IActionResult Get() => Ok(new string[] { "value2" });
}
}現在去瀏覽器並訪問控制器。 您應該看到API版本1.0控制器的輸出，因為預設訪問為1.0的版本。 現在在URL中附加api-version = 2，你應該看到API 2.0版控制器的輸出。
Via URL Path Segment(通過URL路徑)
查詢字元串參數是有用的，但在長URL和其他查詢字元串參數的情況下可能會很痛苦。 相反，更好的方法是在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" });
}
}同樣，您需要將路由參數更新到所有請求中。 通過此更改，API端點始終需要具有版本號。 您可以通過api/v1/values導航到版本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測試
當您將2.0作為值提供給api-version時，它將調用2.0版Controller並返回輸出
簡單易用的設置。 但是，現在查詢字元串參數(query string parameter)將無法正常工作。 設置header後，不能指定查詢字元串參數(query string parameter)。 如果你希望支持,請使用ApiVersionReader.Combine
option.ApiVersionReader = ApiVersionReader.Combine
(
new QueryStringApiVersionReader("api-version"),
new HeaderApiVersionReader("api-version")
);現在，查詢字元串參數和header都支持
請記住，我們還將ReportApiVersions設置為true，返迴響應頭中的版本信息。 見下圖
現在，讓我們來看看另外幾個選項
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(棄用)
當支持多個API版本時，一些版本最終將被淘汰。 要想標明一個或多個API版將被棄用，只需將準備棄用的API版本標記。 這並不意味著不支持API版本，這些被標記的API仍然可以調用。 這隻是讓用戶意識到以後版本將被廢棄的一種方式
[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
相關文章API-Version-Reader
