Samouczek: używanie flag funkcji w aplikacji ASP.NET Core

Artykuł
03/05/2024

Biblioteki zarządzania funkcjami platformy .NET zapewniają idiomatyczną obsługę implementowania flag funkcji na platformie .NET lub ASP.NET Core. Te biblioteki umożliwiają deklaratywne dodawanie flag funkcji do kodu, dzięki czemu nie trzeba ręcznie pisać kodu, aby włączyć lub wyłączyć funkcje za pomocą if instrukcji.

Biblioteki zarządzania funkcjami zarządzają również cyklami życia flag funkcji w tle. Na przykład biblioteki odświeżą i buforują stany flagi lub gwarantują, że stan flagi będzie niezmienny podczas wywołania żądania. Ponadto biblioteka ASP.NET Core oferuje gotowe do użycia integracje, w tym akcje kontrolera MVC, widoki, trasy i oprogramowanie pośredniczące.

Aby uzyskać dokumentację referencyjną interfejsu API zarządzania funkcjami platformy ASP.NET Core, zobacz Microsoft.FeatureManagement Namespace (Przestrzeń nazw microsoft.FeatureManagement).

Niniejszy samouczek zawiera informacje na temat wykonywania następujących czynności:

Dodaj flagi funkcji w kluczowych częściach aplikacji, aby kontrolować dostępność funkcji.
Integruj się z usługą App Configuration, gdy używasz jej do zarządzania flagami funkcji.

Wymagania wstępne

W przewodniku Szybki start dodawanie flag funkcji do aplikacji ASP.NET Core przedstawiono prosty przykład używania flag funkcji w aplikacji ASP.NET Core. W tym samouczku przedstawiono dodatkowe opcje konfiguracji i możliwości bibliotek zarządzania funkcjami. Przykładowa aplikacja utworzona w przewodniku Szybki start umożliwia wypróbowanie przykładowego kodu pokazanego w tym samouczku.

Konfigurowanie zarządzania funkcjami

Aby uzyskać dostęp do menedżera funkcji platformy .NET, aplikacja musi mieć odwołania do Microsoft.Azure.AppConfiguration.AspNetCore pakietów NuGet i Microsoft.FeatureManagement.AspNetCore .

Menedżer funkcji platformy .NET jest skonfigurowany z natywnego systemu konfiguracji platformy. W związku z tym można zdefiniować ustawienia flagi funkcji aplikacji przy użyciu dowolnego źródła konfiguracji obsługiwanego przez platformę .NET, w tym lokalnego appsettings.json pliku lub zmiennych środowiskowych.

Domyślnie menedżer funkcji pobiera konfigurację flagi funkcji z "FeatureManagement" sekcji danych konfiguracji platformy .NET. Aby użyć domyślnej lokalizacji konfiguracji, wywołaj metodę AddFeatureManagement elementu IServiceCollection przekazaną do metody ConfigureServices klasy Startup.

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

Konfigurację zarządzania funkcjami można określić w innej sekcji konfiguracji, wywołując polecenie Configuration.GetSection i przekazując nazwę żądanej sekcji. Poniższy przykład informuje menedżera funkcji o konieczności odczytania z innej sekcji o nazwie "MyFeatureFlags" zamiast tego:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));

Jeśli używasz filtrów w flagach funkcji, musisz dołączyć przestrzeń nazw Microsoft.FeatureManagement.FeatureFilters i dodać wywołanie metody AddFeatureFilter określające nazwę typu filtru, którego chcesz użyć jako typ ogólny metody. Aby uzyskać więcej informacji na temat dynamicznego włączania i wyłączania funkcji przy użyciu filtrów funkcji, zobacz Włączanie etapowego wdrażania funkcji dla docelowych odbiorców.

W poniższym przykładzie pokazano, jak używać wbudowanego filtru funkcji o nazwie PercentageFilter:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement()
    .AddFeatureFilter<PercentageFilter>();

Zamiast kodować flagi funkcji w aplikacji, zalecamy, aby flagi funkcji były przechowywane poza aplikacją i zarządzać nimi oddzielnie. Dzięki temu można w dowolnym momencie modyfikować stany flagi i od razu wprowadzać te zmiany w aplikacji. Usługa aplikacja systemu Azure Configuration udostępnia dedykowany interfejs użytkownika portalu do zarządzania wszystkimi flagami funkcji. Usługa aplikacja systemu Azure Configuration udostępnia również flagi funkcji aplikacji bezpośrednio za pośrednictwem bibliotek klienckich platformy .NET.

Najprostszym sposobem połączenia aplikacji ASP.NET Core z usługą App Configuration jest dostawca konfiguracji uwzględniony w pakiecie Microsoft.Azure.AppConfiguration.AspNetCore NuGet. Po dołączeniu odwołania do pakietu wykonaj następujące kroki, aby użyć tego pakietu NuGet.

Otwórz plik Program.cs i dodaj następujący kod.

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
        .UseFeatureFlags());

Zaktualizuj oprogramowanie pośredniczące i konfiguracje usługi dla aplikacji przy użyciu następującego kodu.

program.cs Wewnątrz klasy zarejestruj usługi aplikacja systemu Azure Configuration services i oprogramowanie pośredniczące w obiektach builder i app :
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

W typowym scenariuszu okresowo aktualizujesz wartości flag funkcji podczas wdrażania i włączania i różnych funkcji aplikacji. Domyślnie wartości flag funkcji są buforowane przez okres 30 sekund, więc operacja odświeżania wyzwolona, gdy oprogramowanie pośredniczące odbiera żądanie, nie zaktualizuje wartości do momentu wygaśnięcia buforowanej wartości. Poniższy kod pokazuje, jak zmienić czas wygaśnięcia pamięci podręcznej lub interwał sondowania na 5 minut, ustawiając wartość CacheExpirationInterval w wywołaniu metody UseFeatureFlags.

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

Deklaracja flagi funkcji

Każda deklaracja flagi funkcji ma dwie części: nazwę i listę co najmniej jednego filtru używanego do oceny, czy stan funkcji jest włączony (to znaczy, gdy jej wartość to True). Filtr definiuje kryterium, kiedy funkcja powinna być włączona.

Gdy flaga funkcji ma wiele filtrów, lista filtrów jest przechodzina w kolejności, dopóki jeden z filtrów nie określi, że funkcja powinna zostać włączona. W tym momencie flaga funkcji jest włączona i wszystkie pozostałe wyniki filtru są pomijane. Jeśli żaden filtr nie wskazuje, że funkcja powinna być włączona, flaga funkcji jest wyłączona.

Menedżer funkcji obsługuje appsettings.json jako źródło konfiguracji flag funkcji. W poniższym przykładzie pokazano, jak skonfigurować flagi funkcji w pliku JSON:

{"FeatureManagement": {
        "FeatureA": true, // Feature flag set to on
        "FeatureB": false, // Feature flag set to off
        "FeatureC": {
            "EnabledFor": [
                {
                    "Name": "Percentage",
                    "Parameters": {
                        "Value": 50
                    }
                }
            ]
        }
    }
}

Zgodnie z konwencją FeatureManagement sekcja tego dokumentu JSON jest używana do ustawień flagi funkcji. W poprzednim przykładzie pokazano trzy flagi funkcji z filtrami zdefiniowanymi we EnabledFor właściwości :

FeatureA jest włączona.
FeatureB jest wyłączona.
FeatureC określa filtr o nazwie Percentage z właściwością Parameters . Percentage jest konfigurowalnym filtrem. W tym przykładzie Percentage określa 50-procentowe prawdopodobieństwo, że flaga FeatureC ma być włączona. Aby zapoznać się z instrukcjami dotyczącymi używania filtrów funkcji, zobacz Używanie filtrów funkcji do włączania flag funkcji warunkowych.

Używanie wstrzykiwania zależności w celu uzyskania dostępu do klasy IFeatureManager

W przypadku niektórych operacji, takich jak ręczne sprawdzanie wartości flag funkcji, należy uzyskać wystąpienie klasy IFeatureManager. W ASP.NET Core MVC można uzyskać dostęp do menedżera IFeatureManager funkcji za pomocą wstrzykiwania zależności. W poniższym przykładzie argument typu IFeatureManager jest dodawany do podpisu konstruktora dla kontrolera. Środowisko uruchomieniowe automatycznie rozpoznaje odwołanie i zapewnia implementację interfejsu podczas wywoływania konstruktora. Jeśli używasz szablonu aplikacji, w którym kontroler ma już jeden lub więcej argumentów iniekcji zależności w konstruktorze, takich jak ILogger, możesz po prostu dodać IFeatureManager jako dodatkowy argument:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

    public HomeController(ILogger<HomeController> logger, IFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

Odwołania do flagi funkcji

Zdefiniuj flagi funkcji jako zmienne ciągu, aby odwoływać się do nich z kodu:

public static class MyFeatureFlags
{
    public const string FeatureA = "FeatureA";
    public const string FeatureB = "FeatureB";
    public const string FeatureC = "FeatureC";
}

Kontrole flag funkcji

Typowym wzorcem zarządzania funkcjami jest sprawdzenie, czy flaga funkcji jest włączona i jeśli tak, uruchom sekcję kodu. Na przykład:

IFeatureManager featureManager;
...
if (await featureManager.IsEnabledAsync(MyFeatureFlags.FeatureA))
{
    // Run the following code
}

Akcje kontrolera

W przypadku kontrolerów MVC można użyć atrybutu FeatureGate do kontrolowania, czy jest włączona cała klasa kontrolera, czy określona akcja. Przed wykonaniem dowolnej akcji, jaką może wykonać klasa kontrolera, musi FeatureA być włączony następujący HomeController kontroler:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public class HomeController : Controller
{
    ...
}

Aby można było uruchomić polecenie , należy FeatureA wykonaćnastępującą Index akcję:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public IActionResult Index()
{
    return View();
}

Gdy kontroler MVC lub akcja jest blokowana, ponieważ flaga funkcji sterowania jest wyłączona, wywoływany jest zarejestrowany interfejs IDisabledFeaturesHandler . Interfejs domyślny IDisabledFeaturesHandler zwraca kod stanu 404 do klienta bez treści odpowiedzi.

Widoki MVC

Otwórz plik _ViewImports.cshtml w katalogu Views i dodaj pomocnik tagu menedżera funkcji:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

W widokach MVC można użyć tagu <feature> do renderowania zawartości na podstawie tego, czy flaga funkcji jest włączona:

<feature name="FeatureA">
    <p>This can only be seen if 'FeatureA' is enabled.</p>
</feature>

Aby wyświetlić zawartość alternatywną, jeśli wymagania nie są spełnione, można użyć atrybutu negate .

<feature name="FeatureA" negate="true">
    <p>This will be shown if 'FeatureA' is disabled.</p>
</feature>

Tag funkcji <feature> może również służyć do wyświetlania zawartości, jeśli są włączone dowolne lub wszystkie funkcje na liście.

<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>

Filtry MVC

Filtry MVC można skonfigurować tak, aby były aktywowane na podstawie stanu flagi funkcji. Ta funkcja jest ograniczona do filtrów implementujących filtr IAsyncActionFilter. Poniższy kod dodaje filtr MVC o nazwie ThirdPartyActionFilter. Ten filtr jest wyzwalany w potoku MVC tylko wtedy, gdy FeatureA jest włączony.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options => {
        options.Filters.AddForFeature<ThirdPartyActionFilter>(MyFeatureFlags.FeatureA);
    });
}

Oprogramowanie pośredniczące

Możesz również użyć flag funkcji, aby warunkowo dodać gałęzie aplikacji i oprogramowanie pośredniczące. Poniższy kod wstawia składnik oprogramowania pośredniczącego w potoku żądania tylko wtedy, gdy FeatureA jest włączony:

app.UseMiddlewareForFeature<ThirdPartyMiddleware>(MyFeatureFlags.FeatureA);

Ten kod kompiluje bardziej ogólną możliwość rozgałęziania całej aplikacji na podstawie flagi funkcji:

app.UseForFeature(featureName, appBuilder => {
    appBuilder.UseMiddleware<T>();
});

Następne kroki

W tym samouczku przedstawiono sposób implementowania flag funkcji w aplikacji ASP.NET Core przy użyciu Microsoft.FeatureManagement bibliotek. Aby uzyskać więcej informacji na temat obsługi zarządzania funkcjami w usłudze ASP.NET Core i App Configuration, zobacz następujące zasoby: