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

Artikel
02/28/2024

De .NET Feature Management-bibliotheken bieden idiomatische ondersteuning voor het implementeren van functievlagmen in een .NET- of ASP.NET Core-toepassing. Met deze bibliotheken kunt u declaratief functievlagmen toevoegen aan uw code, zodat u geen code handmatig hoeft te schrijven om functies met if instructies in of uit te 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.

Zie Microsoft.FeatureManagement-naamruimte voor de ASP.NET Core-documentatie over de API 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.

Vereisten

In de quickstart functievlagmen toevoegen aan een ASP.NET Core-app ziet u een eenvoudig voorbeeld van het gebruik van functievlagmen in een ASP.NET Core-toepassing. In deze zelfstudie ziet u aanvullende instellingsopties en mogelijkheden van de bibliotheken voor functiebeheer. U kunt de voorbeeld-app die u in de quickstart hebt gemaakt, gebruiken om de voorbeeldcode uit te proberen die in deze zelfstudie wordt weergegeven.

Functiebeheer instellen

Voor toegang tot .NET-functiebeheer moet uw app verwijzingen hebben naar de Microsoft.Azure.AppConfiguration.AspNetCore en Microsoft.FeatureManagement.AspNetCore NuGet-pakketten.

Het .NET-functiebeheer is 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 wordt ondersteund, inclusief het lokale appsettings.json bestand of de omgevingsvariabelen.

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

using Microsoft.FeatureManagement;

builder.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;

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

Als u filters in uw functievlagmen gebruikt, moet u de naamruimte Microsoft.FeatureManagement.FeatureFilters opnemen en een aanroep toevoegen aan AddFeatureFilter met de typenaam van het filter dat u wilt gebruiken als het algemene type van de methode. Zie Gefaseerde implementatie van functies inschakelen voor doelgroepen voor meer informatie over het gebruik van functiefilters om functionaliteit dynamisch in te schakelen.

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

using Microsoft.FeatureManagement;

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

In plaats van uw functievlagmen hard te coderen in uw toepassing, wordt u aangeraden functievlagmen buiten de toepassing te houden en deze 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 toegewezen portalgebruikersinterface voor het beheren van al uw functievlagmen. De Azure-app Configuration-service levert ook de functievlagmen rechtstreeks aan uw toepassing via de .NET-clientbibliotheken.

De eenvoudigste manier om uw ASP.NET Core-toepassing 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 hebt opgegeven, volgt u deze stappen om dit NuGet-pakket te gebruiken.

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

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

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

Werk de middleware- en serviceconfiguraties voor uw app bij met behulp van de volgende code.

Registreer in de program.cs klasse de Azure-app Configuration-services en middleware op de builder en app objecten:
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

In een typisch scenario werkt u de waarden van uw functievlag regelmatig bij terwijl u implementeert en verschillende functies van uw toepassing inschakelt en inschakelt. 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 de CacheExpirationInterval in te stellen in de aanroep naar UseFeatureFlags.

config.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["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 ingeschakeld (dat wil gezegd, wanneer de waarde is True). 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 FeatureCaan is. Zie Functiefilters gebruiken om voorwaardelijke functievlagmen in te schakelen voor instructies voor het gebruik van functiefilters.

Afhankelijkheidsinjectie gebruiken voor toegang tot IFeatureManager

Voor sommige bewerkingen, zoals het handmatig controleren van functievlagwaarden, moet u een exemplaar van IFeatureManager ophalen. In ASP.NET Core MVC hebt u toegang tot de functiebeheerder IFeatureManager via afhankelijkheidsinjectie. In het volgende voorbeeld wordt een argument van het type IFeatureManager toegevoegd aan de handtekening van de constructor voor een controller. De runtime lost de verwijzing automatisch op en biedt een implementatie van de interface bij het aanroepen van de constructor. Als u een toepassingssjabloon gebruikt waarin de controller al een of meer afhankelijkheidsinjectieargumenten in de constructor heeft, zoals ILogger, kunt u gewoon toevoegen IFeatureManager als een extra argument:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

Verwijzingen naar functievlaggen

Functievlagmen definiëren als tekenreeksvariabelen om ernaar te verwijzen vanuit code:

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

Controles van functievlaggen

Een veelvoorkomend patroon van functiebeheer is om te controleren of een functievlag is ingesteld op Aan en als dat het het volgende is, voert u een codesectie uit. Voorbeeld:

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

Controller-acties

Met MVC-controllers kunt u het FeatureGate kenmerk gebruiken om te bepalen of een hele controllerklasse of 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 FeatureAaan 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 vlag voor de besturingsfunctie is uitgeschakeld, 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: