教學課程:在 ASP.NET Core 應用程式中使用功能旗標
本文內容
必要條件
設定功能管理
功能旗標宣告
使用相依性插入存取 IFeatureManager
功能旗標參考
功能旗標檢查
控制器動作
MVC 檢視
MVC 篩選條件
中介軟體
下一步
顯示其他 7 個
.NET 功能管理程式庫會提供在 .NET 或 ASP.NET Core 應用程式中實作功能旗標的支援。 這些程式庫讓您以宣告方式新增功能旗標至程式碼,所以您不必手動撰寫程式碼啟用或停用包含 if
陳述式的功能。
功能管理程式庫也可在幕後管理功能旗標的生命週期。 例如,這些程式庫會重新整理及快取旗標狀態,或保證旗標的狀態在要求呼叫期間不會變化。 此外,ASP.NET Core 程式庫還提供現成可用的整合,包括 MVC 控制器動作、檢視、路由和中介軟體。
在本教學課程中,您將了解如何:
在應用程式的重要部分新增功能旗標來控制功能的可用性。
在您使用應用程式組態來管理功能旗標時與其進行整合。
若要存取 .NET 功能管理員,您的應用程式必須包含 Microsoft.Azure.AppConfiguration.AspNetCore
和 Microsoft.FeatureManagement.AspNetCore
NuGet 套件的參考。
.NET 功能管理員是由架構的原生組態系統所組態。 因此,您可以使用 .NET 支援的組態來源 (包括本地 appsettings.json
檔案或環境變數),定義應用程式的功能旗標組態。
根據預設,功能管理員會從 .NET Core 設定資料的 "FeatureManagement"
區段來擷取功能旗標設定。 若要使用預設設定位置,請呼叫傳遞至啟動 類別 ConfigureServices 方法中,IServiceCollection 的 AddFeatureManagement 方法。
using Microsoft.FeatureManagement;
builder.Services.AddFeatureManagement();
您可以呼叫 Configuration.GetSection 並傳入所需區段的名稱,然後指定從不同的設定區段擷取功能管理設定。 下列範例會指示功能管理員改為讀取名為 "MyFeatureFlags"
的不同區段:
using Microsoft.FeatureManagement;
builder.Services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));
您可以使用功能篩選來啟用條件式功能旗標。 若要使用內建功能篩選或建立您自己的篩選,請參閱 使用功能篩選啟用條件式功能 。
建議您不要將功能旗標程式碼寫入應用程式,而是將其保留在應用程式外部並個別管理。 這樣做可讓您隨時修改旗標狀態,並讓那些變更在應用程式中立即生效。 Azure 應用程式設定服務提供用於管理所有功能旗標的專用入口網站 UI。 Azure 應用程式組態服務也可透過其 .NET Core 用戶端程式庫,直接傳遞功能旗標至應用程式。
若要連線 ASP.NET Core 應用程式與應用程式設定,最簡單的方式是透過 Microsoft.Azure.AppConfiguration.AspNetCore
NuGet 套件包含的設定提供者。 包含套件的參考後,請遵循下列步驟使用此 NuGet 套件。
開啟 Program.cs 檔案,並新增下列程式碼。
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
options.Connect(
builder.Configuration["ConnectionStrings:AppConfig"])
.UseFeatureFlags());
使用下列程式碼更新應用程式的中介軟體和服務組態。
在 program.cs
類別內,在 builder
和 app
物件上註冊 Azure 應用程式組態服務和中介軟體:
builder.Services.AddAzureAppConfiguration();
app.UseAzureAppConfiguration();
在典型案例中,您將在部署並啟用應用程式的不同功能時,定期更新功能旗標值。 根據預設,功能旗標值的快取期間為 30 秒,因此在中介軟體接收要求時觸發的重新整理作業,必須要到快取的值過期後才會更新值。 下列程式碼說明如何在呼叫 UseFeatureFlags 時,設定 CacheExpirationInterval ,並將快取到期時間或輪詢間隔變更為 5分鐘。
config.AddAzureAppConfiguration(options =>
options.Connect(
builder.Configuration["ConnectionStrings:AppConfig"])
.UseFeatureFlags(featureFlagOptions => {
featureFlagOptions.CacheExpirationInterval = TimeSpan.FromMinutes(5);
}));
每個功能旗標宣告都有兩個部分:名稱和一或多個篩選條件的清單,而此清單用來評估功能狀態是否為「開啟」 (亦即狀態值為 True
時)。 篩選條件定義開啟功能時機的準則。
如果功能旗標有多個篩選條件,則會依序周遊篩選條件清單,直到其中一個篩選條件確定應啟用功能。 此時,功能旗標會顯示開啟 ,而且會略過任何其餘的篩選結果。 如果沒有篩選條件指出應該啟用此功能,則功能旗標就會關閉 。
功能管理員支援以 appsettings.json 作為功能旗標的設定來源。 下列範例示範如何在 JSON 檔案中設定功能旗標:
{
"FeatureManagement": {
"FeatureA": true, // Feature flag set to on
"FeatureB": false, // Feature flag set to off
"FeatureC": {
"EnabledFor": [
{
"Name": "Percentage",
"Parameters": {
"Value": 50
}
}
]
}
}
}
依照慣例,我們會將此 JSON 文件的 FeatureManagement
區段用於功能旗標設定。 上述範例顯示了三個功能旗標,及其在 EnabledFor
屬性中定義的篩選條件:
FeatureA
為「開啟」 。
FeatureB
為「關閉」 。
FeatureC
會使用 Parameters
屬性指定名為 Percentage
的篩選條件。 Percentage
是可設定的篩選條件。 在此範例中,Percentage
會指定 FeatureC
旗標有 50% 的機率會「開啟」 。 如需使用功能篩選的操作指南,請參閱使用功能篩選啟用條件式功能旗標 。
使用相依性插入存取 IFeatureManager
如果是手動檢查功能旗標值等作業,請取得 IFeatureManager 的執行個體。 在 ASP.NET Core MVC 中,您可以透過相依性插入存取功能管理員 IFeatureManager
。 在下列範例中,IFeatureManager
類型的引數會新增至控制器的建構函式簽章。 呼叫建構函式時,執行階段會自動解析參考並提供介面的實行。 如果您目前使用的應用程式範本中的控制器,在建構函式已有一或多個相依性插入引數 (例如 ILogger
),您可以直接新增 IFeatureManager
作為其他引數:
using Microsoft.FeatureManagement;
public class HomeController : Controller
{
private readonly IFeatureManager _featureManager;
public HomeController(ILogger<HomeController> logger, IFeatureManager featureManager)
{
_featureManager = featureManager;
}
}
若要從程式碼參考功能旗標,請將功能旗標定義為字串變數:
public static class MyFeatureFlags
{
public const string FeatureA = "FeatureA";
public const string FeatureB = "FeatureB";
public const string FeatureC = "FeatureC";
}
功能管理的常見模式是,檢查功能旗標是否設為「開啟」 ,如果是,請執行一段程式碼。 例如:
IFeatureManager featureManager;
...
if (await featureManager.IsEnabledAsync(MyFeatureFlags.FeatureA))
{
// Run the following code
}
使用 MVC 控制器時,您可以使用 FeatureGate
屬性,控制是否啟用整個控制器類別或特定動作。 下列 HomeController
控制器必須在 FeatureA
「開啟」 時,才能執行該控制器類別所包含的動作:
using Microsoft.FeatureManagement.Mvc;
[FeatureGate(MyFeatureFlags.FeatureA)]
public class HomeController : Controller
{
...
}
下列 Index
動作必須在 FeatureA
「開啟」 時才能執行:
using Microsoft.FeatureManagement.Mvc;
[FeatureGate(MyFeatureFlags.FeatureA)]
public IActionResult Index()
{
return View();
}
因為控制功能旗標「關閉」 而封鎖 MVC 控制器或動作時,系統便會呼叫註冊的 IDisabledFeaturesHandler 介面。 預設的 IDisabledFeaturesHandler
介面會對用戶端傳回沒有回應本文的 404 狀態碼。
在 Views 目錄中開啟 _ViewImports.cshtml ,並新增功能管理員標記協助程式:
@addTagHelper *, Microsoft.FeatureManagement.AspNetCore
在 MVC 檢視中,您可以使用 <feature>
標記,根據功能旗標是否已啟用來呈現內容:
<feature name="FeatureA">
<p>This can only be seen if 'FeatureA' is enabled.</p>
</feature>
若要在不符合需求時顯示替代內容,可以使用 negate
屬性。
<feature name="FeatureA" negate="true">
<p>This will be shown if 'FeatureA' is disabled.</p>
</feature>
如果清單中的任何功能或所有功能都啟用,功能 <feature>
標記也可以用來顯示內容。
<feature name="FeatureA, FeatureB" requirement="All">
<p>This can only be seen if 'FeatureA' and 'FeatureB' are enabled.</p>
</feature>
<feature name="FeatureA, FeatureB" requirement="Any">
<p>This can be seen if 'FeatureA', 'FeatureB', or both are enabled.</p>
</feature>
您可以將 MVC 篩選條件設定為根據功能旗標的狀態來啟用。 此功能限於實作 IAsyncActionFilter 的篩選。 下列程式碼會新增名為 ThirdPartyActionFilter
的 MVC 篩選條件。 只有在 FeatureA
已啟用時,才會在 MVC 管線內觸發此篩選條件。
using Microsoft.FeatureManagement.FeatureFilters;
IConfiguration Configuration { get; set;}
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(options => {
options.Filters.AddForFeature<ThirdPartyActionFilter>(MyFeatureFlags.FeatureA);
});
}
您也可以使用功能旗標,根據條件新增應用程式分支和中介軟體。 下列程式碼只有在 FeatureA
啟用時,才會在要求管線中插入中介軟體元件:
app.UseMiddlewareForFeature<ThirdPartyMiddleware>(MyFeatureFlags.FeatureA);
此程式碼會建置更泛型的功能,以根據功能旗標為整個應用程式建立分支:
app.UseForFeature(featureName, appBuilder => {
appBuilder.UseMiddleware<T>();
});
在本教學課程中,您已了解如何藉由使用 Microsoft.FeatureManagement
程式庫在 ASP.NET Core 應用程式中實作功能旗標。 若要進一步了解 ASP.NET Core 和應用程式組態中的功能管理支援,請參閱下列資源: