Självstudie: Använda funktionsflaggor i en ASP.NET Core-app

.NET-funktionshanteringsbiblioteken ger idiomatiskt stöd för att implementera funktionsflaggor i ett .NET- eller ASP.NET Core-program. Med de här biblioteken kan du deklarativt lägga till funktionsflaggor i koden så att du inte behöver skriva kod manuellt för att aktivera eller inaktivera funktioner med if instruktioner.

Funktionshanteringsbiblioteken hanterar även funktionsflaggans livscykel i bakgrunden. Till exempel uppdaterar biblioteken och cachelagrade flaggtillstånd, eller garanterar att ett flaggtillstånd inte kan ändras under ett begärandeanrop. Dessutom erbjuder ASP.NET Core-biblioteket färdiga integreringar, inklusive MVC-kontrollantåtgärder, vyer, vägar och mellanprogram.

I den här självstudien får du lära dig hur man:

Förutsättningar

• Snabbstarten Lägg till funktionsflaggor i en ASP.NET Core-app visar ett enkelt exempel på hur du använder funktionsflaggor i ett ASP.NET Core-program. Den här självstudien visar ytterligare installationsalternativ och funktioner i funktionshanteringsbiblioteken. Du kan använda exempelappen som skapades i snabbstarten för att prova exempelkoden som visas i den här självstudien.

Konfigurera funktionshantering

För att få åtkomst till .NET-funktionshanteraren måste appen ha referenser till NuGet-paketen Microsoft.Azure.AppConfiguration.AspNetCore och Microsoft.FeatureManagement.AspNetCore .

.NET-funktionshanteraren konfigureras från ramverkets interna konfigurationssystem. Därför kan du definiera programmets inställningar för funktionsflagga med hjälp av valfri konfigurationskälla som .NET stöder, inklusive lokala appsettings.json fil- eller miljövariabler.

Som standard hämtar funktionshanteraren konfigurationen av funktionsflaggan "FeatureManagement" från avsnittet i .NET-konfigurationsdata. Om du vill använda standardkonfigurationsplatsen anropar du metoden AddFeatureManagement för IServiceCollection som skickas till metoden ConfigureServices i startklassen.

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

Du kan ange att funktionshanteringskonfigurationen ska hämtas från ett annat konfigurationsavsnitt genom att anropa Configuration.GetSection och skicka namnet på det önskade avsnittet. I följande exempel uppmanas funktionshanteraren att läsa från ett annat avsnitt med namnet "MyFeatureFlags" i stället:

using Microsoft.FeatureManagement;

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

Du kan använda funktionsfilter för att aktivera flaggor för villkorsstyrda funktioner. Information om hur du använder antingen inbyggda funktionsfilter eller skapa egna finns i Aktivera villkorsstyrda funktioner med funktionsfilter.

I stället för att hårdkoda funktionsflaggor i ditt program rekommenderar vi att du håller funktionsflaggor utanför programmet och hanterar dem separat. På så sätt kan du ändra flaggtillstånd när som helst och låta ändringarna börja gälla i programmet direkt. Azure App Configuration Service tillhandahåller ett dedikerat portalgränssnitt för att hantera alla dina funktionsflaggor. Azure App Configuration Service levererar också funktionsflaggor till ditt program direkt via dess .NET-klientbibliotek.

Det enklaste sättet att ansluta ditt ASP.NET Core-program till App Configuration är via konfigurationsprovidern som ingår i Microsoft.Azure.AppConfiguration.AspNetCore NuGet-paketet. När du har inkluderat en referens till paketet följer du dessa steg för att använda det här NuGet-paketet.

1. Öppna Program.cs fil och lägg till följande kod.

   using Microsoft.Extensions.Configuration.AzureAppConfiguration;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureAppConfiguration(options =>
       options.Connect(
           builder.Configuration["ConnectionStrings:AppConfig"])
           .UseFeatureFlags());
   

2. Uppdatera mellanprograms- och tjänstkonfigurationerna för din app med hjälp av följande kod.

   program.cs I klassen registrerar du Azure App Configuration Services och mellanprogram på objekten builder ochapp:

   builder.Services.AddAzureAppConfiguration();
   
   app.UseAzureAppConfiguration();
   

I ett typiskt scenario uppdaterar du dina funktionsflaggavärden regelbundet när du distribuerar och aktiverar olika funktioner i ditt program. Som standard cachelagras funktionsflaggans värden i 30 sekunder, så en uppdateringsåtgärd som utlöses när mellanprogrammet tar emot en begäran uppdaterar inte värdet förrän det cachelagrade värdet upphör att gälla. Följande kod visar hur du ändrar cachens förfallotid eller avsökningsintervall till 5 minuter genom att ange CacheExpirationInterval i anropet till UseFeatureFlags.

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

Deklaration av funktionsflagga

Varje funktionsflaggadeklaration har två delar: ett namn och en lista över ett eller flera filter som används för att utvärdera om en funktions tillstånd är på (det vill säga när dess värde är True). Ett filter definierar ett villkor för när en funktion ska aktiveras.

När en funktionsflagga har flera filter bläddras filterlistan i ordning tills ett av filtren fastställer att funktionen ska aktiveras. Då är funktionsflaggan aktiverad och eventuella återstående filterresultat hoppas över. Om inget filter anger att funktionen ska vara aktiverad är funktionsflaggan inaktiverad.

Funktionshanteraren stöder appsettings.json som konfigurationskälla för funktionsflaggor. I följande exempel visas hur du konfigurerar funktionsflaggor i en JSON-fil:

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

Enligt konventionen används avsnittet i FeatureManagement det här JSON-dokumentet för inställningar för funktionsflagga. I föregående exempel visas tre funktionsflaggor med sina filter definierade i egenskapen EnabledFor :

• FeatureA är på.
• FeatureB är av.
• FeatureC anger ett filter med namnet Percentage med en Parameters egenskap. Percentage är ett konfigurerbart filter. I det här exemplet Percentage anger du 50 procents sannolikhet för FeatureC att flaggan ska vara på. En instruktionsguide om hur du använder funktionsfilter finns i Använda funktionsfilter för att aktivera flaggor för villkorsstyrda funktioner.

Använda beroendeinmatning för att få åtkomst till IFeatureManager

För vissa åtgärder, till exempel att manuellt kontrollera funktionsflaggavärden, måste du hämta en instans av IFeatureManager. I ASP.NET Core MVC kan du komma åt funktionshanteraren IFeatureManager via beroendeinmatning. I följande exempel läggs ett argument av typen IFeatureManager till i konstruktorns signatur för en kontrollant. Körningen löser automatiskt referensen och tillhandahåller en implementering av gränssnittet när konstruktorn anropas. Om du använder en programmall där kontrollanten redan har ett eller flera beroendeinmatningsargument i konstruktorn, till exempel ILogger, kan du bara lägga till IFeatureManager som ett ytterligare argument:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

Referens för funktionsflagga

Definiera funktionsflaggor som strängvariabler för att referera till dem från kod:

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

Funktionsflaggakontroller

Ett vanligt mönster för funktionshantering är att kontrollera om en funktionsflagga är inställd på på och i så fall köra ett kodavsnitt. Till exempel:

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

Kontrollantåtgärder

Med MVC-styrenheter kan du använda FeatureGate attributet för att styra om en hel kontrollantklass eller en specifik åtgärd är aktiverad. Följande HomeController kontrollant måste FeatureA vara på innan någon åtgärd som kontrollantklassen innehåller kan köras:

using Microsoft.FeatureManagement.Mvc;

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

Följande Index åtgärd måste FeatureA vara på innan den kan köras:

using Microsoft.FeatureManagement.Mvc;

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

När en MVC-styrenhet eller åtgärd blockeras på grund av att den kontrollerande funktionsflaggan är avstängd anropas ett registrerat IDisabledFeaturesHandler-gränssnitt . IDisabledFeaturesHandler Standardgränssnittet returnerar en 404-statuskod till klienten utan svarstext.

MVC-vyer

Öppna _ViewImports.cshtml i katalogen Vyer och lägg till hjälpverktyget för funktionshanteraren:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

I MVC-vyer kan du använda en <feature> tagg för att återge innehåll baserat på om en funktionsflagga är aktiverad:

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

Om du vill visa alternativt innehåll när kraven inte uppfylls negate kan attributet användas.

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

Funktionstaggen <feature> kan också användas för att visa innehåll om några eller alla funktioner i en lista är aktiverade.

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

Du kan konfigurera MVC-filter så att de aktiveras baserat på tillståndet för en funktionsflagga. Den här funktionen är begränsad till filter som implementerar IAsyncActionFilter. Följande kod lägger till ett MVC-filter med namnet ThirdPartyActionFilter. Det här filtret utlöses endast i MVC-pipelinen om FeatureA det är aktiverat.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

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

Mellanprogram

Du kan också använda funktionsflaggor för att villkorligt lägga till programgrenar och mellanprogram. Följande kod infogar en mellanprogramskomponent i begärandepipelinen endast när FeatureA är aktiverad:

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

Den här koden bygger vidare på den mer generiska funktionen för att förgrena hela programmet baserat på en funktionsflagga:

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

Nästa steg

I den här självstudien har du lärt dig hur du implementerar funktionsflaggor i ditt ASP.NET Core-program med hjälp av biblioteken Microsoft.FeatureManagement . Mer information om stöd för funktionshantering i ASP.NET Core och App Configuration finns i följande resurser:

• exempelkod för ASP.NET Core-funktionsflagga
• Funktionsreferens för Microsoft.FeatureManagement
• Api-referens för Microsoft.FeatureManagement
• Hantera funktionsflaggor