Kurz: Použití příznaků funkcí v aplikaci ASP.NET Core

Článek
02/28/2024

Knihovny pro správu funkcí .NET poskytují idiomatickou podporu pro implementaci příznaků funkcí v aplikaci .NET nebo ASP.NET Core. Tyto knihovny umožňují deklarativní přidávání příznaků funkcí do kódu, takže nemusíte ručně psát kód pro povolení nebo zakázání funkcí s if příkazy.

Knihovny správy funkcí také spravují životní cyklus příznaků funkcí na pozadí. Například knihovny aktualizují a ukládají stav příznaku do mezipaměti nebo zaručují neměnný stav příznaku během volání žádosti. Kromě toho knihovna ASP.NET Core nabízí předem integrované integrace, včetně akcí kontroleru MVC, zobrazení, tras a middlewaru.

Referenční dokumentace k rozhraní API pro správu základních funkcí ASP.NET naleznete v tématu Obor názvů Microsoft.FeatureManagement.

V tomto kurzu se naučíte, jak:

Přidejte příznaky funkcí do klíčových částí aplikace, abyste mohli řídit dostupnost funkcí.
Integrace se službou App Configuration, když ji používáte ke správě příznaků funkcí

Požadavky

Rychlé zprovoznění aplikace ASP.NET Core ukazuje jednoduchý příklad použití příznaků funkcí v aplikaci ASP.NET Core. Tento kurz ukazuje další možnosti nastavení a možnosti knihoven správy funkcí. Ukázkovou aplikaci vytvořenou v rychlém startu můžete použít k vyzkoušení ukázkového kódu uvedeného v tomto kurzu.

Nastavení správy funkcí

Pokud chcete získat přístup ke správci funkcí .NET, musí vaše aplikace obsahovat odkazy na Microsoft.Azure.AppConfiguration.AspNetCore balíčky NuGet a Microsoft.FeatureManagement.AspNetCore balíčky NuGet.

Správce funkcí .NET je nakonfigurovaný z nativního konfiguračního systému architektury. V důsledku toho můžete definovat nastavení příznaku funkce aplikace pomocí libovolného zdroje konfigurace, který .NET podporuje, včetně místního appsettings.json souboru nebo proměnných prostředí.

Ve výchozím nastavení správce funkcí načte konfiguraci příznaku funkce z "FeatureManagement" části konfiguračních dat .NET. Chcete-li použít výchozí umístění konfigurace, zavolejte AddFeatureManagement metoda IServiceCollection předaná do ConfigureServices metoda Startup třídy.

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

Konfiguraci správy funkcí můžete zadat tak , že zavoláte Configuration.GetSection a předáte název požadovaného oddílu. Následující příklad říká správci funkcí, aby místo toho četl z jiného oddílu:"MyFeatureFlags"

using Microsoft.FeatureManagement;

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

Pokud ve svých příznakech funkce používáte filtry, musíte zahrnout obor názvů Microsoft.FeatureManagement.FeatureFilters a přidat volání AddFeatureFilter určující název typu filtru, který chcete použít jako obecný typ metody. Další informace o použití filtrů funkcí k dynamickému povolení a zakázání funkcí najdete v tématu Povolení postupného zavedení funkcí pro cílové skupiny.

Následující příklad ukazuje, jak použít předdefinovaný filtr funkcí s názvem PercentageFilter:

using Microsoft.FeatureManagement;

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

Místo pevného kódování příznaků funkcí do aplikace doporučujeme zachovat příznaky funkcí mimo aplikaci a spravovat je samostatně. Tímto způsobem můžete kdykoli změnit stavy příznaků a tyto změny se projeví v aplikaci okamžitě. Služba Aplikace Azure Configuration poskytuje vyhrazené uživatelské rozhraní portálu pro správu všech příznaků funkcí. Služba Aplikace Azure Configuration také doručuje příznaky funkcí vaší aplikaci přímo prostřednictvím klientských knihoven .NET.

Nejjednodušší způsob, jak připojit aplikaci ASP.NET Core ke konfiguraci aplikace, je prostřednictvím zprostředkovatele konfigurace, který je součástí Microsoft.Azure.AppConfiguration.AspNetCore balíčku NuGet. Po zahrnutí odkazu na balíček použijte tento balíček NuGet podle těchto kroků.

Otevřete Program.cs soubor a přidejte následující kód.

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

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

Pomocí následujícího kódu aktualizujte middleware a konfigurace služeb pro vaši aplikaci.

program.cs Uvnitř třídy zaregistrujte služby Aplikace Azure Configuration a middleware na builder objekty a app objekty:
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

V typickém scénáři pravidelně aktualizujete hodnoty příznaků funkcí při nasazování a povolování a povolování a různých funkcí aplikace. Ve výchozím nastavení se hodnoty příznaků funkce ukládají do mezipaměti po dobu 30 sekund, takže operace aktualizace se aktivuje, když middleware obdrží požadavek, neaktualizuje hodnotu, dokud nevyprší platnost hodnoty uložené v mezipaměti. Následující kód ukazuje, jak změnit dobu vypršení platnosti mezipaměti nebo interval dotazování na 5 minut nastavením CacheExpirationInterval ve volání UseFeatureFlags.

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

Deklarace příznaku funkce

Každá deklarace příznaku funkce má dvě části: název a seznam jednoho nebo více filtrů, které se používají k vyhodnocení, jestli je stav funkce zapnutý (to znamená, že je Truejeho hodnota). Filtr definuje kritérium, kdy má být funkce zapnutá.

Pokud má příznak funkce více filtrů, seznam filtrů se prochází v pořadí, dokud některý z filtrů nezjední, že by měla být funkce povolená. V tomto okamžiku je příznak funkce zapnutý a všechny zbývající výsledky filtru se přeskočí. Pokud žádný filtr indikuje, že by funkce měla být povolená, příznak funkce je vypnutý.

Správce funkcí podporuje appsettings.json jako zdroj konfigurace pro příznaky funkcí. Následující příklad ukazuje, jak nastavit příznaky funkcí v souboru JSON:

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

Podle konvence FeatureManagement se část tohoto dokumentu JSON používá pro nastavení příznaku funkce. Předchozí příklad ukazuje tři příznaky funkcí s jejich filtry definovanými ve EnabledFor vlastnosti:

FeatureA je zapnutý.
FeatureB je vypnutý.
FeatureC určuje filtr pojmenovaný PercentageParameters vlastností. Percentage je konfigurovatelný filtr. V tomto příkladu Percentage určuje 50procentní pravděpodobnost příznaku FeatureC , který má být zapnutý. Návod k používání filtrů funkcí najdete v tématu Použití filtrů funkcí k povolení příznaků podmíněné funkce.

Použití injektáže závislostí pro přístup k IFeatureManager

U některých operací, jako je ruční kontrola hodnot příznaků funkce, musíte získat instanci IFeatureManager. V ASP.NET Core MVC máte přístup ke správci IFeatureManager funkcí prostřednictvím injektáže závislostí. V následujícím příkladu je do podpisu konstruktoru pro kontroler přidán argument typu IFeatureManager . Modul runtime automaticky přeloží odkaz a poskytne implementaci rozhraní při volání konstruktoru. Pokud používáte šablonu aplikace, ve které už kontroler obsahuje jeden nebo více argumentů injektáže závislostí v konstruktoru, například ILoggermůžete přidat IFeatureManager jako další argument:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

Odkazy na příznaky funkcí

Definujte příznaky funkcí jako řetězcové proměnné, abyste je mohli odkazovat z kódu:

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

Kontroly příznaků funkcí

Běžným způsobem správy funkcí je zkontrolovat, jestli je příznak funkce nastavený na zapnutý , a pokud ano, spusťte část kódu. Příklad:

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

Akce kontroleru

Pomocí kontrolerů MVC můžete pomocí atributu FeatureGate řídit, jestli je povolená celá třída kontroleru nebo konkrétní akce. Před provedením jakékoli akce, která třída kontroleru obsahuje, musí FeatureA být zapnutý následující HomeController kontroler:

using Microsoft.FeatureManagement.Mvc;

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

Před spuštěním musí FeatureA být tato Index akce zapnutá:

using Microsoft.FeatureManagement.Mvc;

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

Když je kontroler MVC nebo akce blokovány, protože řídicí příznak funkce je vypnutý, volá se registrované rozhraní IDisabledFeaturesHandler . Výchozí IDisabledFeaturesHandler rozhraní vrátí klientovi stavový kód 404 bez textu odpovědi.

Zobrazení MVC

Otevřete soubor _ViewImports.cshtml v adresáři Zobrazení a přidejte pomocnou rutinu značky správce funkcí:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

V zobrazeních MVC můžete pomocí značky <feature> vykreslit obsah na základě toho, jestli je povolený příznak funkce:

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

Chcete-li zobrazit alternativní obsah, pokud nejsou splněny negate požadavky, lze použít atribut.

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

Značka funkce <feature> se dá použít také k zobrazení obsahu, pokud jsou povolené některé nebo všechny funkce v seznamu.

<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 můžete nastavit tak, aby byly aktivované na základě stavu příznaku funkce. Tato funkce je omezená na filtry, které implementují IAsyncActionFilter. Následující kód přidá filtr MVC s názvem ThirdPartyActionFilter. Tento filtr se aktivuje v kanálu MVC jenom v případě, že FeatureA je povolený.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

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

Middleware

Příznaky funkcí můžete také použít k podmíněnému přidání větví aplikací a middlewaru. Následující kód vloží komponentu middlewaru do kanálu požadavku pouze v případech, kdy FeatureA je povolená:

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

Tento kód sestavuje obecnější schopnost větvení celé aplikace na základě příznaku funkce:

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

Další kroky

V tomto kurzu jste zjistili, jak implementovat příznaky funkcí v aplikaci ASP.NET Core pomocí Microsoft.FeatureManagement knihoven. Další informace o podpoře správy funkcí v ASP.NET Core a App Configuration najdete v následujících zdrojích informací: