Tutorial: Verwenden von Featureflags in einer ASP.NET Core-AppTutorial: Use feature flags in an ASP.NET Core app

Die .NET Core-Featureverwaltungsbibliotheken bieten idiomatische Unterstützung für die Implementierung von Featureflags in einer .NET- oder ASP.NET Core-Anwendung.The .NET Core Feature Management libraries provide idiomatic support for implementing feature flags in a .NET or ASP.NET Core application. Dank dieser Bibliotheken können Sie Ihrem Code Featureflags auf deklarative Weise hinzufügen, um nicht sämtliche Anweisungen vom Typ if manuell schreiben zu müssen.These libraries allow you to declaratively add feature flags to your code so that you don't have to write all the if statements for them manually.

Die Featureverwaltungsbibliotheken verwalten darüber hinaus Featureflag-Lebenszyklen im Hintergrund.The Feature Management libraries also manage feature flag lifecycles behind the scenes. Die Bibliotheken können Flagzustände aktualisieren und zwischenspeichern, garantieren, dass ein Flagzustand während eines Anforderungsaufrufs unveränderlich ist, und Ähnliches.For example, the libraries refresh and cache flag states, or guarantee a flag state to be immutable during a request call. Darüber hinaus bietet die ASP.NET Core-Bibliothek sofort einsetzbare Integrationen – einschließlich MVC-Controlleraktionen, Ansichten, Routen und Middleware.In addition, the ASP.NET Core library offers out-of-the-box integrations, including MVC controller actions, views, routes, and middleware.

Unter Schnellstart: Hinzufügen von Featureflags zu einer ASP.NET Core-App werden mehrere Methoden gezeigt, mit denen Sie Featureflags in einer ASP.NET Core-Anwendung hinzufügen können.The Add feature flags to an ASP.NET Core app Quickstart shows several ways to add feature flags in an ASP.NET Core application. Diese Methoden werden im vorliegenden Tutorial näher erläutert.This tutorial explains these methods in more detail. Eine umfassende Referenz finden Sie in der Featureverwaltungsdokumentation für ASP.NET Core.For a complete reference, see the ASP.NET Core feature management documentation.

In diesem Tutorial lernen Sie Folgendes:In this tutorial, you will learn how to:

  • Hinzufügen von Featureflags in wichtigen Teilen Ihrer Anwendung, um die Verfügbarkeit von Features zu steuernAdd feature flags in key parts of your application to control feature availability.
  • Integrieren in App Configuration, wenn Sie damit Featureflags verwaltenIntegrate with App Configuration when you're using it to manage feature flags.

Einrichten der FeatureverwaltungSet up feature management

Fügen Sie einen Verweis auf die NuGet-Pakete Microsoft.FeatureManagement.AspNetCore und Microsoft.FeatureManagement hinzu, um den .NET Core-Feature-Manager zu nutzen.Add a reference to the Microsoft.FeatureManagement.AspNetCore and Microsoft.FeatureManagement NuGet packages to utilize the .NET Core feature manager.

Der .NET Core-Feature-Manager IFeatureManager ruft Featureflags aus dem nativen Konfigurationssystem des Frameworks ab.The .NET Core feature manager IFeatureManager gets feature flags from the framework's native configuration system. Dadurch können Sie die Featureflags Ihrer Anwendung mit einer beliebigen, von .NET Core unterstützten Konfigurationsquelle konfigurieren – unter anderem mit der lokalen Datei appsettings.json oder mit Umgebungsvariablen.As a result, you can define your application's feature flags by using any configuration source that .NET Core supports, including the local appsettings.json file or environment variables. IFeatureManager basiert auf der .NET Core-Abhängigkeitsinjektion.IFeatureManager relies on .NET Core dependency injection. Die Featureverwaltungsdienste können unter Verwendung von Standardkonventionen registriert werden:You can register the feature management services by using standard conventions:

using Microsoft.FeatureManagement;

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

Der Feature-Manager ruft Featureflags standardmäßig aus dem Abschnitt "FeatureManagement" der .NET Core-Konfigurationsdaten ab.By default, the feature manager retrieves feature flags from the "FeatureManagement" section of the .NET Core configuration data. Im folgenden Beispiel wird er angewiesen, sie stattdessen aus einem Abschnitt namens "MyFeatureFlags" zu lesen:The following example tells the feature manager to read from a different section called "MyFeatureFlags" instead:

using Microsoft.FeatureManagement;

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

Wenn Sie in Ihren Featureflags Filter verwenden, müssen Sie eine zusätzliche Bibliothek einschließen und registrieren.If you use filters in your feature flags, you need to include an additional library and register it. Das folgende Beispiel zeigt, wie Sie einen integrierten Featurefilter namens PercentageFilter verwenden:The following example shows how to use a built-in feature filter called PercentageFilter:

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

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

Featureflags sollten sich außerhalb der Anwendung befinden und separat verwaltet werden.We recommend that you keep feature flags outside the application and manage them separately. Dadurch können Sie Flagzustände jederzeit ändern, und die Änderungen werden in der Anwendung sofort wirksam.Doing so allows you to modify flag states at any time and have those changes take effect in the application right away. Mit App Configuration können Sie alle Ihre Featureflags über eine dedizierte Portalbenutzeroberfläche an einem zentralen Ort organisieren und steuern.App Configuration provides a centralized place for organizing and controlling all your feature flags through a dedicated portal UI. App Configuration übermittelt darüber hinaus die Flags über seine .NET Core-Clientbibliotheken direkt an Ihre Anwendung.App Configuration also delivers the flags to your application directly through its .NET Core client libraries.

Die Verbindung zwischen Ihrer ASP.NET Core-Anwendung und App Configuration lässt sich am einfachsten über den Konfigurationsanbieter Microsoft.Azure.AppConfiguration.AspNetCore herstellen.The easiest way to connect your ASP.NET Core application to App Configuration is through the configuration provider Microsoft.Azure.AppConfiguration.AspNetCore. Führen Sie die folgenden Schritte aus, um dieses NuGet-Paket zu verwenden.Follow these steps to use this NuGet package.

  1. Öffnen Sie die Datei Program.cs , und fügen Sie folgenden Code hinzu.Open Program.cs file and add the following code.

    using Microsoft.Extensions.Configuration.AzureAppConfiguration;
    
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
               .ConfigureAppConfiguration((hostingContext, config) => {
                   var settings = config.Build();
                   config.AddAzureAppConfiguration(options => {
                       options.Connect(settings["ConnectionStrings:AppConfig"])
                              .UseFeatureFlags();
                    });
               })
               .UseStartup<Startup>();
    
  2. Öffnen Sie Startup.cs , und aktualisieren Sie die Configure-Methode, um die integrierte Middleware namens UseAzureAppConfiguration hinzuzufügen.Open Startup.cs and update the Configure method to add the built-in middleware called UseAzureAppConfiguration. Diese Middleware gestattet die regelmäßige Aktualisierung der Featureflagwerte, während die ASP.NET Core-Web-App weiterhin Anforderungen empfängt.This middleware allows the feature flag values to be refreshed at a recurring interval while the ASP.NET Core web app continues to receive requests.

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseAzureAppConfiguration();
        app.UseMvc();
    }
    

Die Werte von Featureflags ändern sich üblicherweise im Laufe der Zeit.Feature flag values are expected to change over time. Standardmäßig werden die Featureflagwerte für einen Zeitraum von 30 Sekunden zwischengespeichert, daher würde ein Aktualisierungsvorgang, der ausgelöst wird, wenn die Middleware eine Anforderung empfängt, den Wert erst nach Ablauf des zwischengespeicherten Werts aktualisieren.By default, the feature flag values are cached for a period of 30 seconds, so a refresh operation triggered when the middleware receives a request would not update the value until the cached value expires. Der folgende Code zeigt, wie Sie die Cacheablaufzeit oder das Abrufintervall im Aufruf options.UseFeatureFlags() in einen Wert von fünf Minuten ändern.The following code shows how to change the cache expiration time or polling interval to 5 minutes in the options.UseFeatureFlags() call.

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

FeatureflagdeklarationFeature flag declaration

Jedes Featureflag besteht aus zwei Teilen: einem Namen und einer Filterliste, anhand der ausgewertet wird, ob ein Feature aktiviert ist (der Wert also True lautet).Each feature flag has two parts: a name and a list of one or more filters that are used to evaluate if a feature's state is on (that is, when its value is True). Ein Filter definiert einen Anwendungsfall für die Aktivierung eines Features.A filter defines a use case for when a feature should be turned on.

Verfügt ein Featureflag über mehrere Filter, wird die Filterliste in der angegebenen Reihenfolge durchlaufen, bis einer der Filter angibt, dass das Feature aktiviert werden soll.When a feature flag has multiple filters, the filter list is traversed in order until one of the filters determines the feature should be enabled. Daraufhin ist das Featureflag aktiviert , und alle weiteren Filterergebnisse werden übersprungen.At that point, the feature flag is on , and any remaining filter results are skipped. Falls durch keinen Filter angegeben wird, dass das Feature aktiviert werden soll, ist das Featureflag deaktiviert.If no filter indicates the feature should be enabled, the feature flag is off.

Der Feature-Manager unterstützt appsettings.json als Konfigurationsquelle für Featureflags.The feature manager supports appsettings.json as a configuration source for feature flags. Das folgende Beispiel zeigt die Einrichtung von Featureflags in einer JSON-Datei:The following example shows how to set up feature flags in a JSON file:

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

Der Abschnitt FeatureManagement dieses JSON-Dokuments wird konventionsgemäß für Featureflageinstellungen verwendet.By convention, the FeatureManagement section of this JSON document is used for feature flag settings. Das vorherige Beispiel enthält drei Featureflags, deren Filter in der Eigenschaft EnabledFor definiert sind:The prior example shows three feature flags with their filters defined in the EnabledFor property:

  • FeatureA ist aktiviert.FeatureA is on.
  • FeatureB ist deaktiviert.FeatureB is off.
  • FeatureC gibt einen Filter namens Percentage mit einer Eigenschaft vom Typ Parameters an.FeatureC specifies a filter named Percentage with a Parameters property. Percentage ist ein konfigurierbarer Filter.Percentage is a configurable filter. In diesem Beispiel gibt Percentage an, dass das Flag FeatureC mit einer Wahrscheinlichkeit von 50 Prozent aktiviert ist.In this example, Percentage specifies a 50-percent probability for the FeatureC flag to be on.

Featureflag-VerweiseFeature flag references

Damit Sie im Code einfach auf Featureflags verweisen können, sollten Sie sie als enum-Variablen definieren:So that you can easily reference feature flags in code, you should define them as enum variables:

public enum MyFeatureFlags
{
    FeatureA,
    FeatureB,
    FeatureC
}

Überprüfen von FeatureflagsFeature flag checks

Bei der Featureverwaltung wird grundsätzlich zunächst geprüft, ob ein Featureflag aktiviert ist.The basic pattern of feature management is to first check if a feature flag is set to on. Ist dies der Fall, führt der Feature-Manager die im Feature enthaltenen Aktionen aus.If so, the feature manager then runs the actions that the feature contains. Beispiel:For example:

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

AbhängigkeitsinjektionDependency injection

In ASP.NET Core MVC kann auf den Feature-Manager IFeatureManager mittels Abhängigkeitsinjektion zugegriffen werden:In ASP.NET Core MVC, you can access the feature manager IFeatureManager through dependency injection:

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

ControlleraktionenController actions

In MVC-Controllern steuern Sie mithilfe eines Attributs vom Typ FeatureGate, ob eine gesamte Controllerklasse oder eine spezifische Aktion aktiviert wird.In MVC controllers, you use the FeatureGate attribute to control whether a whole controller class or a specific action is enabled. Für den folgenden Controller HomeController muss FeatureAaktiviert sein, damit eine der in der Controllerklasse enthaltenen Aktionen ausgeführt werden kann:The following HomeController controller requires FeatureA to be on before any action the controller class contains can be executed:

using Microsoft.FeatureManagement.Mvc;

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

Für die folgende Aktion Index muss FeatureAaktiviert sein, damit sie ausgeführt werden kann:The following Index action requires FeatureA to be on before it can run:

using Microsoft.FeatureManagement.Mvc;

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

Ist ein MVC-Controller oder eine Aktion blockiert, weil das steuernde Featureflag deaktiviert ist, wird eine registrierte Schnittstelle (IDisabledFeaturesHandler) aufgerufen.When an MVC controller or action is blocked because the controlling feature flag is off , a registered IDisabledFeaturesHandler interface is called. Die Standardschnittstelle IDisabledFeaturesHandler gibt den Statuscode 404 ohne Antworttext an den Client zurück.The default IDisabledFeaturesHandler interface returns a 404 status code to the client with no response body.

MVC-AnsichtenMVC views

Öffnen Sie _ViewImports.cshtml im Verzeichnis Views , und fügen Sie das Taghilfsprogramm für den Feature-Manager hinzu:Open _ViewImports.cshtml in the Views directory, and add the feature manager tag helper:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

In MVC-Ansichten können Sie ein Tag vom Typ <feature> verwenden, um das Rendern von Inhalten vom Aktivierungsstatus eines Featureflags abhängig zu machen:In MVC views, you can use a <feature> tag to render content based on whether a feature flag is enabled:

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

Um alternative Inhalte anzuzeigen, wenn die Anforderungen nicht erfüllt sind, kann das negate-Attribut verwendet werden.To display alternate content when the requirements are not met the negate attribute can be used.

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

Das <feature>-Tag kann auch verwendet werden, um Inhalte anzuzeigen, wenn ein oder alle Features in einer Liste aktiviert sind.The feature <feature> tag can also be used to show content if any or all features in a list are enabled.

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

Sie können MVC-Filter so einrichten, dass sie abhängig vom Zustand eines Featureflags aktiviert werden.You can set up MVC filters so that they're activated based on the state of a feature flag. Im folgenden Code wird ein MVC-Filter namens SomeMvcFilter hinzugefügt.The following code adds an MVC filter named SomeMvcFilter. Dieser Filter wird innerhalb der MVC-Pipeline nur ausgelöst, wenn FeatureA aktiviert ist.This filter is triggered within the MVC pipeline only if FeatureA is enabled. Diese Funktion ist auf IAsyncActionFilter beschränkt.This capability is limited to IAsyncActionFilter.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

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

MiddlewareMiddleware

Featureflags ermöglichen außerdem das bedingte Hinzufügen von Anwendungsbranches und Middleware.You can also use feature flags to conditionally add application branches and middleware. Im folgenden Code wird nur dann eine Middlewarekomponente in die Anforderungspipeline eingefügt, wenn FeatureA aktiviert ist:The following code inserts a middleware component in the request pipeline only when FeatureA is enabled:

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

Dieser Code baut auf der allgemeineren Verzweigung der gesamten Anwendung auf der Grundlage eines Featureflags auf:This code builds off the more-generic capability to branch the entire application based on a feature flag:

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

Nächste SchritteNext steps

In diesem Tutorial haben Sie gelernt, wie Sie Featureflags in Ihrer ASP.NET Core-Anwendung unter Verwendung der Bibliotheken vom Typ Microsoft.FeatureManagement implementieren.In this tutorial, you learned how to implement feature flags in your ASP.NET Core application by using the Microsoft.FeatureManagement libraries. Die folgenden Ressourcen enthalten weitere Informationen zur Unterstützung der Featureverwaltung in ASP.NET Core und App Configuration:For more information about feature management support in ASP.NET Core and App Configuration, see the following resources: