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

Artikel
08/29/2021
8 minuter för att läsa

.NET Core-biblioteken för funktionshantering har idiomatiskt stöd för implementering av 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 också livscykeln för funktionsflaggor i bakgrunden. Biblioteken kan till exempel uppdatera och cachelagra flaggtillstånd eller garantera att ett flaggtillstånd inte kan ändras under ett begärandeanrop. Dessutom erbjuder ASP.NET Core-biblioteket in-of-the-box-integreringar, inklusive MVC-kontrollantåtgärder, vyer, vägar och mellanprogram.

Snabbstarten Lägg till funktionsflaggor ASP.NET Core en 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 biblioteken för funktionshantering. Du kan använda exempelappen som skapades i snabbstarten för att prova exempelkoden som visas i den här självstudien.

Mer information ASP.NET Core API-referensdokumentationen för funktionshantering finns i Microsoft.FeatureManagement Namespace.

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

Lägg till funktionsflaggor i viktiga delar av programmet för att kontrollera funktionstillgänglighet.
Integrera med App Configuration när du använder den för att hantera funktionsflaggor.

Konfigurera funktionshantering

För att få åtkomst till funktionshanteraren för .NET Core måste din app ha referenser till Microsoft.FeatureManagement.AspNetCore NuGet-paketet.

Funktionshanteraren för .NET Core konfigureras från ramverket interna konfigurationssystem. Därför kan du definiera programmets inställningar för funktionsflaggan med hjälp av valfri konfigurationskälla som .NET Core stöder, inklusive de lokalaappsettings.jspå fil- eller miljövariabler.

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

using Microsoft.FeatureManagement;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        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;

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

Om du använder filter i funktionsflaggorna måste du inkludera namnområdet Microsoft.FeatureManagement.FeatureFilters och lägga till ett anrop till AddFeatureFilters som anger typnamnet för det filter som du vill använda som den allmänna typen av metod. Mer information om hur du använder funktionsfilter för att dynamiskt aktivera och inaktivera funktioner finns i Aktivera mellandelade funktioner för målgrupper.

I följande exempel visas hur du använder ett inbyggt funktionsfilter med namnet PercentageFilter :

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

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

I stället för att hårdkoda funktionsflaggorna i ditt program rekommenderar vi att du behåller funktionsflaggor utanför programmet och hanterar dem separat. På så sätt kan du ändra flagg tillstånd när som helst och få dessa ändringar att gälla i programmet direkt. Tjänsten Azure App Configuration tillhandahåller ett dedikerat portalgränssnitt för att hantera alla dina funktionsflaggor. Tjänsten Azure App Configuration levererar även funktionsflaggorna till ditt program direkt via dess .NET Core-klientbibliotek.

Det enklaste sättet att ansluta ASP.NET Core 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.

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

Viktigt

CreateHostBuilder ersätter CreateWebHostBuilder i .NET Core 3.x. Välj rätt syntax baserat på din miljö.

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>());

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>());

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
                .ConfigureAppConfiguration(config =>
                {
                    var settings = config.Build();
                    config.AddAzureAppConfiguration(options =>
                        options.Connect(settings["ConnectionStrings:AppConfig"]).UseFeatureFlags());
                }).UseStartup<Startup>();

Öppna Startup.cs och uppdatera metoden Configure och för att lägga till det ConfigureServices inbyggda mellanprogram som heter UseAzureAppConfiguration . Det här mellanprogrammet gör att funktionsflaggans värden kan uppdateras med ett återkommande intervall ASP.NET Core webbappen fortsätter att ta emot begäranden.
```
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseAzureAppConfiguration();
}
```
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureAppConfiguration();
}
```

I ett vanligt scenario uppdaterar du funktionsflaggans värden med jämna mellanrum när du distribuerar och aktiverar och olika funktioner i ditt program. Som standard cachelagras funktionsflaggans värden i 30 sekunder, så en uppdateringsåtgärd som utlöses när mellanprogram 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 förfallotiden för cachen eller avsökningsintervallet till 5 minuter genom att ange CacheExpirationInterval i anropet till UseFeatureFlags.

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

Deklaration av funktionsflagga

Varje deklaration av funktionsflaggan har två delar: ett namn och en lista med 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 bestämmer att funktionen ska aktiveras. Då är funktionsflaggan på, och eventuella återstående filterresultat hoppas över. Om inget filter indikerar att funktionen ska vara aktiverad är funktionsflaggan inaktiverad.

Funktionshanteraren stöderappsettings.js på som en konfigurationskälla för funktionsflaggor. I följande exempel visas hur du ställer in 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
                    }
                }
            ]
        }
    }
}

Som konvention används FeatureManagement avsnittet i det här JSON-dokumentet för inställningar för funktionsflaggan. I föregående exempel visas tre funktionsflaggor med deras filter definierade i EnabledFor egenskapen :

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 en sannolikhet på 50 procent för att flaggan ska vara FeatureC på. En guide 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 funktionsflaggans värden, måste du hämta en instans av IFeatureManager. I ASP.NET Core MVC kan du komma åt funktionshanteraren via IFeatureManager beroendeinjektion. I följande exempel läggs ett argument av typen IFeatureManager till i signaturen för konstruktorn för en kontrollant. Körningen matchar automatiskt referensen och tillhandahåller ett av -gränssnittet när du anropar konstruktorn. Om du använder en programmall där kontrollanten redan har ett eller flera argument för beroendeinjektion i konstruktorn, till exempel , kan du bara lägga till ILogger IFeatureManager som ytterligare ett argument:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

    public HomeController(IFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

Referens för funktionsflaggan

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";
}

Funktionsflaggan kontrollerar

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. 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 FeatureA måste 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 åtgärd Index måste vara på FeatureA innan den kan köras:

using Microsoft.FeatureManagement.Mvc;

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

När en MVC-kontrollant eller åtgärd blockeras eftersom kontrollfunktionsflaggan är inaktiverad anropas ett registrerat IDisabledFeaturesHandler-gränssnitt. IDisabledFeaturesHandlerStandardgränssnittet returnerar en 404-statuskod till klienten utan svarstext.

MVC-vyer

Öppna _ViewImports.cshtml i katalogen Vyer och lägg till tag helper 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>

<feature>Funktionstaggen 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 ä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 pipelinen för begäran endast när FeatureA är aktiverat:

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

Den här koden bygger på den mer allmänna 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 ASP.NET Core med hjälp av Microsoft.FeatureManagement biblioteken. Mer information om stöd för funktionshantering i ASP.NET Core och App Configuration finns i följande resurser: