Zelfstudie: Functievlaggen gebruiken in een ASP.NET Core-app

Artikel
08/27/2021
8 minuten om te lezen

De .NET Core Feature Management-bibliotheken bieden idiomatische ondersteuning voor het implementeren van functievlaggen in een .NET- of ASP.NET Core-toepassing. Met deze bibliotheken kunt u functievlaggen declaratief toevoegen aan uw code, zodat u niet handmatig code hoeft te schrijven om functies met instructies in of uit te if schakelen.

De Feature Management-bibliotheken beheren ook de levenscyclus van functievlaggen achter de schermen. Bijvoorbeeld: de bibliotheken worden vernieuwd en slaan vlagstatussen op in een cache of garanderen dat een vlagstatus onveranderbaar is tijdens het aanroepen van een aanvraag. Daarnaast biedt de ASP.NET Core-bibliotheek kant-en-klare integraties, waaronder acties, weergaven, routes en middleware voor MVC-controllers.

In de quickstart Functievlaggen toevoegen aan ASP.NET Core app ziet u een eenvoudig voorbeeld van het gebruik van functievlaggen in een ASP.NET Core app. In deze zelfstudie ziet u aanvullende installatieopties en mogelijkheden van de functiebeheerbibliotheken. U kunt de voorbeeld-app die in de quickstart is gemaakt, gebruiken om de voorbeeldcode uit te proberen die in deze zelfstudie wordt weergegeven.

Zie Microsoft.FeatureManagement Namespacevoor ASP.NET Core api-referentiedocumentatie voor functiebeheer.

In deze zelfstudie leert u het volgende:

Voeg functievlaggen toe aan de belangrijkste onderdelen van uw toepassing om de beschikbaarheid van functies te bepalen.
Integreer met App Configuration wanneer u deze gebruikt voor het beheren van functievlaggen.

Functiebeheer instellen

Als u toegang wilt krijgen tot het functiebeheer van .NET Core, moet uw app verwijzingen hebben naar het Microsoft.FeatureManagement.AspNetCore NuGet-pakket.

.NET Core-functiebeheer wordt geconfigureerd vanuit het systeemeigen configuratiesysteem van het framework. Als gevolg hiervan kunt u de instellingen voor functievlagken van uw toepassing definiëren met behulp van een configuratiebron die door .NET Core wordt ondersteund, met inbegrip van de lokale appsettings.js voor bestands- of omgevingsvariabelen.

De functiebeheerder haalt standaard de configuratie van functievlaggetalen op uit de "FeatureManagement" sectie van de .NET Core-configuratiegegevens. Als u de standaardconfiguratielocatie wilt gebruiken, roept u de methode AddFeatureManagement van de IServiceCollection aan die is doorgegeven aan de methode ConfigureServices van de klasse Startup.

using Microsoft.FeatureManagement;

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

U kunt opgeven dat de configuratie van functiebeheer moet worden opgehaald uit een andere configuratiesectie door Configuration.GetSection aan te roepen en de naam van de gewenste sectie door te geven. In het volgende voorbeeld moet de functiebeheerder deze echter lezen vanuit een andere sectie met de naam "MyFeatureFlags":

using Microsoft.FeatureManagement;

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

Als u filters gebruikt in uw functievlaggen, moet u de naamruimte Microsoft.FeatureManagement.FeatureFilters opnemen en een aanroep toevoegen aan AddFeatureFilters waarin u de typenaam opgeeft van het filter dat u wilt gebruiken als het algemene type van de methode. Zie Gefaseerd rollout van functies inschakelen voor doelgroepen voor meer informatie over het gebruik van functiefilters omfunctionaliteit dynamisch in en uit te schakelen.

In het volgende voorbeeld ziet u hoe u een ingebouwd functiefilter gebruikt met de naam PercentageFilter:

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

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

In plaats van uw functievlaggen hard te coderen in uw toepassing, raden we u aan functievlaggen buiten de toepassing te houden en ze afzonderlijk te beheren. Als u dit doet, kunt u de status van de vlaggen op elk gewenst moment wijzigen. Deze wijzigingen worden direct doorgevoerd in de toepassing. De Azure App Configuration-service biedt een speciale portal-ui voor het beheren van al uw functievlaggen. De Azure App Configuration service levert de functievlaggen ook rechtstreeks aan uw toepassing via de .NET Core-clientbibliotheken.

De eenvoudigste manier om uw ASP.NET Core te verbinden met App Configuration is via de configuratieprovider die is opgenomen in het Microsoft.Azure.AppConfiguration.AspNetCore NuGet-pakket. Nadat u een verwijzing naar het pakket heeft gemaakt, volgt u deze stappen om dit NuGet-pakket te gebruiken.

Open het bestand Program.cs en voeg de volgende code toe.

Belangrijk

CreateHostBuilder wordt vervangen door CreateWebHostBuilder in .NET Core 3.x. Selecteer de juiste syntaxis op basis van uw omgeving.

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

Open Startup.cs en werk de Configure methode en bij om de ingebouwde middleware met de naam ConfigureServices toe te UseAzureAppConfiguration voegen. Met deze middleware kunnen de waarden van de functievlaggen periodiek worden vernieuwd terwijl de ASP.NET Core-web-app aanvragen blijft ontvangen.
```
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseAzureAppConfiguration();
}
```
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureAppConfiguration();
}
```

In een typisch scenario werkt u de waarden van de functievlag regelmatig bij wanneer u uw toepassing implementeert en inschakelen en verschillende functies van uw toepassing. Standaard worden de waarden van de functievlaggen in de cache opgeslagen gedurende een periode van 30 seconden. Als een vernieuwingsbewerking wordt geactiveerd terwijl de middleware een aanvraag ontvangt, wordt de waarde dus pas bijgewerkt als de waarde in de cache verloopt. De volgende code laat zien hoe u de verlooptijd van de cache of het polling-interval wijzigt in 5 minuten door CacheExpirationInterval in te stellen in de aanroep van UseFeatureFlags.

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

Declaratie van functievlaggen

Elke functievlagdeclaratie bestaat uit twee delen: een naam en een lijst met een of meer filters die worden gebruikt om te evalueren of de status van een functie is aan (dat wil zeggen, wanneer de waarde ervan True is). Een filter definieert een criterium voor wanneer een functie moet worden ingeschakeld.

Wanneer een functievlag meerdere filters heeft, wordt de filterlijst in de juiste volgorde doorgelopen, totdat een van de filters bepaalt dat de functie moet worden ingeschakeld. Op dat moment is de functievlag aan en worden alle resterende filterresultaten overgeslagen. Als geen enkel filter aangeeft dat de functie moet worden ingeschakeld, is de functievlag uit.

De functiebeheerder ondersteunt appsettings.json als een configuratiebron voor functievlaggen. In het volgende voorbeeld ziet u hoe u functievlaggen kunt instellen in een JSON-bestand:

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

Standaard wordt het gedeelte FeatureManagement van dit JSON-document gebruikt voor instellingen voor functievlaggen. Het vorige voorbeeld toont drie functievlaggen waarvoor de filters zijn gedefinieerd in de eigenschap EnabledFor:

FeatureA is aan.
FeatureB is uit.
Met FeatureC geeft u een filter op met de naam Percentage met een eigenschap Parameters. Percentage is een configureerbaar filter. In dit voorbeeld geeft Percentage een kans van 50 procent dat de vlag FeatureC aan is. Zie Functiefilters gebruiken om voorwaardelijke functievlaggen in teschakelen voor een handleiding over het gebruik van functiefilters.

Afhankelijkheidsinjectie gebruiken voor toegang tot IFeatureManager

Voor sommige bewerkingen, zoals het handmatig controleren van functievlagwaarden, moet u een instantie van IFeatureManager krijgen. In ASP.NET Core MVC hebt u toegang tot de functiebeheerder IFeatureManager via afhankelijkheidsinjectie. In het volgende voorbeeld wordt een argument van het type toegevoegd aan de handtekening IFeatureManager van de constructor voor een controller. De runtime lost de verwijzing automatisch op en levert een van de interface bij het aanroepen van de constructor. Als u een toepassingssjabloon gebruikt waarin de controller al een of meer argumenten voor afhankelijkheidsinjectie in de constructor heeft, zoals , kunt u gewoon toevoegen als ILogger IFeatureManager een extra 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;
    }
}

Verwijzingen naar functievlaggen

Definieer functievlaggen als tekenreeksvariabelen om er vanuit code naar te verwijzen:

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

Controles van functievlaggen

Een veelvoorkomende patroon van functiebeheer is om te controleren of een functievlag is ingesteld op Aan en zo ja, een codesectie uit te voeren. Bijvoorbeeld:

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

Controller-acties

Met MVC-controllers kunt u het kenmerk gebruiken om te bepalen of een hele controllerklasse of FeatureGate een specifieke actie is ingeschakeld. Voor de volgende HomeController-controller moet FeatureA worden ingesteld op aan voordat een actie in de controllerklasse kan worden uitgevoerd:

using Microsoft.FeatureManagement.Mvc;

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

Voor de volgende actie Index moet FeatureA aan zijn voordat deze kan worden uitgevoerd:

using Microsoft.FeatureManagement.Mvc;

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

Wanneer een MVC-controller of -actie wordt geblokkeerd omdat de besturingsfunctievlag uit is, wordt een geregistreerde IDisabledFeaturesHandler-interface aangeroepen. De standaard IDisabledFeaturesHandler-interface retourneert een 404-statuscode naar de client zonder hoofdtekst van de reactie.

MVC-weergaven

Open _ViewImports.cshtml in de map Views en voeg de taghelper voor functiebeheer toe:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

In MVC-weergaven kunt u een <feature>-tag gebruiken om inhoud weer te geven op basis van het feit of een functievlag is ingeschakeld:

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

Om alternatieve inhoud weer te geven als niet aan de vereisten wordt voldaan, kan het kenmerk negate worden gebruikt.

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

De <feature>-tag kan ook worden gebruikt voor het weergeven van inhoud als een of alle functies in een lijst zijn ingeschakeld.

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

U kunt MVC-filters zo instellen dat ze worden geactiveerd op basis van de status van een functievlag. Deze mogelijkheid is beperkt tot filters die IAsyncActionFilter implementeren. Met de volgende code wordt een MVC-filter toegevoegd met de naam ThirdPartyActionFilter. Dit filter wordt alleen in de MVC-pijplijn geactiveerd als FeatureA is ingeschakeld.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

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

Middleware

U kunt functievlaggen ook gebruiken om voorwaardelijk toepassingsvertakkingen en middleware toe te voegen. Met de volgende code wordt alleen een middleware-onderdeel in de aanvraagpijplijn ingevoegd wanneer FeatureA is ingeschakeld:

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

Deze code bouwt voort op de meer generieke mogelijkheid om de hele toepassing te vertakken op basis van een functievlag:

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

Volgende stappen

In deze zelfstudie hebt u geleerd hoe u functievlaggen kunt implementeren in een ASP.NET Core-toepassing met behulp van de Microsoft.FeatureManagement-bibliotheken. Raadpleeg de volgende bronnen voor meer informatie over de ondersteuning van functiebeheer in ASP.NET Core en App Configuration: