.NET-functiebeheer

De .NET-functiebeheerbibliotheek biedt een manier om toepassingsfunctionaliteit te ontwikkelen en beschikbaar te maken op basis van functievlagmen. Wanneer een nieuwe functie wordt ontwikkeld, hebben veel toepassingen speciale vereisten, zoals wanneer de functie moet worden ingeschakeld en onder welke omstandigheden. Deze bibliotheek biedt een manier om deze relaties te definiëren. Het kan ook worden geïntegreerd met veelgebruikte .NET-codepatronen om deze functies beschikbaar te maken.

Functievlagmen bieden een manier voor .NET- en ASP.NET Core-toepassingen om functies dynamisch in of uit te schakelen. U kunt functievlagmen gebruiken in eenvoudige gebruiksvoorbeelden, zoals voorwaardelijke instructies. U kunt functievlagmen ook gebruiken in geavanceerdere scenario's, zoals het voorwaardelijk toevoegen van routes of MVC-filters (model-view-controller). Functievlagmen zijn gebouwd op het .NET Core-configuratiesysteem. Elke .NET Core-configuratieprovider kan fungeren als de backbone voor functievlaggen.

Hier volgen enkele voordelen van het gebruik van de .NET-functiebeheerbibliotheek:

• Het maakt gebruik van algemene conventies voor functiebeheer.
• Het heeft een lage barrière om binnen te komen:
  • Het is gebouwd op de IConfiguration interface.
  • Het ondersteunt het instellen van JSON-bestandsfeaturevlaggen.
• Het biedt levensduurbeheer voor functievlagken.
  • Configuratiewaarden kunnen in realtime worden gewijzigd.
  • Functievlagmen kunnen consistent zijn voor de hele aanvraag.
• Het behandelt eenvoudige tot complexe scenario's door ondersteuning te bieden voor de volgende mogelijkheden:
  • Functies in- en uitschakelen via een declaratief configuratiebestand
  • Verschillende varianten van een functie presenteren aan verschillende gebruikers
  • De status van een functie dynamisch evalueren op basis van een aanroep naar een server
• Het biedt API-extensies voor ASP.NET Core- en MVC-framework op de volgende gebieden:
  • Routering
  • Filters
  • Actie-attributen

De .NET-functiebeheerbibliotheek is open source. Zie de GitHub-opslagplaats FeatureManagement-Dotnet voor meer informatie.

Functievlaggen

Functievlagmen kunnen worden ingeschakeld of uitgeschakeld. De status van een vlag kan voorwaardelijk worden gemaakt met behulp van functiefilters.

Functiefilters

Functiefilters definiëren een scenario voor wanneer een functie moet worden ingeschakeld. Als u de status van een functie wilt evalueren, wordt de lijst met functiefilters doorkruist totdat een van de filters bepaalt dat de functie is ingeschakeld. Op dit moment wordt doorkruising door de functiefilters gestopt. Als er geen functiefilter aangeeft dat de functie moet worden ingeschakeld, wordt deze als uitgeschakeld beschouwd.

Stel dat u een microsoft Edge-browserfunctiefilter ontwerpt. Als een HTTP-aanvraag afkomstig is van Microsoft Edge, activeert uw functiefilter alle functies waaraan deze is gekoppeld.

Configuratie van functievlag

Het .NET Core-configuratiesysteem wordt gebruikt om de status van functievlagmen te bepalen. De basis van dit systeem is de IConfiguration interface. Elke provider IConfiguration voor kan worden gebruikt als de functiestatusprovider voor de functievlagbibliotheek. Dit systeem ondersteunt scenario's, variërend van hetappsettings.json-configuratiebestand tot Azure App Configuration.

Declaratie van kenmerkvlaggen

De bibliotheek voor functiebeheer ondersteunt het appsettings.json configuratiebestand als een functievlagbron omdat het een provider is voor het .NET Core-systeem IConfiguration . Functievlagmen worden gedeclareerd met behulp van de Microsoft Feature Management schema. Dit schema is taalneutraal in oorsprong en wordt ondersteund in alle Microsoft-functiebeheerbibliotheken.

De code in het volgende voorbeeld declareert functievlagmen in een JSON-bestand:

{
    "Logging": {
        "LogLevel": {
            "Default": "Warning"
        }
    },

    // Define feature flags in a JSON file.
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": false
            },
            {
                "id": "FeatureU",
                "enabled": true,
                "conditions": {}
            },
            {
                "id": "FeatureV",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {  
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                                "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

De feature_management sectie van het JSON-document wordt volgens de conventie gebruikt om instellingen voor functievlagken te laden. U moet functievlagobjecten in de feature_flags matrix in deze sectie vermelden. Deze code bevat drie functievlagken. Elk functievlagobject heeft een id en een enabled eigenschap.

• De id waarde is de naam die u gebruikt om de functievlag te identificeren en ernaar te verwijzen.
• De enabled eigenschap geeft de ingeschakelde status van de functievlag aan.

Een functie is uitgeschakeld als enabledfalse is. Als enabledtrue is, hangt de status van de functie af van de conditions eigenschap. De conditions eigenschap declareert de voorwaarden die worden gebruikt om de functie dynamisch in te schakelen.

• Als een functievlag geen eigenschap heeft conditions , is de functie ingeschakeld.
• Als een feature flag een conditions-eigenschap heeft en aan de voorwaarden wordt voldaan, is de functie ingeschakeld.
• Als een functievlag een conditions eigenschap heeft en niet aan de voorwaarden wordt voldaan, is de functie uitgeschakeld.

Functiefilters worden gedefinieerd in de client_filters matrix. In de voorgaande code heeft de feature flag een functiefilter genaamd Microsoft.TimeWindow. Dit filter is een voorbeeld van een configureerbaar functiefilter. In deze code heeft dit filter een parameters eigenschap. Deze eigenschap wordt gebruikt om het filter te configureren. In dit geval worden de begin- en eindtijden voor de functie geconfigureerd om actief te zijn.

Geavanceerd: Het dubbele punt (:) is verboden in functievlagnamen.

Vereistetype

Binnen de conditions eigenschap wordt de requirement_type eigenschap gebruikt om te bepalen of de filters Any of All logica moeten gebruiken bij het evalueren van de status van een functie. Als requirement_type dit niet is opgegeven, is Anyde standaardwaarde . De requirement_type waarden resulteren in het volgende gedrag:

• Any: Er hoeft slechts één filter een positieve evaluatie te krijgen true om de functie in te schakelen.
• All: Elk filter moet evalueren true om de functie in te schakelen.

Een requirement_type van All verandert de manier waarop de filters worden doorlopen.

• Als er geen filters worden weergegeven, wordt de functie uitgeschakeld.
• Als er filters worden weergegeven, worden deze doorgelopen totdat de voorwaarden van een filter specificeren dat de functie moet worden uitgeschakeld. Als er geen filter aangeeft dat de functie moet worden uitgeschakeld, wordt deze als ingeschakeld beschouwd.

{
    "id": "FeatureW",
    "enabled": true,
    "conditions": {
        "requirement_type": "All",
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 00:00:00 GMT"
                }
            },
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": "50"
                }
            }
        ]
    }
}

In dit voorbeeld heeft de FeatureW functievlag een requirement_type waarde van All. Als gevolg hiervan moeten al zijn filters evalueren naar true voor het inschakelen van de functie. In dit geval is de functie ingeschakeld voor 50 procent van de gebruikers tijdens het opgegeven tijdvenster.

Meerdere configuratiebronnen verwerken

Vanaf v4.3.0 kunt u zich aanmelden voor aangepaste samenvoeging voor Microsoft-schemafunctievlagmen (de feature_management sectie). Wanneer dezelfde functievlag-id wordt weergegeven in meerdere configuratiebronnen, voegt een exemplaar van de ingebouwde ConfigurationFeatureDefinitionProvider klasse deze definities samen op basis van de registratievolgorde van de configuratieprovider. Als er een conflict is, wordt de laatste definitie van de functievlag gebruikt. Dit gedrag verschilt van het standaard samenvoegen op basis van matrixindexen in .NET.

Met de volgende code kunt u configuratie van aangepaste functievlagmen samenvoegen via afhankelijkheidsinjectie:

IConfiguration configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddJsonFile("appsettings.prod.json")
    .Build();

services.AddSingleton(configuration);
services.AddFeatureManagement();
services.Configure<ConfigurationFeatureDefinitionProviderOptions>(o =>
{
        o.CustomConfigurationMergingEnabled = true;
});

U kunt ook aangepaste samenvoegopties inschakelen wanneer u een instantie van ConfigurationFeatureDefinitionProvider maakt.

var featureManager = new FeatureManager(
    new ConfigurationFeatureDefinitionProvider(
            configuration,
            new ConfigurationFeatureDefinitionProviderOptions
            {
                    CustomConfigurationMergingEnabled = true
            }));

Voorbeeldgedrag:

// appsettings.json
{
    "feature_management": {
        "feature_flags": [
            { "id": "FeatureA", "enabled": true },
            { "id": "FeatureB", "enabled": false }
        ]
    }
}

// appsettings.prod.json (added later in ConfigurationBuilder)
{
    "feature_management": {
        "feature_flags": [
            { "id": "FeatureB", "enabled": true }
        ]
    }
}

Wanneer u aangepast samenvoegen inschakelt, FeatureA blijft dit ingeschakeld en FeatureB wordt omgezet in ingeschakeld, omdat de laatste declaratie wordt gebruikt. Wanneer u standaard .NET-samenvoeging gebruikt, waarbij aangepaste samenvoeging is uitgeschakeld, worden matrices samengevoegd per index. Deze benadering kan onverwachte resultaten opleveren als bronnen niet op positie worden uitgelijnd.

.NET-schema voor functiebeheer

In eerdere versies van de functiebeheerbibliotheek was het primaire schema het .NET-schema voor functiebeheer.

Vanaf versie 4.0.0 van de bibliotheek worden nieuwe functies, waaronder varianten en telemetrie, niet ondersteund in het .NET-functiebeheerschema.

Verbruik

In een eenvoudige implementatie controleert functiebeheer of een functievlag is ingeschakeld. Vervolgens worden acties uitgevoerd op basis van het resultaat. Deze controle wordt uitgevoerd via de IsEnabledAsync methode van IVariantFeatureManager.

…
IVariantFeatureManager featureManager;
…
if (await featureManager.IsEnabledAsync("FeatureX"))
{
    // Do something.
}

Serviceregistratie

Functiebeheer is afhankelijk van afhankelijkheidsinjectie van .NET Core. Zoals in de volgende code wordt weergegeven, kunt u standaardconventies gebruiken om functiebeheerservices te registreren:

using Microsoft.FeatureManagement;

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

De functiebeheerder haalt standaard de configuratie van de functievlag op uit de feature_management sectie of FeatureManagement sectie van de .NET Core-configuratiegegevens. Als geen van beide secties bestaat, wordt de configuratie als leeg beschouwd.

services.AddFeatureManagement(configuration.GetSection("MyFeatureFlags"));

Afhankelijkheidsinjectie

Wanneer u de bibliotheek voor functiebeheer met MVC gebruikt, kunt u het object verkrijgen dat wordt geïmplementeerd IVariantFeatureManager met behulp van afhankelijkheidsinjectie.

public class HomeController : Controller
{
    private readonly IVariantFeatureManager _featureManager;
    
    public HomeController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

Diensten voor beheer van gefaseerde functies

Met de AddFeatureManagement methode worden functiesbeheerservices toegevoegd als singletons binnen een toepassing. Voor sommige scenario's moeten functiesbeheerservices worden toegevoegd als scoped services. U kunt bijvoorbeeld functiefilters gebruiken die scoped services gebruiken voor contextinformatie. In dit geval moet u de AddScopedFeatureManagement methode gebruiken. Deze methode zorgt ervoor dat functiebeheerservices, inclusief functiefilters, worden toegevoegd als scoped services.

services.AddScopedFeatureManagement();

ASP.NET Core-integratie

De bibliotheek voor functiebeheer biedt functionaliteit in ASP.NET Core en MVC om algemene functievlagscenario's in webtoepassingen mogelijk te maken. Deze mogelijkheden zijn beschikbaar door te verwijzen naar het NuGet-pakket Microsoft.FeatureManagement.AspNetCore .

Controllers en acties

Een MVC-controller en -acties kunnen vereisen dat een bepaalde functie, of een van een lijst met functies, is ingeschakeld om uit te voeren. U kunt aan deze vereiste voldoen met behulp van een FeatureGateAttribute object. De FeatureGateAttribute klasse wordt gedefinieerd in de Microsoft.FeatureManagement.Mvc naamruimte.

[FeatureGate("FeatureX")]
public class HomeController : Controller
{
    …
}

In het voorgaande voorbeeld wordt de HomeController klasse gecontroleerd door FeatureX. HomeController acties kunnen alleen worden uitgevoerd als de FeatureX functie is ingeschakeld.

[FeatureGate("FeatureX")]
public IActionResult Index()
{
    return View();
}

In het voorgaande voorbeeld kan de Index MVC-actie alleen worden uitgevoerd als de FeatureX functie is ingeschakeld.

Afhandeling van uitgeschakelde acties

Wanneer een MVC-controller of -actie wordt geblokkeerd omdat geen van de functies die worden opgegeven is ingeschakeld, wordt een geregistreerde implementatie van IDisabledFeaturesHandler aangeroepen. Standaard wordt een minimalistische handler geregistreerd die een HTTP 404-fout retourneert. U kunt deze handler overschrijven door IFeatureManagementBuilder te gebruiken bij het registreren van functievlaggen.

public interface IDisabledFeaturesHandler
{
    Task HandleDisabledFeatures(IEnumerable<string> features, ActionExecutingContext context);
}

Weergave

In MVC-weergaven kunt u tags gebruiken <feature> om inhoud voorwaardelijk weer te geven. U kunt de renderingvoorwaarden baseren op of een functie is ingeschakeld of of een specifieke variant van een functie is toegewezen. Zie Varianten verderop in dit artikel voor meer informatie.

<feature name="FeatureX">
  <p>This content appears only when 'FeatureX' is enabled.</p>
</feature>

<feature name="FeatureX" variant="Alpha">
  <p>This content appears only when variant 'Alpha' of 'FeatureX' is assigned.</p>
</feature>

U kunt ook de evaluatie van de taghelper uitschakelen als u inhoud wilt weergeven wanneer een functie of set functies is uitgeschakeld. Als u negate="true" opgeeft, zoals in de volgende voorbeelden, wordt de inhoud alleen weergegeven wanneer FeatureX uitgeschakeld is.

<feature negate="true" name="FeatureX">
  <p>This content appears only when 'FeatureX' is disabled.</p>
</feature>

<feature negate="true" name="FeatureX" variant="Alpha">
  <p>This content appears only when variant 'Alpha' of 'FeatureX' isn't assigned.</p>
</feature>

U kunt de <feature> tag gebruiken om te verwijzen naar meerdere functies. Hiertoe geeft u een door komma's gescheiden lijst met functies in het name kenmerk op.

<feature name="FeatureX,FeatureY">
  <p>This content appears only when 'FeatureX' and 'FeatureY' are enabled.</p>
</feature>

Standaard moeten alle vermelde functies zijn ingeschakeld om de functietag weer te geven. U kunt dit gedrag overschrijven door het requirement kenmerk toe te voegen, zoals in het volgende voorbeeld wordt weergegeven.

<feature name="FeatureX,FeatureY" requirement="Any">
  <p>This content appears only when 'FeatureX,' 'FeatureY,' or both are enabled.</p>
</feature>

U kunt de <feature> tag ook gebruiken om te verwijzen naar meerdere varianten. Hiervoor gebruikt u een requirement waarde van Any en geeft u een door komma's gescheiden lijst met varianten in het variant kenmerk op.

<feature name="FeatureX" variant="Alpha,Beta" requirement="Any">
  <p>This content appears only when variant 'Alpha' or 'Beta' of 'FeatureX' is assigned.</p>
</feature>

Voor de <feature> tag is een taghulp vereist. Als u de tag wilt gebruiken, voegt u de taghelper voor functiebeheer toe aan het bestand _ViewImports.cshtml .

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC-filters

U kunt MVC-actiefilters instellen die u voorwaardelijk toepast op basis van de status van een functie. Als u deze filters wilt instellen, registreert u deze op een functiebewuste manier. De functiebeheerpijplijn ondersteunt asynchrone MVC-actiefilters waarmee de IAsyncActionFilter interface wordt geïmplementeerd.

services.AddMvc(o => 
{
    o.Filters.AddForFeature<SomeMvcFilter>("FeatureX");
});

De voorgaande code registreert een MVC-filter met de naam SomeMvcFilter. Dit filter wordt alleen geactiveerd in de MVC-pijplijn als FeatureX is ingeschakeld.

Razor-pagina's

MVC Razor-pagina's kunnen vereisen dat een bepaalde functie, of een van een lijst met functies, is ingeschakeld om uit te voeren. U kunt deze vereiste toevoegen met behulp van een FeatureGateAttribute object. De FeatureGateAttribute klasse wordt gedefinieerd in de Microsoft.FeatureManagement.Mvc naamruimte.

[FeatureGate("FeatureX")]
public class IndexModel : PageModel
{
    public void OnGet()
    {
    }
}

Met de voorgaande code wordt een Razor-pagina ingesteld waarvoor FeatureX is ingeschakeld. Als de functie niet is ingeschakeld, genereert de pagina een HTTP 404-resultaat (NotFound).

Wanneer u een FeatureGateAttribute object op Razor-pagina's gebruikt, moet u FeatureGateAttribute op het paginahandler-type plaatsen. U kunt deze niet op afzonderlijke handlermethoden plaatsen.

Toepassingsgebouw

U kunt de bibliotheek voor functiebeheer gebruiken om toepassingsbranches en middleware toe te voegen die voorwaardelijk worden uitgevoerd op basis van de status van een functie.

app.UseMiddlewareForFeature<ThirdPartyMiddleware>("FeatureX");

In de voorgaande code voegt de toepassing een middlewareonderdeel toe dat alleen in de aanvraagpijplijn wordt weergegeven als de FeatureX functie is ingeschakeld. Als de functie tijdens runtime is ingeschakeld of uitgeschakeld, kan de middleware-pijplijn dynamisch worden gewijzigd.

Zoals in de volgende code wordt weergegeven, bouwt deze functionaliteit voort op de meer algemene mogelijkheid om de hele toepassing te vertakken op basis van een functie.

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

Een functiefilter implementeren

Het maken van een functiefilter biedt een manier om functies in te schakelen op basis van criteria die u definieert. Als u een functiefilter wilt implementeren, moet u de IFeatureFilter interface implementeren. IFeatureFilter heeft één methode met de naam EvaluateAsync. Wanneer een functie aangeeft dat deze kan worden ingeschakeld voor een functiefilter, wordt de EvaluateAsync methode aangeroepen. Als EvaluateAsynctrue teruggeeft, moet de functie zijn ingeschakeld.

De volgende code laat zien hoe u een aangepast functiefilter toevoegt met de naam MyCriteriaFilter.

services.AddFeatureManagement()
        .AddFeatureFilter<MyCriteriaFilter>();

U kunt een kenmerkfilter registreren door AddFeatureFilter<T> aan te roepen op de IFeatureManagementBuilder-implementatie die AddFeatureManagement retourneert. Het functiefilter heeft toegang tot de services in de serviceverzameling die u gebruikt om functievlagmen toe te voegen. U kunt afhankelijkheidsinjectie gebruiken om deze services op te halen.

Geparameteriseerde functiefilters

Voor sommige functiefilters zijn parameters vereist om te evalueren of een functie moet worden ingeschakeld. Een browserfunctiefilter kan bijvoorbeeld een functie inschakelen voor een bepaalde set browsers. Mogelijk wilt u een functie inschakelen in de browsers Microsoft Edge en Chrome, maar niet in Firefox.

Als u dit filter wilt implementeren, kunt u een functiefilter ontwerpen om parameters te verwachten. U geeft deze parameters op in de functieconfiguratie. In code opent u deze via de FeatureFilterEvaluationContext parameter van IFeatureFilter.EvaluateAsync.

public class FeatureFilterEvaluationContext
{
    /// <summary>
    /// The name of the feature being evaluated
    /// </summary>
    public string FeatureName { get; set; }

    /// <summary>
    /// The settings provided for the feature filter to use when evaluating whether the feature should be enabled
    /// </summary>
    public IConfiguration Parameters { get; set; }
}

De FeatureFilterEvaluationContext klasse heeft een eigenschap met de naam Parameters. De parameters van deze eigenschap vertegenwoordigen een onbewerkte configuratie die het functiefilter kan gebruiken bij het evalueren of de functie moet worden ingeschakeld. In het voorbeeld van het filter voor browserfuncties kan het filter de Parameters eigenschap gebruiken om een set toegestane browsers te extraheren die zijn opgegeven voor de functie. Het filter kan vervolgens controleren of de aanvraag afkomstig is van een van deze browsers.

[FilterAlias("Browser")]
public class BrowserFilter : IFeatureFilter
{
    …

    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        BrowserFilterSettings settings = context.Parameters.Get<BrowserFilterSettings>() ?? new BrowserFilterSettings();

        //
        // Use the settings to check whether the request is from a browser in BrowserFilterSettings.AllowedBrowsers.
    }
}

Filter-aliaskenmerk

Wanneer u een functiefilter registreert voor een functievlag, is de alias die u in de configuratie gebruikt, de naam van het functiefiltertype met het Filter achtervoegsel, indien aanwezig, verwijderd. U moet bijvoorbeeld naar MyCriteriaFilter verwijzen als MyCriteria in configuratie.

{
    "id": "MyFeature",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "MyCriteria"
            }
        ]
    }
}

U kunt deze naam overschrijven met behulp van de FilterAliasAttribute klasse. Als u een naam wilt declareren die moet worden gebruikt in de configuratie om te verwijzen naar een functiefilter binnen een functievlag, kunt u het functiefilter voorzien van dit kenmerk.

Ontbrekende functiefilters

Stel dat u een functie configureert die moet worden ingeschakeld voor een specifiek functiefilter. Als dat functiefilter niet is geregistreerd, wordt er een uitzondering gegenereerd wanneer de functie wordt geëvalueerd. Zoals in de volgende code wordt weergegeven, kunt u de uitzondering uitschakelen met behulp van opties voor functiebeheer.

services.Configure<FeatureManagementOptions>(options =>
{
    options.IgnoreMissingFeatureFilters = true;
});

HttpContext gebruiken

Functiefilters kunnen evalueren of een functie moet worden ingeschakeld op basis van de eigenschappen van een HTTP-aanvraag. Deze controle wordt uitgevoerd door de HTTP-context te inspecteren. Zoals in de volgende code wordt weergegeven, kan een functiefilter een verwijzing naar de HTTP-context krijgen met behulp van afhankelijkheidsinjectie om een implementatie van IHttpContextAccessorte verkrijgen.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public BrowserFilter(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor));
    }
}

U moet de IHttpContextAccessor implementatie toevoegen aan de container voor afhankelijkheidsinjectie bij het opstarten, zodat deze beschikbaar is. U kunt de volgende methode gebruiken om de implementatie in de IServiceCollection services te registreren.

public void ConfigureServices(IServiceCollection services)
{
    …
    services.AddHttpContextAccessor();
    …
}

Geavanceerd:IHttpContextAccessor en HttpContext mag niet worden gebruikt in de Razor-onderdelen van Blazor-apps aan de serverzijde. De aanbevolen methode voor het doorgeven van HTTP-context in Blazor-apps is het kopiëren van de gegevens naar een scoped service. Voor Blazor-apps moet u AddScopedFeatureManagement gebruiken om functiebeheerservices te registreren. Zie Scoped functiebeheerservices voor meer informatie, eerder in dit artikel.

Een context opgeven voor functie-evaluatie

In consoletoepassingen is er geen omgevingscontext zoals HttpContext die functiefilters kunnen gebruiken om te controleren of een functie moet worden ingeschakeld. In dit geval moeten toepassingen een object opgeven dat een context vertegenwoordigt voor het functiebeheersysteem voor gebruik door functiefilters. U kunt IVariantFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext) gebruiken om deze context te bieden. Als u de status van een functie wilt evalueren, kunnen functiefilters het appContext object gebruiken dat u aan de functiebeheerder opgeeft.

MyAppContext context = new MyAppContext
{
    AccountId = current.Id
};

if (await featureManager.IsEnabledAsync(feature, context))
{
…
}

Contextuele kenmerkfilters

Contextuele functiefilters implementeren de IContextualFeatureFilter<TContext> interface. Deze speciale functiefilters kunnen profiteren van de context die wordt doorgegeven wanneer IVariantFeatureManager.IsEnabledAsync<TContext> wordt aangeroepen. De TContext typeparameter in IContextualFeatureFilter<TContext> beschrijft het contexttype dat het filter kan verwerken. Wanneer u een contextueel functiefilter ontwikkelt, kunt u de vereisten voor het gebruik van het filter vaststellen door een contexttype op te geven.

Omdat elk type een afstammeling is van de Object-klasse, kan een filter dat IContextualFeatureFilter<object> implementeert, worden aangeroepen voor elke opgegeven context. De volgende code bevat een voorbeeld van een specifiek contextueel functiefilter. In deze code is een functie ingeschakeld als een account zich in een geconfigureerde lijst met ingeschakelde accounts bevindt.

public interface IAccountContext
{
    string AccountId { get; set; }
}

[FilterAlias("AccountId")]
class AccountIdFilter : IContextualFeatureFilter<IAccountContext>
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext featureEvaluationContext, IAccountContext accountId)
    {
        //
        // Evaluate whether the feature should be on by using the IAccountContext that's provided.
    }
}

Voor de AccountIdFilter klasse is een object vereist dat IAccountContext implementeert om de status van een functionaliteit te kunnen evalueren. Wanneer u dit functiefilter gebruikt, moet de aanroeper ervoor zorgen dat het doorgegeven object IAccountContext implementeert.

Contextuele en niet-contextuele filters gebruiken met dezelfde alias

Filters die IFeatureFilter en IContextualFeatureFilter implementeren, kunnen dezelfde alias delen. U kunt met name één filteralias delen met nul of één IFeatureFilter implementatie en met nul tot NIContextualFeatureFilter<ContextType> implementaties als er hoogstens één toepasselijk filter voor ContextType is.

Bekijk het volgende voorbeeld om inzicht te krijgen in het proces van het selecteren van een filter wanneer contextuele en niet-contextuele filters van dezelfde naam zijn geregistreerd in een toepassing.

Drie filters delen de SharedFilterName alias:

• Een niet-contextueel filter met de naam FilterA
• Een contextueel filter dat een TypeB context accepteert, FilterB.
• Een contextueel filter met de naam FilterC dat een TypeC context accepteert

Een functievlag genaamd MyFeature maakt gebruik van het functiefilter in de SharedFilterName-configuratie.

Als alle drie de filters zijn geregistreerd:

• Wanneer u aanroept IsEnabledAsync("MyFeature"), wordt het FilterA filter gebruikt om de functievlag te evalueren.
• Wanneer u belt IsEnabledAsync("MyFeature", context):
  • Als het type context is TypeB, FilterB wordt gebruikt.
  • Als het type context is TypeC, FilterC wordt gebruikt.
  • Als het type context is TypeF, FilterA wordt gebruikt.

Ingebouwde functiefilters

Er zijn enkele functiefilters die bij het Microsoft.FeatureManagement pakket worden geleverd: PercentageFilter, TimeWindowFilter, ContextualTargetingFilteren TargetingFilter. Alle filters behalve TargetingFilter worden automatisch toegevoegd wanneer u de AddFeatureManagement methode gebruikt om functiebeheer te registreren. TargetingFilter wordt toegevoegd met behulp van de WithTargeting methode. Zie Targeting verderop in dit artikel voor meer informatie.

Elk van de ingebouwde functiefilters heeft zijn eigen parameters. In de volgende secties worden deze functiefilters beschreven en worden voorbeelden weergegeven.

Microsoft.Percentage

Het Microsoft.Percentage filter biedt een manier om een functie in te schakelen op basis van een ingesteld percentage.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": 50
                }
            }
        ]
    }
}

Microsoft.TimeWindow

Het Microsoft.TimeWindow filter biedt een manier om een functie in te schakelen op basis van een tijdvenster.

• Als u alleen een End waarde invoert, wordt de functie tot die tijd ingeschakeld.
• Als u slechts een Start waarde opgeeft, wordt de functie op alle punten na die tijd ingeschakeld.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                }
            }
        ]
    }
}

U kunt het filter configureren om een tijdvenster op terugkerende basis toe te passen. Deze mogelijkheid kan handig zijn wanneer u een functie moet inschakelen tijdens een periode met weinig verkeer of een hoog verkeer van een dag of bepaalde dagen van een week. Als u een afzonderlijk tijdvenster wilt uitbreiden naar een terugkerend tijdvenster, gebruikt u een Recurrence parameter om een terugkeerregel op te geven.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
                    "End": "Sat, 23 Mar 2024 02:00:00 GMT",
                    "Recurrence": {
                        "Pattern": {
                            "Type": "Daily",
                            "Interval": 1
                        },
                        "Range": {
                            "Type": "NoEnd"
                        }
                    }
                }
            }
        ]
    }
}

De Recurrence instellingen bestaan uit twee delen:

• De Pattern instellingen geven aan hoe vaak het tijdvenster wordt herhaald.
• De Range instellingen geven op hoe lang het terugkeerpatroon wordt herhaald.

Terugkeerpatroon

Er zijn twee mogelijke terugkeerpatroontypen: Daily en Weekly. Een tijdvenster kan bijvoorbeeld elke dag, om de drie dagen, elke maandag of om de andere vrijdag worden herhaald.

Afhankelijk van het type zijn bepaalde velden van de Pattern instellingen vereist, optioneel of genegeerd.

• Daily

  Het dagelijkse terugkeerpatroon zorgt ervoor dat het tijdvenster wordt herhaald op basis van een opgegeven aantal dagen tussen elke gebeurtenis.

  Eigenschappen	Relevantie	Beschrijving
  Type	Vereist	Het type herhalingspatroon. Moet worden ingesteld op Daily.
  Interval	Optioneel	Het aantal dagen tussen elke gebeurtenis. De standaardwaarde is 1.

• Weekly

  Het wekelijkse terugkeerpatroon zorgt ervoor dat het tijdvenster op dezelfde dag of dagen van de week wordt herhaald. U kunt echter het aantal weken opgeven tussen elke set voorkomens.

  Eigenschappen	Relevantie	Beschrijving
  Type	Vereist	Het terugkeerpatroontype. Moet worden ingesteld op Weekly.
  DaysOfWeek	Vereist	De dagen van de week waarop de gebeurtenis plaatsvindt.
  Interval	Optioneel	Het aantal weken tussen elke reeks voorkomens. De standaardwaarde is 1.
  FirstDayOfWeek	Optioneel	De dag die moet worden gebruikt als de eerste dag van de week. De standaardwaarde is Sunday.

  In het volgende voorbeeld wordt het tijdvenster elke maandag en dinsdag herhaald:

  "Pattern": {
      "Type": "Weekly",
      "Interval": 2,
      "DaysOfWeek": ["Monday", "Tuesday"]
  }
  

Terugkeerpatroon

Er zijn drie mogelijke terugkeerbereiktypen: NoEnd, EndDateen Numbered.

• NoEnd

  Het NoEnd bereik zorgt ervoor dat het terugkeerpatroon voor onbepaalde tijd plaatsvindt.

  Eigenschappen	Relevantie	Beschrijving
  Type	Vereist	Het type terugkeerbereik. Moet worden ingesteld op NoEnd.

• EndDate

  Het EndDate bereik zorgt ervoor dat het tijdvenster plaatsvindt op alle dagen die passen bij het toepasselijke patroon tot de einddatum.

  Eigenschappen	Relevantie	Beschrijving
  Type	Vereist	Het type terugkeerbereik. Moet worden ingesteld op EndDate.
  EndDate	Vereist	De datum en tijd waarop het patroon niet meer wordt toegepast. Als de begintijd van de laatste gebeurtenis vóór de einddatum valt, kan de eindtijd van die gebeurtenis verder gaan.

  In het volgende voorbeeld wordt het tijdvenster elke dag herhaald tot de laatste keer op 1 april 2024.

  "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
  "End": "Fri, 22 Mar 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Daily",
          "Interval": 1
      },
      "Range": {
          "Type": "EndDate",
          "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
      }
  }
  

• Numbered

  Het Numbered bereik zorgt ervoor dat het tijdvenster een opgegeven aantal keren plaatsvindt.

  Eigenschappen	Relevantie	Beschrijving
  Type	Vereist	Het type terugkeerbereik. Moet worden ingesteld op Numbered.
  NumberOfOccurrences	Vereist	Het aantal voorkomens.

  In het volgende voorbeeld wordt het tijdvenster op maandag en dinsdag herhaald voor een totaal van drie voorkomens, die plaatsvinden op de volgende data:

  • Maandag 1 april
  • dinsdag 2 april
  • maandag 8 april

  "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
  "End": "Mon, 1 Apr 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Weekly",
          "Interval": 1,
          "DaysOfWeek": ["Monday", "Tuesday"]
      },
      "Range": {
          "Type": "Numbered",
          "NumberOfOccurrences": 3
      }
  }
  

Om een herhalingsregel te maken, moet u zowel de Pattern- als de Range-instellingen opgeven. Elk patroontype kan werken met elk bereiktype.

Geavanceerd: De tijdzone-offset van de Start eigenschap wordt toegepast op de terugkeerpatrooninstellingen.

Microsoft.Targeting

Het Microsoft.Targeting filter biedt een manier om een functie in te schakelen voor een doelgroep. Zie Targeting verderop in dit artikel voor een uitgebreide uitleg van targeting.

De filterparameters bevatten een Audience object dat beschrijft wie toegang heeft tot de functie. Binnen het Audience object kunt u gebruikers, groepen, uitgesloten gebruikers en groepen en een standaardpercentage van de gebruikersbasis opgeven.

Voor elk groepsobject dat u in de Groups sectie opgeeft, moet u ook opgeven welk percentage van de leden van de groep toegang moet hebben.

Voor elke gebruiker wordt de functie op de volgende manier geëvalueerd:

• Als de gebruiker is uitgesloten, is de functie uitgeschakeld voor de gebruiker. U kunt de gebruiker uitsluiten door:

  • Geef hun naam weer onder Users in de Exclusion sectie.
  • Geef een groep op waartoe Groups ze behoren in de Exclusion sectie.

• Als de gebruiker niet is uitgesloten, wordt de functie ingeschakeld als aan een van de volgende voorwaarden wordt voldaan:

  • De gebruiker wordt vermeld in de Users sectie.
  • De gebruiker bevindt zich in het opgenomen percentage van een van de groeps-implementaties.
  • De gebruiker valt in het standaardpercentage voor uitrol.

• Als geen van de vorige gevallen van toepassing is, wordt de functie uitgeschakeld voor de gebruiker. Als de gebruiker zich bijvoorbeeld niet in een opgenomen percentage bevindt, is de functie uitgeschakeld.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.Targeting",
                "parameters": {
                    "Audience": {
                        "Users": [
                            "Jeff",
                            "Alicia"
                        ],
                        "Groups": [
                            {
                                "Name": "Ring0",
                                "RolloutPercentage": 100
                            },
                            {
                                "Name": "Ring1",
                                "RolloutPercentage": 50
                            }
                        ],
                        "DefaultRolloutPercentage": 20,
                        "Exclusion": {
                            "Users": [
                                "Ross"
                            ],
                            "Groups": [
                                "Ring2"
                            ]
                        }
                    }
                }
            }
        ]
    }
}

Naamruimten van functiefilteralias

Alle ingebouwde functiefilteraliassen bevinden zich in de Microsoft functiefilternaamruimte. Als u zich in deze naamruimte bevindt, voorkomt u conflicten met andere functiefilters die dezelfde alias delen. De segmenten van een functiefilternaamruimte worden gesplitst door het . teken. U kunt verwijzen naar een functiefilter op basis van de volledig gekwalificeerde alias, zoals Microsoft.Percentage. U kunt ook verwijzen naar het laatste segment, zoals Percentage.

Targeten

Targeting is een strategie voor functionaliteitenbeheer die u kunt gebruiken om nieuwe functies geleidelijk uit te rollen onder uw gebruikers. De strategie is gebaseerd op het concept van het richten van een set gebruikers die bekend staan als de doelgroep. Een doelgroep bestaat uit specifieke gebruikers, groepen, uitgesloten gebruikers en groepen en een aangewezen percentage van de gehele gebruikersbasis. De groepen die in de doelgroep zijn opgenomen, kunnen verder worden onderverdeeld in percentages van hun totale leden.

In de volgende stappen ziet u een voorbeeld van een progressieve implementatie voor een nieuwe functie met de naam Bèta:

1. Individuele gebruikers Jeff en Alicia krijgen toegang tot de bètafunctie.
2. Een andere gebruiker, Mark, vraagt zich aan te kiezen en is inbegrepen.
3. Twintig procent van de gebruikers in de Ring1-groep zijn opgenomen in de bètafunctie.
4. Het aantal opgenomen Ring1-gebruikers wordt tot 100 procent opgestoten.
5. Vijf procent van de gebruikersbasis is opgenomen in de bètafunctie.
6. Het implementatiepercentage wordt maximaal 100 procent opgestoten om de functie volledig uit te rollen.

De bibliotheek ondersteunt deze strategie voor het implementeren van een functie via het ingebouwde Microsoft.Targeting-functiefilter .

Doelgerichtheid in een webtoepassing

Zie het voorbeeldproject FeatureFlagDemo voor een voorbeeld van een webtoepassing die gebruikmaakt van het doelfunctiefilter.

Om TargetingFilter in een toepassing te gebruiken, moet u deze toevoegen aan de serviceverzameling van de toepassing, zoals u dat ook met elk ander functiefilter doet. In tegenstelling tot andere ingebouwde filters is TargetingFilter het afhankelijk van een andere service die moet worden toegevoegd aan de serviceverzameling van de toepassing. De service is een ITargetingContextAccessor implementatie.

De Microsoft.FeatureManagement.AspNetCore bibliotheek biedt een standaard implementatie van ITargetingContextAccessor die doelgegevens ophaalt uit de waarde van HttpContext een aanvraag. U kunt de standaard targetcontexttoegang gebruiken wanneer u targeting instelt met behulp van de niet-generieke WithTargeting overload in IFeatureManagementBuilder.

Om de standaard contexttoegangsmiddel en TargetingFilter te registreren, roep je WithTargeting op aan IFeatureManagementBuilder.

services.AddFeatureManagement()
        .WithTargeting();

U kunt ook een aangepaste implementatie registreren voor ITargetingContextAccessor en TargetingFilter door aan te roepen WithTargeting<T>. Met de volgende code stel je functiebeheer in een webtoepassing in om TargetingFilter te gebruiken met een implementatie van ITargetingContextAccessor genaamd ExampleTargetingContextAccessor.

services.AddFeatureManagement()
        .WithTargeting<ExampleTargetingContextAccessor>();

ITargetingContextAccessor

Voor het gebruik van TargetingFilter in een webtoepassing is een implementatie van ITargetingContextAccessor vereist. De redenering achter deze vereiste is dat contextuele informatie, zoals informatie over de gebruiker, nodig is voor het instellen van evaluaties. Deze informatie wordt opgeslagen in exemplaren van de TargetingContext klasse. Verschillende toepassingen halen deze informatie uit verschillende plaatsen, zoals de HTTP-context van een aanvraag of een database.

Zie DefaultHttpTargetingContextAccessor in het Microsoft.FeatureManagement.AspNetCore-pakket voor een voorbeeld dat doelcontextinformatie uit de HTTP-context van een toepassing extraheert. De volgende informatie wordt geëxtraheerd:

• Doelgegevens van de HttpContext.User eigenschap
• UserId informatie uit het Identity.Name veld
• Groups informatie van vorderingen van het type Role

Deze implementatie is afhankelijk van het gebruik van IHttpContextAccessor. Zie IHttpContextAccessor gebruiken, eerder in dit artikel voor meer informatie.

Doelgerichtheid in een consoletoepassing

Het doelfilter is afhankelijk van een doelcontext om te evalueren of een functie moet worden ingeschakeld. Deze doelcontext bevat informatie zoals de gebruiker die wordt geëvalueerd en de groepen waartoe de gebruiker behoort. In consoletoepassingen is er doorgaans geen omgevingscontext beschikbaar voor het doorgeven van deze informatie aan het doelfilter. Als gevolg hiervan moet u deze rechtstreeks doorgeven wanneer u belt FeatureManager.IsEnabledAsync. Dit type context wordt ondersteund met behulp van ContextualTargetingFilter. Toepassingen die de doelcontext naar de functiebeheerder moeten verzenden, moeten worden gebruikt ContextualTargetingFilter in plaats van TargetingFilter.

Omdat ContextualTargetingFilterIContextualTargetingFilter<ITargetingContext> implementeert, moet u een implementatie van ITargetingContext doorgeven aan IVariantFeatureManager.IsEnabledAsync om een functie te kunnen evalueren en activeren.

IVariantFeatureManager fm;
…
// The userId and groups variables are defined earlier in the application.
TargetingContext targetingContext = new TargetingContext
{
   UserId = userId,
   Groups = groups
};

await fm.IsEnabledAsync(featureName, targetingContext);

ContextualTargetingFilter maakt gebruik van de functiefilteralias Microsoft.Targeting, dus de configuratie voor dit filter is consistent met de informatie in Microsoft.Targeting, eerder in dit artikel.

Zie het voorbeeldproject ContextualTargetingFilter voor een voorbeeld dat in een consoletoepassing wordt gebruikt.

Evaluatieopties richten

Er zijn opties beschikbaar om aan te passen hoe doelevaluatie wordt uitgevoerd voor alle functies. U kunt deze opties configureren wanneer u functiebeheer instelt.

services.Configure<TargetingEvaluationOptions>(options =>
{
    options.IgnoreCase = true;
});

Doelgerichte uitsluiting

Wanneer u een doelgroep definieert, kunt u gebruikers en groepen uitsluiten van de doelgroep. Deze functionaliteit is handig wanneer u een functie uitrolt voor een groep gebruikers, maar u moet enkele gebruikers of groepen uitsluiten van de implementatie. Als u gebruikers en groepen wilt opgeven die moeten worden uitgesloten, gebruikt u de Exclusion eigenschap van een doelgroep.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

Met de voorgaande code wordt een functie ingeschakeld voor gebruikers met de naam Jeff en Alicia. De functie is ook ingeschakeld voor gebruikers in de groep met de naam Ring0. De functie is echter uitgeschakeld voor de gebruiker met de naam Mark, zelfs als die gebruiker zich in de Ring0 groep bevindt. Uitsluitingen hebben voorrang op de rest van het doelfilter.

Varianten

Soms heeft de functie meerdere voorgestelde ontwerpopties wanneer u een nieuwe functie aan een toepassing toevoegt. A/B-tests bieden een algemene oplossing voor het bepalen van een ontwerp. A/B-testen omvat het verstrekken van een andere versie van de functie aan verschillende segmenten van de gebruikersbasis en vervolgens het kiezen van een versie op basis van gebruikersinteractie. In de .NET-functiebeheerbibliotheek kunt u A/B-tests implementeren met behulp van varianten om verschillende configuraties van een functie weer te geven.

Varianten bieden een manier om een functievlag meer te laten worden dan een eenvoudige aan/uit-vlag. Een variant vertegenwoordigt een waarde van een functievlag die een tekenreeks, een getal, een Booleaanse waarde of zelfs een configuratieobject kan zijn. Een functievlag die varianten declareert, moet de omstandigheden definiëren waaronder elke variant moet worden gebruikt. Zie Varianten toewijzen verderop in dit artikel voor meer informatie.

public class Variant
{
    /// <summary>
    /// The name of the variant
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// The configuration of the variant
    /// </summary>
    public IConfigurationSection Configuration { get; set; }
}

Varianten ophalen

Voor elke functie kunt u een variant ophalen met behulp van de GetVariantAsync methode van de IVariantFeatureManager interface.

…
IVariantFeatureManager featureManager;
…
Variant variant = await featureManager.GetVariantAsync("MyVariantFeatureFlag", CancellationToken.None);

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration.

Nadat u een variant hebt opgehaald, kunt u de configuratie daarvan rechtstreeks gebruiken als een implementatie van IConfigurationSection vanuit de eigenschap Configuration van de variant. Een andere optie is om de configuratie aan een object te binden met behulp van het bindingspatroon voor .NET-configuratie.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

De geretourneerde variant is afhankelijk van de gebruiker die wordt geëvalueerd. U kunt informatie over de gebruiker verkrijgen van een exemplaar van TargetingContext. U kunt deze context doorgeven wanneer u GetVariantAsync aanroept. Of deze kan automatisch worden opgehaald uit een implementatie van ITargetingContextAccessor als deze is geregistreerd.

Declaratie van variantfunctievlag

In vergelijking met standaardfunctievlagmen hebben variantfunctievlagmen twee extra eigenschappen: variants en allocation. De variants eigenschap is een matrix die de varianten bevat die zijn gedefinieerd voor de functie. De allocation eigenschap definieert hoe deze varianten moeten worden toegewezen voor de functie. Net als bij het declareren van standaardfunctievlagmen kunt u variantfunctievlagmen instellen in een JSON-bestand. De volgende code is een voorbeeld van een variantfunctievlag:

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

Varianten definiëren

Elke variant heeft twee eigenschappen: een naam en een configuratie. De naam wordt gebruikt om te verwijzen naar een specifieke variant en de configuratie is de waarde van die variant. U kunt de configuration_value eigenschap gebruiken om de configuratie op te geven. De configuration_value eigenschap is een inlineconfiguratie die een tekenreeks, getal, Booleaanse waarde of configuratieobject kan zijn. Als u de configuration_value eigenschap niet configureert, is de eigenschap van de geretourneerde variant Configurationnull.

Als u alle mogelijke varianten voor een functie wilt opgeven, geeft u deze weer onder de variants eigenschap.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

Varianten toewijzen

Als u de varianten van een functie wilt toewijzen, gebruikt u de allocation eigenschap van de functie.

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

De allocation instelling heeft de volgende eigenschappen:

Als een functie niet is ingeschakeld, wijst de functiebeheerder de variant toe die is opgegeven voor default_when_disabled de huidige gebruiker. In het voorgaande voorbeeld wordt die functie aangeroepen Small.

Als de functie is ingeschakeld, controleert de functiebeheerder de user, group en percentile toewijzingen in die volgorde om een variant toe te wijzen. In het voorgaande voorbeeld wordt de opgegeven variant toegewezen Bigaan de gebruiker in de volgende gevallen:

• De gebruiker die wordt geëvalueerd, heeft de naam Marsha.
• De gebruiker bevindt zich in de Ring1 groep.
• De gebruiker valt tussen het nul- en tiende percentiel.

Als geen van deze toewijzingen overeenkomt, wordt de default_when_enabled variant toegewezen aan de gebruiker. In het voorbeeld is dat de variant Small.

Toewijzingslogica is vergelijkbaar met de logica die u gebruikt voor het functiefilter Microsoft.Targeting . Er zijn echter enkele parameters die wel aanwezig zijn in targeting maar niet in toewijzing, en omgekeerd. De resultaten van targeting en toewijzing zijn niet gerelateerd.

Ingeschakelde status overschrijven met behulp van een variant

U kunt varianten gebruiken om de ingeschakelde status van een functievlag te overschrijven. Wanneer u van deze functionaliteit profiteert, kunt u de evaluatie van een functievlag uitbreiden. Tijdens het aanroepen van IsEnabledAsync een vlag met varianten controleert de functiebeheerder of de variant die is toegewezen aan de huidige gebruiker is geconfigureerd om het resultaat te overschrijven.

U kunt overriding implementeren met behulp van de optionele variant-eigenschap status_override. Deze eigenschap kan de volgende waarden hebben:

• None: De variant heeft geen invloed op of de vlag wordt beschouwd als ingeschakeld of uitgeschakeld. None is de standaardwaarde.
• Enabled: Wanneer de variant is gekozen, wordt de functievlag geëvalueerd als ingeschakeld.
• Disabled: Wanneer de variant is gekozen, wordt de feature flag als uitgeschakeld beschouwd.

U kunt een functie niet overschrijven met een enabled status van false.

Als u een functievlag met binaire varianten gebruikt, kan de status_override eigenschap handig zijn. U kunt API's blijven gebruiken, zoals IsEnabledAsync en FeatureGateAttribute in uw toepassing. Maar u kunt ook profiteren van de functies die worden geleverd met varianten, zoals percentieltoewijzing en het gebruik van een seed-waarde voor percentageberekeningen.

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

In het voorgaande voorbeeld is de functie altijd ingeschakeld. Als de huidige gebruiker zich in het berekende percentielbereik van 10 tot 20 bevindt, wordt de On variant geretourneerd. Anders wordt de Off variant geretourneerd en omdat de status_override waarde is Disabled, wordt de functie als uitgeschakeld beschouwd.

Varianten in afhankelijkheidsinjectie

U kunt variantfunctievlagmen samen met afhankelijkheidsinjectie gebruiken om verschillende implementaties van een service beschikbaar te maken voor verschillende gebruikers. De IVariantServiceProvider<TService> interface biedt een manier om deze combinatie te bereiken.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken); 

In de voorgaande code haalt de IVariantServiceProvider<IAlgorithm>-implementatie een implementatie van IAlgorithm uit de afhankelijkheidsinjectiecontainer op. De gekozen implementatie is afhankelijk van:

• De functievlag waarmee de IAlgorithm service is geregistreerd.
• De toegewezen variant voor die functie.

De IVariantServiceProvider<T> implementatie wordt beschikbaar gesteld aan de toepassing door aan te roepen IFeatureManagementBuilder.WithVariantService<T>(string featureName), zoals in het volgende voorbeeld wordt weergegeven. De aanroep in deze code maakt IVariantServiceProvider<IAlgorithm> beschikbaar in de servicecollectie.

services.AddFeatureManagement() 
        .WithVariantService<IAlgorithm>("ForecastAlgorithm");

U moet elke implementatie IAlgorithm afzonderlijk toevoegen via een add-methode, zoals services.AddSingleton<IAlgorithm, SomeImplementation>(). De implementatie van IAlgorithm die IVariantServiceProvider gebruikt wordt, hangt af van de functievlag van de ForecastAlgorithm variant. Als er geen implementatie van IAlgorithm wordt toegevoegd aan de serviceverzameling, retourneert de IVariantServiceProvider<IAlgorithm>.GetServiceAsync() taak met een null resultaat.

{
    // The example variant feature flag
    "id": "ForecastAlgorithm",
    "enabled": true,
    "variants": [
        { 
            "Name": "AlgorithmBeta" 
        },
        ...
    ] 
}

Kenmerk variant servicealias

De variantserviceprovider gebruikt de typenamen van implementaties om overeen te komen met de toegewezen variant. Als een variantservice is ingericht met VariantServiceAliasAttribute, moet de naam die door dit kenmerk is gedeclareerd, worden gebruikt in de configuratie om naar deze variantservice te verwijzen.

[VariantServiceAlias("Beta")]
public class AlgorithmBeta : IAlgorithm
{
    ...
}

Telemetrie

Wanneer u een wijziging in een functievlag implementeert, is het vaak belangrijk om het effect ervan op een toepassing te analyseren. Hier volgen bijvoorbeeld enkele vragen die zich kunnen voordoen:

• Zijn de vlaggen ingeschakeld en uitgeschakeld zoals verwacht?
• Krijgen doelgebruikers toegang tot een bepaalde functie zoals verwacht?
• Welke variant ziet een bepaalde gebruiker?

De emissie en analyse van evaluatie-gebeurtenissen van functievlagken kunnen u helpen bij het beantwoorden van deze typen vragen. De .NET-functiebeheerbibliotheek maakt gebruik van de System.Diagnostics.Activity API om traceringstelemetrie te produceren tijdens de evaluatie van functievlagken.

Telemetrie inschakelen

Standaard worden er geen telemetriegegevens verzonden voor functievlagmen. Als u telemetrie wilt publiceren voor een bepaalde functievlag, moet de vlag aangeven dat deze is ingeschakeld voor telemetrie-emissie.

Voor functievlagmen die zijn gedefinieerd in appsettings.json, kunt u telemetrie inschakelen met behulp van de telemetry eigenschap.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

De voorgaande code van een appsettings.json-bestand definieert een functievlag met de naam MyFeatureFlag die is ingeschakeld voor telemetrie. De telemetriestatus wordt aangegeven door het telemetry-object dat enabled instelt op true. De waarde van de enabled eigenschap moet zijn true om telemetriegegevens voor de vlag te publiceren.

De telemetry sectie van een functievlag heeft de volgende eigenschappen:

Publicatie van aangepaste telemetrie

De functiebeheerder heeft een eigen ActivitySource exemplaar met de naam Microsoft.FeatureManagement. Als telemetrie is ingeschakeld voor een functievlag:

• Wanneer een evaluatie van een functievlag wordt gestart, start de functiebeheerder een exemplaar van Activity.
• Wanneer de evaluatie van een functievlag is voltooid, voegt de functiebeheerder een exemplaar, ActivityEvent, genaamd FeatureFlag, toe aan de huidige activiteit.

De FeatureFlag gebeurtenis bevat tags met de informatie over de functievlag-evaluatie. De tags gebruiken de velden die zijn gedefinieerd in het FeatureEvaluationEvent-schema .

Als u aangepaste telemetriepublicaties wilt inschakelen, kunt u een exemplaar van ActivityListener maken en naar de Microsoft.FeatureManagement-activiteitsbron luisteren. De volgende code laat zien hoe u naar de bron van de functiebeheeractiviteit luistert en een callback toevoegt wanneer een functie wordt geëvalueerd.

ActivitySource.AddActivityListener(new ActivityListener()
{
    ShouldListenTo = (activitySource) => activitySource.Name == "Microsoft.FeatureManagement",
    Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllData,
    ActivityStopped = (activity) =>
    {
        ActivityEvent? evaluationEvent = activity.Events.FirstOrDefault((activityEvent) => activityEvent.Name == "FeatureFlag");

        if (evaluationEvent.HasValue && evaluationEvent.Value.Tags.Any())
        {
            // Do something.
        }
    }
});

Zie Een gedistribueerde tracering verzamelen voor meer informatie.

Application Insights-telemetrie

Het Microsoft.FeatureManagement.Telemetry.ApplicationInsights pakket biedt een ingebouwde telemetrie-uitgever waarmee evaluatiegegevens van functievlagken worden verzonden naar Application Insights. Het Microsoft.FeatureManagement.Telemetry.ApplicationInsights pakket biedt ook een telemetrie-initialisatiefunctie waarmee automatisch alle gebeurtenissen TargetingId worden gelabeld, zodat gebeurtenissen kunnen worden gekoppeld om evaluaties te markeren. Als u gebruik wilt maken van deze functionaliteit, voegt u een verwijzing naar het pakket toe en registreert u de Application Insights-telemetrie. De volgende code bevat een voorbeeld:

builder.services
    .AddFeatureManagement()
    .AddApplicationInsightsTelemetry();

Als u persistentie van doelcontext in de huidige activiteit wilt inschakelen, kunt u de TargetingHttpContextMiddleware klasse gebruiken.

app.UseMiddleware<TargetingHttpContextMiddleware>();

Zie het voorbeeld VariantAndTelemetryDemo voor een voorbeeld van het gebruik.

Vereiste

Voor de telemetrie-uitgever die het Microsoft.FeatureManagement.Telemetry.ApplicationInsights pakket biedt, moet Application Insights worden ingesteld en geregistreerd als een toepassingsservice. Zie de voorbeeldtoepassing VariantAndTelemetryDemo voor voorbeeldcode.

Caching

De functiestatus wordt geleverd door het IConfiguration systeem. Van configuratieproviders wordt verwacht dat zij caching en dynamische updates afhandelen. De functiebeheerder vraagt om IConfiguration de meest recente waarde van de status van een functie wanneer deze evalueert of een functie is ingeschakeld.

Momentopname

Voor sommige scenario's moet de status van een functie consistent blijven tijdens de levensduur van een aanvraag. De waarden die worden geretourneerd uit een standaard IVariantFeatureManager implementatie, kunnen veranderen als de IConfiguration bron waaruit deze wordt opgehaald, tijdens de aanvraag wordt bijgewerkt.

U kunt dit gedrag voorkomen met behulp van IVariantFeatureManagerSnapshot. U kunt op dezelfde manier ophalen IVariantFeatureManagerSnapshot als IVariantFeatureManager. IVariantFeatureManagerSnapshot implementeert de IVariantFeatureManager interface, maar IVariantFeatureManagerSnapshot slaat de eerste geëvalueerde status van een functie in de cache op tijdens een aanvraag. Deze status wordt geretourneerd tijdens de levensduur van de functie.

Aangepaste functieproviders

Wanneer u een aangepaste functieprovider implementeert, kunt u functievlagmen ophalen uit bronnen zoals een database of een functiebeheerservice. De standaardfunctieprovider haalt functievlagmen op uit het .NET Core-configuratiesysteem. Dit systeem biedt ondersteuning voor het definiëren van functies in een appsettings.json-bestand of in configuratieproviders zoals Azure App Configuration. U kunt dit gedrag aanpassen om te bepalen waar functiedefinities vandaan worden gelezen.

Als u het laden van functiedefinities wilt aanpassen, moet u de IFeatureDefinitionProvider interface implementeren.

public interface IFeatureDefinitionProvider
{
    Task<FeatureDefinition> GetFeatureDefinitionAsync(string featureName);

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

Als u een implementatie van IFeatureDefinitionProviderwilt gebruiken, moet u deze toevoegen aan de serviceverzameling voordat u functiebeheer toevoegt. In het volgende voorbeeld wordt een implementatie van IFeatureDefinitionProvider de naam InMemoryFeatureDefinitionProvidertoegevoegd.

services.AddSingleton<IFeatureDefinitionProvider, InMemoryFeatureDefinitionProvider>()
        .AddFeatureManagement()

Volgende stappen

Zie de volgende quickstarts voor informatie over het gebruik van functievlagmen in uw toepassingen:

Zie de volgende zelfstudies voor informatie over het gebruik van functiefilters: