教學課程:在 ASP.NET Core 應用程式中使用功能旗標

.NET Core 功能管理程式庫可讓您在 .NET 或 ASP.NET Core 應用程式中以慣用方式實作功能旗標。 這些程式庫可讓您以宣告方式將功能旗標新增至您的程式碼,如此您就不需要手動撰寫程式碼來啟用或停用語句的功能 if

功能管理程式庫也可在幕後管理功能旗標的生命週期。 例如,這些程式庫會重新整理及快取旗標狀態,或保證旗標的狀態在要求呼叫期間不會變化。 此外,ASP.NET Core 程式庫還提供現成可用的整合,包括 MVC 控制器動作、檢視、路由和中介軟體。

功能旗標新增至 ASP.NET Core 應用程式快速入門會顯示如何在 ASP.NET Core 應用程式中使用功能旗標的簡單範例。 本教學課程會顯示功能管理程式庫的其他安裝選項和功能。 您可以使用在快速入門中建立的範例應用程式來試用本教學課程中所顯示的範例程式碼。

如需 ASP.NET Core 功能管理 API 參考檔,請參閱FeatureManagement 命名空間

在本教學課程中,您將學會如何:

  • 在應用程式的重要部分新增功能旗標來控制功能的可用性。
  • 在您使用應用程式組態來管理功能旗標時與其進行整合。

設定功能管理

若要存取 .net Core 功能管理員,您的應用程式必須參考 Microsoft.FeatureManagement.AspNetCore NuGet 套件。

.NET Core 功能管理員會從架構的原生設定系統設定。 因此,您可以使用 .NET Core 支援的任何設定來源來定義應用程式的功能旗標設定,包括本機 appsettings.js 檔案或環境變數。

根據預設,功能管理員會從 .NET Core 設定資料的區段抓取功能旗標設定 "FeatureManagement" 。 若要使用預設設定位置,請呼叫傳遞至 Startup 類別之 ConfigureServices 方法的 IServiceCollection AddFeatureManagement方法。

using Microsoft.FeatureManagement;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        services.AddFeatureManagement();
    }
}

您可以藉由呼叫 GetSection ,並傳入所需區段的名稱,指定要從不同的設定區段取出功能管理設定。 下列範例會指示功能管理員改為讀取名為 "MyFeatureFlags" 的不同區段:

using Microsoft.FeatureManagement;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));
    }
}

如果您在功能旗標中使用篩選準則,則必須包含 FeatureManagement. FeatureFilters 命名空間,並新增對 AddFeatureFilters 的呼叫,以指定您想要用來做為方法泛型型別之篩選準則的型別名稱。 如需使用功能篩選動態啟用和停用功能的詳細資訊,請參閱 為目標物件啟用功能的分段推出

下列範例說明如何使用名為 PercentageFilter 的內建功能篩選條件:

using Microsoft.FeatureManagement;
using Microsoft.FeatureManagement.FeatureFilters;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        services.AddFeatureManagement()
                .AddFeatureFilter<PercentageFilter>();
    }
}

建議您將功能旗標放在應用程式外部,並個別管理它們,而不是將功能旗標硬編碼至您的應用程式。 這樣做可讓您隨時修改旗標狀態,並讓那些變更在應用程式中立即生效。 Azure 應用程式組態服務提供專用的入口網站 UI 來管理您的所有功能旗標。 Azure 應用程式組態服務也會透過其 .NET Core 用戶端程式庫,直接將功能旗標傳遞給您的應用程式。

將 ASP.NET Core 應用程式連線到應用程式設定最簡單的方式,就是透過 NuGet 套件中包含的設定提供者 Microsoft.Azure.AppConfiguration.AspNetCore 。 包含封裝的參考之後,請遵循下列步驟來使用此 NuGet 套件。

  1. 開啟 Program.cs 檔案,並新增下列程式碼。

    重要

    CreateHostBuilder 會取代 .NET Core 3.x 中的 CreateWebHostBuilder。 根據您的環境選取正確的語法。

    using Microsoft.Extensions.Configuration.AzureAppConfiguration;
    
    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
                webBuilder.ConfigureAppConfiguration(config =>
                {
                    var settings = config.Build();
                    config.AddAzureAppConfiguration(options =>
                        options.Connect(settings["ConnectionStrings:AppConfig"]).UseFeatureFlags());
                }).UseStartup<Startup>());
    
  2. 開啟 [ 啟動 ],並更新 ConfigureConfigureServices 方法,以加入名為的內建中介軟體 UseAzureAppConfiguration 。 此中介軟體可讓功能旗標值依週期性間隔重新整理,同時讓 ASP.NET Core Web 應用程式繼續接收要求。

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        app.UseAzureAppConfiguration();
    }
    
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAzureAppConfiguration();
    }
    

在一般案例中,您會在部署和啟用應用程式的不同功能時,定期更新功能旗標值。 根據預設,功能旗標值的快取期間為 30 秒,因此在中介軟體接收要求時觸發的重新整理作業,必須要到快取的值過期後才會更新值。 下列程式碼示範如何藉由在 UseFeatureFlags 的呼叫中設定 CacheExpirationInterval ,將快取到期時間或輪詢間隔變更為5分鐘。

config.AddAzureAppConfiguration(options =>
    options.Connect(settings["ConnectionStrings:AppConfig"]).UseFeatureFlags(featureFlagOptions => {
        featureFlagOptions.CacheExpirationInterval = TimeSpan.FromMinutes(5);
    }));
});

功能旗標宣告

每個功能旗標宣告都有兩個部分:名稱和一個或多個篩選準則的清單,這些篩選準則可用來評估功能的狀態是否為 on (也就是 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";
}

功能旗標檢查

功能管理的常見模式是檢查功能旗標是否設定為 on ,如果是,請執行程式碼區段。 例如:

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 狀態碼。

MVC 檢視

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 篩選條件

您可以將 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 和應用程式組態中的功能管理支援,請參閱下列資源: