.NET-funktionshantering

Med .NET-funktionshanteringsbiblioteket kan du utveckla och exponera programfunktioner baserat på funktionsflaggor. När en ny funktion utvecklas har många program särskilda krav, till exempel när funktionen ska aktiveras och under vilka förhållanden. Det här biblioteket är ett sätt att definiera dessa relationer. Den integreras också med vanliga .NET-kodmönster för att göra det möjligt att exponera dessa funktioner.

Funktionsflaggor är ett sätt för .NET- och ASP.NET Core-program att aktivera eller inaktivera funktioner dynamiskt. Du kan använda funktionsflaggor i grundläggande användningsfall som villkorssatser. Du kan också använda funktionsflaggor i mer avancerade scenarier som att villkorligt lägga till vägar eller MVC-filter (model-view-controller). Funktionsflaggor bygger på .NET Core-konfigurationssystemet. Alla .NET Core-konfigurationsprovider kan fungera som stamnät för funktionsflaggor.

Här är några av fördelarna med att använda .NET-funktionshanteringsbiblioteket:

• Den använder vanliga konventioner för funktionshantering.
• Den har en låg inträdesbarriär:
  • Den bygger på IConfiguration gränssnittet.
  • Den stöder konfiguration av JSON-filfunktionsflagga.
• Den tillhandahåller hantering av livslängden för funktionsflaggor.
  • Konfigurationsvärden kan ändras i realtid.
  • Funktionsflaggor kan vara konsekventa i hela begäran.
• Den omfattar grundläggande till komplexa scenarier genom att erbjuda stöd för följande funktioner:
  • Aktivera och inaktivera funktioner via en deklarativ konfigurationsfil
  • Presentera olika varianter av en funktion för olika användare
  • Dynamisk utvärdering av tillståndet för en funktion baserat på ett anrop till en server
• Det tillhandahåller API-tillägg för ASP.NET Core- och MVC-ramverk inom följande områden:
  • Routning
  • Filter
  • Åtgärdsattribut

.NET-funktionshanteringsbiblioteket är öppen källkod. Mer information finns i GitHub-lagringsplatsen FeatureManagement-Dotnet .

Funktionsflaggor (Feature flags)

Funktionsflaggor kan antingen aktiveras eller inaktiveras. Status för en flagga kan villkoras med hjälp av funktionsfilter.

Filter för funktioner

Funktionsfilter definierar ett scenario för när en funktion ska aktiveras. För att utvärdera tillståndet för en funktion bläddras dess lista över funktionsfilter tills ett av filtren fastställer att funktionen är aktiverad. Nu stoppas genomströmningen genom funktionsfiltren. Om inget funktionsfilter anger att funktionen ska vara aktiverad anses den vara inaktiverad.

Anta till exempel att du utformar ett funktionsfilter för Microsoft Edge-webbläsare. Om en HTTP-begäran kommer från Microsoft Edge aktiverar funktionsfiltret alla funktioner som den är kopplad till.

Konfiguration av funktionsflagga

.NET Core-konfigurationssystemet används för att fastställa tillståndet för funktionsflaggor. Grunden för det här systemet är gränssnittet IConfiguration . Valfri provider för IConfiguration kan användas som funktionstillståndsprovider för funktionsflaggabiblioteket. Det här systemet stöder scenarier som sträcker sig frånappsettings.json-konfigurationsfilen till Azure App Configuration.

Deklaration av funktionsflagga

Funktionshanteringsbiblioteket stöder appsettings.json konfigurationsfilen som en funktionsflaggakälla eftersom det är en provider för .NET Core-systemet IConfiguration . Funktionsflaggor deklareras med hjälp av Microsoft Feature Management schema. Det här schemat är språkberoende och stöds i alla Microsofts funktionshanteringsbibliotek.

Koden i följande exempel deklarerar funktionsflaggor i en JSON-fil:

{
    "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"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Avsnittet feature_management i JSON-dokumentet används av konventionen för att läsa in inställningar för funktionsflagga. Du måste lista funktionsflaggaobjekt i matrisen feature_flags i det här avsnittet. Den här koden visar tre funktionsflaggor. Varje funktionsflaggaobjekt har en id och en enabled egenskap.

• Värdet id är det namn som du använder för att identifiera och referera till funktionsflaggan.
• Egenskapen enabled anger det aktiverade tillståndet för funktionsflaggan.

En funktion är inaktiverad om enabled är false. Om enabled är trueberor funktionens tillstånd på conditions egenskapen. Egenskapen conditions deklarerar de villkor som används för att dynamiskt aktivera funktionen.

• Om en funktionsflagga inte har någon conditions egenskap är funktionen aktiverad.
• Om en funktionsflagga har en conditions egenskap och dess villkor uppfylls är funktionen aktiverad.
• Om en funktionsflagga har en conditions egenskap och dess villkor inte uppfylls är funktionen inaktiverad.

Funktionsfilter definieras i matrisen client_filters . I föregående kod har funktionsflaggan FeatureV ett funktionsfilter med namnet Microsoft.TimeWindow. Det här filtret är ett exempel på ett konfigurerbart funktionsfilter. I den här koden har det här filtret en parameters egenskap. Den här egenskapen används för att konfigurera filtret. I det här fallet konfigureras start- och sluttiderna för funktionen som ska vara aktiv.

Avancerad: Kolontecknet (:) är förbjudet i funktionsflaggans namn.

Kravtyp

Inom egenskapen conditions används egenskapen requirement_type för att avgöra om filtren ska använda Any- eller All-logik när tillståndet för en funktion utvärderas. Om requirement_type inte anges är Anystandardvärdet . Värdena requirement_type resulterar i följande beteende:

• Any: Endast ett filter behöver utvärderas för true att funktionen ska aktiveras.
• All: Varje filter måste utvärderas till true för att funktionen ska aktiveras.

En requirement_type av All ändrar hur filtren traverseras.

• Om inga filter visas är funktionen inaktiverad.
• Om filter visas bläddras de tills villkoren för ett anger att funktionen ska inaktiveras. Om inget filter anger att funktionen ska inaktiveras anses den vara aktiverad.

{
    "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"
                }
            }
        ]
    }
}

I det här exemplet har funktionsflaggan FeatureW ett requirement_type värde på All. Därför måste alla dess filter utvärderas till true för att funktionen ska aktiveras. I det här fallet är funktionen aktiverad för 50 procent av användarna under den angivna tidsperioden.

Hantera flera konfigurationskällor

Från och med v4.3.0 kan du välja anpassad sammanslagning för Microsoft-schemafunktionsflaggor (avsnittet feature_management ). När samma funktionsflagga-ID visas i flera konfigurationskällor sammanfogar en instans av den inbyggda ConfigurationFeatureDefinitionProvider klassen dessa definitioner enligt registreringsordningen för konfigurationsprovidern. Om det finns en konflikt används den senaste funktionsflaggadefinitionen. Det här beteendet skiljer sig från standardmatrisindexbaserad sammanslagning i .NET.

Följande kod möjliggör sammanslagning av konfigurationen för anpassade funktionsflaggor genom beroendeinjicering:

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

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

Du kan också aktivera anpassad sammanslagning när du skapar en instans av ConfigurationFeatureDefinitionProvider:

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

Exempelbeteende:

// 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 }
        ]
    }
}

När du aktiverar anpassad sammanslagning förblir FeatureA aktiverad och FeatureB resulterar i aktiverad, eftersom den senaste deklarationen används. När du använder standardmässig .NET-sammanslagning, där anpassad sammanslagning är inaktiverad, sammanfogas matriser med index. Den här metoden kan ge oväntade resultat om källorna inte justeras efter position.

.NET-funktionshanteringsschema

I tidigare versioner av funktionshanteringsbiblioteket var det primära schemat .NET-funktionshanteringsschemat.

Från och med version 4.0.0 av biblioteket stöds inte nya funktioner, inklusive varianter och telemetri, i .NET-funktionshanteringsschemat.

Förbrukning

I en grundläggande implementering kontrollerar funktionshantering om en funktionsflagga är aktiverad. Sedan utför den åtgärder baserat på resultatet. Den här kontrollen görs med IsEnabledAsync metoden IVariantFeatureManager.

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

Tjänstregistrering

Funktionshantering förlitar sig på .NET Core-beroendeinmatning. Som följande kod visar kan du använda standardkonventioner för att registrera funktionshanteringstjänster:

using Microsoft.FeatureManagement;

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

Som standardinställning hämtar funktionshanteraren konfigurationen av funktionsflagga från avsnitten feature_management eller FeatureManagement i .NET Core-konfigurationsdata. Om inget av avsnitten finns anses konfigurationen vara tom.

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

Beroendeinsprutning

När du använder funktionshanteringsbiblioteket med MVC kan du hämta objektet som implementeras IVariantFeatureManager med hjälp av beroendeinmatning.

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

Begränsade funktionshanteringstjänster

Metoden AddFeatureManagement lägger till funktionshanteringstjänster som singletons i ett program. Vissa scenarier kräver att funktionshanteringstjänster läggs till som begränsade tjänster i stället. Du kanske till exempel vill använda funktionsfilter som använder begränsade tjänster för kontextinformation. I det här fallet bör du använda AddScopedFeatureManagement -metoden. Den här metoden säkerställer att funktionshanteringstjänster, inklusive funktionsfilter, läggs till som begränsade tjänster.

services.AddScopedFeatureManagement();

ASP.NET Core-integrering

Funktionshanteringsbiblioteket innehåller funktioner i ASP.NET Core och MVC för att aktivera vanliga scenarier med funktionsflagga i webbprogram. De här funktionerna är tillgängliga genom att referera till NuGet-paketet Microsoft.FeatureManagement.AspNetCore .

Kontrollanter och åtgärder

En MVC-styrenhet och åtgärder kan kräva att en viss funktion, eller en av alla listor över funktioner, aktiveras för att kunna köras. Du kan uppfylla det här kravet med hjälp av ett FeatureGateAttribute objekt. Klassen FeatureGateAttribute definieras i Microsoft.FeatureManagement.Mvc namnområdet.

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

I det föregående exemplet styrs klassen HomeController av FeatureX. HomeController åtgärder kan bara köras om funktionen FeatureX är aktiverad.

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

I föregående exempel Index kan MVC-åtgärden endast köras om FeatureX funktionen är aktiverad.

Hantering av åtgärder inaktiverad

När en MVC-styrenhet eller åtgärd blockeras eftersom ingen av de funktioner som anges är aktiverade anropas en registrerad implementering av IDisabledFeaturesHandler . Som standard registreras en minimalistisk hanterare som returnerar ett HTTP 404-fel. Du kan åsidosätta den här hanteraren genom att använda IFeatureManagementBuilder när du registrerar funktionsflaggor.

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

Visa

I MVC-vyer kan du använda <feature> taggar för att villkorligt återge innehåll. Du kan basera återgivningsvillkoren på om en funktion är aktiverad eller om en specifik variant av en funktion har tilldelats. Mer information finns i Varianter senare i den här artikeln.

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

Du kan också ta bort tagghjälpsutvärderingen om du vill visa innehåll när en funktion eller uppsättning funktioner är inaktiverade. Om du anger negate="true", som i följande exempel återges innehållet endast när FeatureX det är inaktiverat.

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

Du kan använda taggen <feature> för att referera till flera funktioner. Om du vill göra det anger du en kommaavgränsad lista över funktioner i attributet name .

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

Som standard måste alla listade funktioner vara aktiverade för att funktionstaggen ska återges. Du kan åsidosätta det här beteendet genom att lägga till requirement attributet, vilket visas i följande exempel.

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

Du kan också använda taggen <feature> för att referera till flera varianter. Det gör du genom att använda värdet requirementAny och ange en kommaavgränsad lista med varianter i variant attributet.

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

Taggen <feature> kräver en tag helper för att fungera. Om du vill använda taggen lägger du till hjälpverktyget för funktionshanteringstaggen i filen _ViewImports.cshtml .

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC-filter

Du kan konfigurera MVC-åtgärdsfilter som du tillämpar villkorligt baserat på tillståndet för en funktion. Om du vill konfigurera dessa filter registrerar du dem på ett funktionsmedveten sätt. Pipelinen för funktionshantering stöder asynkrona MVC-åtgärdsfilter som implementerar IAsyncActionFilter gränssnittet.

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

Föregående kod registrerar ett MVC-filter med namnet SomeMvcFilter. Det här filtret utlöses endast i MVC-pipelinen om FeatureX det är aktiverat.

Razor-sidor

MVC Razor-sidor kan kräva att en viss funktion, eller en av alla listor över funktioner, aktiveras för att kunna köras. Du kan lägga till det här kravet med hjälp av ett FeatureGateAttribute objekt. Klassen FeatureGateAttribute definieras i Microsoft.FeatureManagement.Mvc namnområdet.

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

Föregående kod konfigurerar en Razor-sida som kräver att FeatureX är aktiverad. Om funktionen inte är aktiverad genererar sidan ett HTTP 404-resultat (NotFound).

När du använder ett FeatureGateAttribute objekt på Razor-sidor måste du placera FeatureGateAttribute på sidhanterartypen. Du kan inte placera den på enskilda metodhanterare.

Programbygge

Du kan använda funktionshanteringsbiblioteket för att lägga till programgrenar och mellanprogram som körs villkorligt baserat på tillståndet för en funktion.

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

I föregående kod lägger programmet till en mellanprogramskomponent som endast visas i pipelinen för begäran om FeatureX funktionen är aktiverad. Om funktionen är aktiverad eller inaktiverad under körningen kan pipelinen för mellanprogram ändras dynamiskt.

Som följande kod visar bygger den här funktionen på den mer allmänna funktionen för att förgrena hela programmet baserat på en funktion.

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

Implementera ett funktionsfilter

Genom att skapa ett funktionsfilter kan du aktivera funktioner baserat på kriterier som du definierar. Om du vill implementera ett funktionsfilter måste du implementera IFeatureFilter gränssnittet. IFeatureFilter har en enda metod med namnet EvaluateAsync. När en funktion anger att den kan aktiveras för ett funktionsfilter EvaluateAsync anropas metoden. Om EvaluateAsync returnerar trueska funktionen vara aktiverad.

Följande kod visar hur du lägger till ett anpassat funktionsfilter med namnet MyCriteriaFilter.

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

Du kan registrera ett funktionsfilter genom att anropa AddFeatureFilter<T> på IFeatureManagementBuilder-implementeringen som AddFeatureManagement returnerar. Funktionsfiltret har åtkomst till tjänsterna i tjänstsamlingen som du använder för att lägga till funktionsflaggor. Du kan använda beroendeinjektion för att hämta dessa tjänster.

Parameteriserade funktionsfilter

Vissa funktionsfilter kräver parametrar för att utvärdera om en funktion ska aktiveras. Ett webbläsarfunktionsfilter kan till exempel aktivera en funktion för en viss uppsättning webbläsare. Du kanske vill aktivera en funktion i Webbläsaren Microsoft Edge och Chrome, men inte i Firefox.

Om du vill implementera den här filtreringen kan du utforma ett funktionsfilter för att förvänta dig parametrar. Du anger dessa parametrar i funktionskonfigurationen. I kod kommer du åt dem via parametern FeatureFilterEvaluationContextIFeatureFilter.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; }
}

Klassen FeatureFilterEvaluationContext har en egenskap med namnet Parameters. Parametrarna för den här egenskapen representerar en råkonfiguration som funktionsfiltret kan använda när du utvärderar om funktionen ska aktiveras. I exemplet med webbläsarfunktionens filter kan filtret använda Parameters egenskapen för att extrahera en uppsättning tillåtna webbläsare som har angetts för funktionen. Filtret kan sedan kontrollera om begäran kommer från någon av dessa webbläsare.

[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.
    }
}

Filteraliasattribut

När du registrerar ett funktionsfilter för en funktionsflagga är det alias som du använder i konfigurationen namnet på funktionsfiltertypen med suffixet, om det finns, borttaget Filter . Du bör till exempel referera till MyCriteriaFilter som MyCriteria i konfigurationen.

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

Du kan åsidosätta det här namnet med hjälp FilterAliasAttribute av klassen . Om du vill deklarera ett namn som ska användas i konfigurationen för att referera till ett funktionsfilter i en funktionsflagga kan du dekorera funktionsfiltret med det här attributet.

Filter för funktioner saknas

Anta att du konfigurerar en funktion som ska aktiveras för ett specifikt funktionsfilter. Om funktionsfiltret inte har registrerats utlöses ett undantag när funktionen utvärderas. Som följande kod visar kan du inaktivera undantaget med hjälp av alternativ för funktionshantering.

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

Använd HttpContext

Funktionsfilter kan utvärdera om en funktion ska aktiveras baserat på egenskaperna för en HTTP-begäran. Den här kontrollen utförs genom att kontrollera HTTP-kontexten. Som följande kod visar kan ett funktionsfilter hämta en referens till HTTP-kontexten genom att använda beroendeinmatning för att få en implementering av IHttpContextAccessor.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

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

Du måste lägga till implementeringen i IHttpContextAccessor containern för beroendeinmatning vid start för att den ska vara tillgänglig. Du kan använda följande metod för att registrera implementeringen i IServiceCollection tjänsterna.

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

Avancerad:IHttpContextAccessor och HttpContext bör inte användas i Razor-komponenterna i Blazor-appar på serversidan. Den rekommenderade metoden för att skicka HTTP-kontext i Blazor-appar är att kopiera data till en begränsad tjänst. För Blazor-appar bör du använda AddScopedFeatureManagement för att registrera funktionshanteringstjänster. Mer information finns i Omfångstjänster för funktionshantering tidigare i den här artikeln.

Ange en kontext för funktionsutvärdering

I konsolprogram finns det ingen omgivande kontext, som HttpContext, som funktionsfilter kan använda för att kontrollera om en funktion ska vara aktiv. I det här fallet måste program tillhandahålla ett objekt som representerar en kontext till funktionshanteringssystemet för användning av funktionsfilter. Du kan använda IVariantFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext) för att ange den här kontexten. För att utvärdera tillståndet för en funktion kan funktionsfilter använda det appContext objekt som du anger för funktionshanteraren.

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

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

Kontextuella funktionsfilter

Kontextuella funktionsfilter implementerar IContextualFeatureFilter<TContext> gränssnittet. Dessa särskilda funktionsfilter kan dra nytta av kontexten som skickas in när IVariantFeatureManager.IsEnabledAsync<TContext> anropas. Typparametern TContext i IContextualFeatureFilter<TContext> beskriver kontexttypen som filtret kan hantera. När du utvecklar ett kontextuellt funktionsfilter kan du fastställa kraven för att använda filtret genom att ange en kontexttyp.

Eftersom varje typ är en underordnad till klassen Object, kan ett filter som implementerar IContextualFeatureFilter<object> anropas för valfri kontext. Följande kod innehåller ett exempel på ett specifikt kontextuellt funktionsfilter. I den här koden aktiveras en funktion om ett konto finns i en konfigurerad lista över aktiverade konton.

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.
    }
}

Klassen AccountIdFilter kräver att ett objekt som implementerar IAccountContext tillhandahålls för att kunna utvärdera tillståndet för en funktionalitet. När du använder det här funktionsfiltret måste anroparen se till att det skickade objektet implementerar IAccountContext.

Använda kontextuella och icke-kontextuella filter med samma alias

Filter som implementerar IFeatureFilter och IContextualFeatureFilter kan dela samma alias. Mer specifikt kan du ha ett filteralias som delas av noll eller en IFeatureFilter implementering och noll eller N-implementeringarIContextualFeatureFilter<ContextType> om det finns högst ett tillämpligt filter för ContextType.

Om du vill förstå processen med att välja ett filter när kontextuella och icke-kontextuella filter med samma namn registreras i ett program bör du överväga följande exempel.

Tre filter delar aliaset SharedFilterName :

• Ett icke-kontextuellt filter som heter FilterA
• Ett sammanhangsberoende filter med namnet FilterB som accepterar en TypeB kontext
• Ett sammanhangsberoende filter med namnet FilterC som accepterar en TypeC kontext

En funktionsflagga med namnet MyFeature använder funktionsfiltret SharedFilterName i konfigurationen.

Om alla tre filtren är registrerade:

• När du anropar IsEnabledAsync("MyFeature")FilterA används filtret för att utvärdera funktionsflaggan.
• När du ringer IsEnabledAsync("MyFeature", context):
  • Om typen av context är TypeBanvänds FilterB .
  • Om typen av context är TypeCanvänds FilterC .
  • Om typen av context är TypeFanvänds FilterA .

Inbyggda funktionsfilter

Det finns några funktionsfilter som medföljer Microsoft.FeatureManagement paketet: PercentageFilter, TimeWindowFilter, ContextualTargetingFilteroch TargetingFilter. Alla filter utom TargetingFilter läggs till automatiskt när du använder AddFeatureManagement metoden för att registrera funktionshantering. TargetingFilter läggs till med hjälp av WithTargeting-metoden. Mer information finns i Mål, senare i den här artikeln.

Vart och ett av de inbyggda funktionsfiltren har sina egna parametrar. I följande avsnitt beskrivs dessa funktionsfilter och innehåller exempel.

Microsoft.Percentage

Filtret Microsoft.Percentage ger ett sätt att aktivera en funktion baserat på en angiven procentandel.

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

Microsoft.TimeWindow

Filtret Microsoft.TimeWindow ger ett sätt att aktivera en funktion baserat på ett tidsfönster.

• Om du bara anger ett End värde beaktas funktionen fram till dess.
• Om du bara anger ett Start värde beaktas funktionen på vid alla tidpunkter efter den tiden.

{
    "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"
                }
            }
        ]
    }
}

Du kan konfigurera filtret så att det tillämpar ett tidsfönster regelbundet. Den här funktionen kan vara användbar när du behöver aktivera en funktion under en period med låg trafik eller hög trafik på en dag eller vissa dagar i veckan. Om du vill expandera ett enskilt tidsfönster till ett återkommande tidsfönster använder du en Recurrence parameter för att ange en upprepningsregel.

{
    "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"
                        }
                    }
                }
            }
        ]
    }
}

Recurrence Inställningarna består av två delar:

• Inställningarna Pattern anger hur ofta tidsfönstret upprepas.
• Range Inställningarna anger hur länge upprepningsmönstret upprepas.

Upprepningsmönster

Det finns två möjliga typer av upprepningsmönster: Daily och Weekly. Ett tidsfönster kan till exempel upprepas varje dag, var tredje dag, varje måndag eller varannan fredag.

Beroende på typen krävs vissa fält i Pattern inställningsalternativen: de kan vara obligatoriska, valfria eller ignorerade.

• Daily

  Det dagliga upprepningsmönstret gör att tidsfönstret upprepas baserat på ett angivet antal dagar mellan varje förekomst.

  Property	Relevans	beskrivning
  Type	Obligatoriskt	Typ av upprepningsmönster. Måste anges till Daily.
  Interval	Valfritt	Antalet dagar mellan varje förekomst. Standardvärdet är 1.

• Weekly

  Det veckovisa upprepningsmönstret gör att tidsfönstret upprepas samma dag eller dagar i veckan. Men du kan ange antalet veckor mellan varje uppsättning förekomster.

  Property	Relevans	beskrivning
  Type	Obligatoriskt	Typ av upprepningsmönster. Måste anges till Weekly.
  DaysOfWeek	Obligatoriskt	Veckodagar som händelsen inträffar på.
  Interval	Valfritt	Antalet veckor mellan varje uppsättning förekomster. Standardvärdet är 1.
  FirstDayOfWeek	Valfritt	Den dag som ska användas som den första dagen i veckan. Standardvärdet är Sunday.

  I följande exempel upprepas tidsfönstret varannan måndag och tisdag:

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

Intervall för upprepning

Det finns tre möjliga typer av upprepningsintervall: NoEnd, EndDateoch Numbered.

• NoEnd

  Intervallet NoEnd gör att upprepningen sker på obestämd tid.

  Property	Relevans	beskrivning
  Type	Obligatoriskt	Typ av upprepningsintervall. Måste anges till NoEnd.

• EndDate

  Intervallet EndDate gör att tidsfönstret inträffar på alla dagar som passar det tillämpliga mönstret fram till slutdatumet.

  Property	Relevans	beskrivning
  Type	Obligatoriskt	Typ av upprepningsintervall. Måste anges till EndDate.
  EndDate	Obligatoriskt	Datum och tid för att sluta tillämpa mönstret. Om starttiden för den senaste förekomsten infaller före slutdatumet kan sluttiden för den förekomsten sträcka sig längre än den.

  I följande exempel upprepas tidsfönstret varje dag till den sista förekomsten den 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

  Intervallet Numbered gör att tidsfönstret inträffar ett angivet antal gånger.

  Property	Relevans	beskrivning
  Type	Obligatoriskt	Typ av upprepningsintervall. Måste anges till Numbered.
  NumberOfOccurrences	Obligatoriskt	Antalet förekomster.

  I följande exempel upprepas tidsfönstret på måndag och tisdag för totalt tre förekomster, som inträffar på följande datum:

  • Måndag 1 april
  • Tisdag 2 april
  • Måndag 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 du vill skapa en upprepningsregel måste du ange både Pattern och Range inställningar. Alla mönstertyper kan fungera med valfri intervalltyp.

Avancerat: Tidszonsförskjutningen för Start egenskapen tillämpas på upprepningsinställningarna.

Microsoft.Targeting

Filtret Microsoft.Targeting ger ett sätt att aktivera en funktion för en målgrupp. En detaljerad förklaring av mål finns i Mål, senare i den här artikeln.

Filterparametrarna innehåller ett Audience objekt som beskriver vem som har åtkomst till funktionen. Audience I objektet kan du ange användare, grupper, exkluderade användare och grupper samt en standardprocentprocent av användarbasen.

För varje gruppobjekt som du listar i Groups avsnittet måste du också ange vilken procentandel av gruppens medlemmar som ska ha åtkomst.

För varje användare utvärderas funktionen på följande sätt:

• Om användaren undantas inaktiveras funktionen för användaren. Du kan exkludera användaren genom att:

  • Lista deras namn under Users i avsnittet Exclusion .
  • Lista en grupp som de tillhör under Groups i avsnittet Exclusion .

• Om användaren inte är exkluderad aktiveras funktionen om något av följande villkor uppfylls:

  • Användaren visas i avsnittet Users .
  • Användaren ingår i den procentsats som ingår i någon av grupputrullningarna.
  • Användaren hamnar i standardprocenten för distribution.

• Om inget av de tidigare fallen gäller inaktiveras funktionen för användaren. Om användaren till exempel inte ingår i en procentsats inaktiveras funktionen.

{
    "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"
                            ]
                        }
                    }
                }
            }
        ]
    }
}

Namnområden för funktionsfilteralias

Alla inbyggda funktionsfilteralias finns i namnområdet för funktionsfilter Microsoft . Att vara i det här namnområdet förhindrar konflikter med andra funktionsfilter som delar samma alias. Segmenten i namnområdet för ett funktionsfilter separeras av tecknet .. Du kan referera till ett funktionsfilter med dess fullständigt kvalificerade alias, till exempel Microsoft.Percentage. Eller så kan du referera till det sista segmentet, till exempel Percentage.

Sök mål

Inriktning är en strategi för funktionshantering som du kan använda för att successivt distribuera nya funktioner till din användarbas. Strategin bygger på konceptet att rikta in sig på en uppsättning användare som kallas målgruppen. En målgrupp består av specifika användare, grupper, exkluderade användare och grupper samt en angiven procentandel av hela användarbasen. De grupper som ingår i målgruppen kan delas upp ytterligare i procent av deras totala medlemmar.

Följande steg visar ett exempel på en progressiv distribution för en ny funktion med namnet Beta:

1. Enskilda användare Jeff och Alicia beviljas åtkomst till betafunktionen.
2. En annan användare, Mark, ber att få anmäla sig och inkluderas.
3. 20 procent av användarna i Gruppen Ring1 ingår i betafunktionen.
4. Antalet Ring1-användare som ingår ökar med upp till 100 procent.
5. Fem procent av användarbasen ingår i betafunktionen.
6. Distributionsprocenten ökar till 100 procent för att helt distribuera funktionen.

Biblioteket stöder den här strategin för att lansera en funktion via det inbyggda funktionsfiltret Microsoft.Targeting .

Målinriktning i en webbapplikation

Ett exempel på ett webbprogram som använder målfunktionsfiltret finns i exempelprojektet FeatureFlagDemo .

Om du vill börja använda TargetingFilter i ett program måste du lägga till det i programmets tjänstsamling precis som andra funktionsfilter. Till skillnad från andra inbyggda filter TargetingFilter förlitar sig på att en annan tjänst läggs till i programmets tjänstsamling. Den tjänsten är en ITargetingContextAccessor implementering.

Biblioteket Microsoft.FeatureManagement.AspNetCore tillhandahåller en standardimplementering av ITargetingContextAccessor som extraherar målinformation från en begärans HttpContext värde. Du kan använda standardinställningen för kontextåtkomst när du konfigurerar mål med hjälp av den icke-generiska WithTargeting överbelastningen på IFeatureManagementBuilder.

För att registrera standardkontextens åtkomsthanterare och TargetingFilter ringer du WithTargeting på IFeatureManagementBuilder.

services.AddFeatureManagement()
        .WithTargeting();

Du kan också registrera en anpassad implementering för ITargetingContextAccessor och TargetingFilter genom att anropa WithTargeting<T>. Följande kod installerar funktionshantering i ett webbprogram för att använda TargetingFilter med en implementation av ITargetingContextAccessor som heter ExampleTargetingContextAccessor.

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

ITargetingContextAccessor

Om du vill använda TargetingFilter i ett webbprogram krävs en implementering av ITargetingContextAccessor . Resonemanget bakom det här kravet är att kontextuell information, till exempel information om användaren, behövs för att rikta utvärderingar. Den här informationen lagras i instanser av TargetingContext klassen. Olika program extraherar den här informationen från olika platser, till exempel en begärans HTTP-kontext eller en databas.

Ett exempel som extraherar målkontextinformation från ett programs HTTP-kontext DefaultHttpTargetingContextAccessor finns i paketet Microsoft.FeatureManagement.AspNetCore . Den extraherar följande information:

• Målinformation från egenskapen HttpContext.User
• UserIdinformation från fältet Identity.Name
• Groups information från anspråk av typen Role

Den här implementeringen förlitar sig på användningen av IHttpContextAccessor. Mer information om IHttpContextAccessorfinns i Använda HttpContext tidigare i den här artikeln.

Målkonfiguration i ett konsolprogram

Målfiltret förlitar sig på en målkontext för att utvärdera om en funktion ska aktiveras. Den här målkontexten innehåller information som den användare som utvärderas och de grupper som användaren tillhör. I konsolprogram finns det vanligtvis ingen omgivande kontext tillgänglig för att skicka den här informationen till målfiltret. Därför måste du skicka det direkt när du anropar FeatureManager.IsEnabledAsync. Den här typen av kontext stöds med hjälp av ContextualTargetingFilter. Program som behöver skicka målkontexten till funktionshanteraren bör använda ContextualTargetingFilter i stället för TargetingFilter.

Eftersom ContextualTargetingFilter implementerar IContextualTargetingFilter<ITargetingContext>måste du skicka en implementering av ITargetingContext till IVariantFeatureManager.IsEnabledAsync för att den ska kunna utvärdera och aktivera en funktion.

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 använder aliaset för funktionsfilter Microsoft.Targetingså att konfigurationen för det här filtret överensstämmer med informationen i Microsoft.Targeting tidigare i den här artikeln.

Ett exempel som används ContextualTargetingFilter i ett konsolprogram finns i exempelprojektet TargetingConsoleApp .

Inriktning på utvärderingsalternativ

Det finns alternativ för att anpassa hur målutvärdering utförs för alla funktioner. Du kan konfigurera de här alternativen när du konfigurerar funktionshantering.

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

Målundantag

När du definierar en målgrupp kan du exkludera användare och grupper från målgruppen. Den här funktionen är användbar när du distribuerar en funktion till en grupp användare, men du måste undanta några användare eller grupper från distributionen. Om du vill ange vilka användare och grupper som ska undantas använder Exclusion du egenskapen för en målgrupp.

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

Föregående kod aktiverar en funktion för användare med namnet Jeff och Alicia. Funktionen är också aktiverad för användare i gruppen med namnet Ring0. Funktionen är dock inaktiverad för användaren med namnet Mark, även om den användaren finns i Ring0 gruppen. Undantag prioriteras framför resten av målfiltret.

Varianter

Ibland när du lägger till en ny funktion i ett program har funktionen flera föreslagna designalternativ. A/B-testning är en vanlig lösning för att bestämma en design. A/B-testning innebär att tillhandahålla en annan version av funktionen till olika segment i användarbasen och sedan välja en version baserat på användarinteraktion. I .NET-funktionshanteringsbiblioteket kan du implementera A/B-testning med hjälp av varianter för att representera olika konfigurationer av en funktion.

Varianter är ett sätt för en funktionsflagga att bli mer än en grundläggande på/av-flagga. En variant representerar ett värde för en funktionsflagga som kan vara en sträng, ett tal, ett booleskt eller till och med ett konfigurationsobjekt. En funktionsflagga som deklarerar varianter bör definiera de omständigheter under vilka varje variant ska användas. Mer information finns i Allokera varianter senare i den här artikeln.

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

Hämta varianter

För varje funktion kan du hämta en variant genom att använda GetVariantAsync-metoden av IVariantFeatureManager-gränssnittet.

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

IConfigurationSection variantConfiguration = variant.Configuration;

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

När du har hämtat en variant kan du använda dess konfiguration direkt som en implementering av IConfigurationSection från variantens Configuration egenskap. Ett annat alternativ är att binda konfigurationen till ett objekt med hjälp av .NET-konfigurationsbindningsmönstret.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

Vilken variant som returneras beror på vilken användare som utvärderas. Du kan hämta information om användaren från en instans av TargetingContext. Du kan skicka i den här kontexten när du anropar GetVariantAsync. Eller så kan den hämtas automatiskt från en implementering av ITargetingContextAccessor om en är registrerad.

Deklaration av variantfunktionsflagga

Jämfört med standardfunktionsflaggor har variantfunktionsflaggor två extra egenskaper: variants och allocation. Egenskapen variants är en matris som innehåller de varianter som definierats för funktionen. Egenskapen allocation definierar hur dessa varianter ska allokeras för funktionen. Precis som när du deklarerar standardfunktionsflaggor kan du konfigurera variantfunktionsflaggor i en JSON-fil. Följande kod är ett exempel på en variantfunktionsflagga:

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

Definiera varianter

Varje variant har två egenskaper: ett namn och en konfiguration. Namnet används för att referera till en specifik variant och konfigurationen är värdet för den varianten. Du kan använda egenskapen configuration_value för att ange konfigurationen. Egenskapen configuration_value är en infogad konfiguration som kan vara ett sträng-, tal-, booleskt eller konfigurationsobjekt. Om du inte konfigurerar configuration_value egenskapen, är egenskapen Configuration i den returnerade varianten null.

Om du vill ange alla möjliga varianter för en funktion listar du dem under egenskapen variants .

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

Allokera varianter

Om du vill allokera en funktions varianter använder allocation du funktionens egenskap.

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

Inställningen allocation har följande egenskaper:

Om en funktion inte är aktiverad tilldelar funktionshanteraren den angivna default_when_disabled varianten till den aktuella användaren. I föregående exempel kallas Smallfunktionen .

Om funktionen är aktiverad kontrollerar funktionshanteraren allokeringarna user, group, och percentile i den angivna ordningen för att tilldela en variant. I föregående exempel tilldelas den angivna varianten , Biganvändaren i följande fall:

• Användaren som utvärderas heter Marsha.
• Användaren finns i gruppen Ring1 .
• Användaren råkar falla mellan den nollde och tionde percentilen.

Om ingen av dessa allokeringar matchar tilldelas varianten default_when_enabled till användaren. I exemplet är den varianten Small.

Allokeringslogik liknar den logik som du använder för funktionsfiltret Microsoft.Targeting . Men det finns vissa parametrar som finns i mål som inte finns i allokering, och vice versa. Resultatet av mål och allokering är inte relaterade.

Åsidosätt aktiverat tillstånd med hjälp av en variant

Du kan använda varianter för att åsidosätta det aktiverade tillståndet för en funktionsflagga. När du använder den här funktionen kan du utöka utvärderingen av en funktionsflagga. Under anropet till IsEnabledAsync på en flagga med varianter kontrollerar funktionshanteraren om den variant som tilldelats den aktuella användaren har konfigurerats för att åsidosätta resultatet.

Du kan implementera åsidosättande med hjälp av den valfria variantegenskapen status_override. Den här egenskapen kan ha följande värden:

• None: Varianten påverkar inte om flaggan anses vara aktiverad eller inaktiverad. None är standardvärdet.
• Enabled: När varianten väljs utvärderas funktionsflaggan som aktiverad.
• Disabled: När varianten väljs utvärderas funktionsflaggan som inaktiverad.

Du kan inte åsidosätta en funktion när den har ett enabled-tillstånd av false.

Om du använder en funktionsflagga med binära varianter kan egenskapen status_override vara användbar. Du kan fortsätta att använda API:er som IsEnabledAsync och FeatureGateAttribute i ditt program. Men du kan också dra nytta av de funktioner som medföljer varianter, till exempel percentilallokering och användning av ett startvärde för procentberäkningar.

{
    "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"
        }
    ]
}

I föregående exempel är funktionen alltid aktiverad. Om den aktuella användaren är i det beräknade percentilintervallet 10 till 20 returneras varianten On . Annars returneras varianten Off och eftersom status_override värdet är Disabledanses funktionen vara inaktiverad.

Varianter av beroendeinjektion

Du kan använda variantfunktionsflaggor tillsammans med beroendeinmatning för att exponera olika implementeringar av en tjänst för olika användare. Gränssnittet IVariantServiceProvider<TService> ger ett sätt att åstadkomma den här kombinationen.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken); 

I föregående kod IVariantServiceProvider<IAlgorithm> hämtar implementeringen en implementering av IAlgorithm från containern för beroendeinmatning. Den valda implementeringen är beroende av:

• Funktionsflaggan IAlgorithm som tjänsten är registrerad med.
• Den allokerade varianten för den funktionen.

Implementeringen IVariantServiceProvider<T> görs tillgänglig för programmet genom att anropa IFeatureManagementBuilder.WithVariantService<T>(string featureName), som i följande exempel visas. Anropet i den här koden gör IVariantServiceProvider<IAlgorithm> tillgängligt i tjänstsamlingen.

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

Du måste lägga till varje implementering av IAlgorithm separat via en lägg till metod, till exempel services.AddSingleton<IAlgorithm, SomeImplementation>(). Implementeringen av IAlgorithm som IVariantServiceProvider använder beror på ForecastAlgorithm variantfunktionsflaggan. Om ingen implementering av IAlgorithm läggs till i tjänstsamlingskollektionen returnerar IVariantServiceProvider<IAlgorithm>.GetServiceAsync() en uppgift med ett null resultat.

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

Aliasattribut för varianttjänst

Varianttjänstleverantören använder typnamnen för implementeringar för att matcha den allokerade varianten. Om en varianttjänst är dekorerad med VariantServiceAliasAttributeska namnet som deklareras i det här attributet användas i konfigurationen för att referera till den här varianttjänsten.

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

Telemetri

När du distribuerar en ändring av funktionsflaggan är det ofta viktigt att analysera dess effekt på ett program. Här är till exempel några frågor som kan uppstå:

• Är flaggorna aktiverade och inaktiverade som förväntat?
• Får målanvändare åtkomst till en viss funktion som förväntat?
• Vilken variant ser en viss användare?

Generering och analys av händelser vid utvärdering av funktionsflaggor kan hjälpa dig att besvara dessa typer av frågor. .NET-funktionshanteringsbiblioteket använder API:et System.Diagnostics.Activity för att producera spårningstelemetri under utvärdering av funktionsflagga.

Aktivera telemetri

Som standard har funktionsflaggor ingen telemetri genererad. Om du vill publicera telemetri för en viss funktionsflagga måste flaggan deklarera att den är aktiverad för telemetriutsläpp.

För funktionsflaggor som definierats i appsettings.jsonkan du aktivera telemetri med hjälp telemetry av egenskapen .

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

Föregående kod från en appsettings.json-fil definierar en funktionsflagga med namnet MyFeatureFlag som är aktiverad för telemetri. Telemetritillståndet anges av objektet telemetry som anger enabled till true. Värdet för egenskapen enabled måste vara true att publicera telemetri för flaggan.

Avsnittet telemetry i en funktionsflagga har följande egenskaper:

Anpassad telemetripublicering

Funktionshanteraren har en egen ActivitySource instans med namnet Microsoft.FeatureManagement. Om telemetri är aktiverat för en funktionsflagga:

• När en utvärdering av funktionsflaggan startar startar funktionshanteraren en instans av Activity.
• När en utvärdering av funktionsflaggan är klar lägger funktionshanteraren till en ActivityEvent instans med namnet FeatureFlag till den aktuella aktiviteten.

Händelsen FeatureFlag har taggar som innehåller information om funktionsflaggans utvärdering. Taggarna använder fälten som definierats i schemat FeatureEvaluationEvent .

Om du vill aktivera anpassad telemetripublicering kan du skapa en instans av ActivityListener och lyssna på aktivitetskällan Microsoft.FeatureManagement . Följande kod visar hur du lyssnar på aktivitetskällan för funktionshantering och lägger till ett återanrop när en funktion utvärderas.

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.
        }
    }
});

Mer information finns i Samla in en distribuerad spårning.

Application Insights-telemetri

Paketet Microsoft.FeatureManagement.Telemetry.ApplicationInsights innehåller en inbyggd telemetriutgivare som skickar utvärderingsdata för funktionsflaggan till Application Insights. Paketet Microsoft.FeatureManagement.Telemetry.ApplicationInsights innehåller också en telemetriinitierare som automatiskt taggar alla händelser med TargetingId så att händelser kan länkas till flaggutvärderingar. Om du vill dra nytta av den här funktionen lägger du till en referens till paketet och registrerar Application Insights-telemetrin. Följande kod innehåller ett exempel:

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

Om du vill aktivera beständighet för målkontexten i den aktuella aktiviteten kan du använda TargetingHttpContextMiddleware klassen .

app.UseMiddleware<TargetingHttpContextMiddleware>();

Ett exempel på dess användning finns i exemplet VariantAndTelemetryDemo .

Förutsättningar

Telemetriutgivaren som Microsoft.FeatureManagement.Telemetry.ApplicationInsights paketet tillhandahåller kräver att Application Insights konfigureras och registreras som en programtjänst. Exempelkod finns i exempelprogrammet VariantAndTelemetryDemo .

Cachelagring

Funktionstillstånd tillhandahålls av IConfiguration systemet. Konfigurationsprovidrar förväntas hantera eventuell cachelagring och dynamisk uppdatering. Funktionshanteraren frågar efter IConfiguration det senaste värdet för en funktions tillstånd när den utvärderar om en funktion är aktiverad.

Ögonblicksbild

Vissa scenarier kräver att tillståndet för en funktion förblir konsekvent under en begärans livslängd. Värdena som returneras från en standardimplementering IVariantFeatureManager kan ändras om källan IConfiguration som den hämtar från uppdateras under begäran.

Du kan förhindra det här beteendet med hjälp av IVariantFeatureManagerSnapshot. Du kan hämta IVariantFeatureManagerSnapshot på samma sätt som IVariantFeatureManager. IVariantFeatureManagerSnapshot implementerar IVariantFeatureManager gränssnittet, men IVariantFeatureManagerSnapshot cachelagrar det första utvärderade tillståndet för en funktion under en begäran. Den återger tillståndet under hela funktionens livslängd.

Anpassade funktionsleverantörer

När du implementerar en anpassad funktionsprovider kan du hämta funktionsflaggor från källor som en databas eller en funktionshanteringstjänst. Standardfunktionsprovidern hämtar funktionsflaggor från .NET Core-konfigurationssystemet. Det här systemet ger stöd för att definiera funktioner i en appsettings.json-fil eller i konfigurationsleverantörer som Azure App Configuration. Du kan anpassa det här beteendet för att styra var funktiondefinitioner läsas från.

Om du vill anpassa inläsningen av funktionsdefinitioner måste du implementera IFeatureDefinitionProvider gränssnittet.

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

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

Om du vill använda en implementering av IFeatureDefinitionProvidermåste du lägga till den i tjänstsamlingen innan du lägger till funktionshantering. I följande exempel läggs en implementering av IFeatureDefinitionProvider med namnet InMemoryFeatureDefinitionProvider.

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

Nästa steg

Information om hur du använder funktionsflaggor i dina program finns i följande snabbstarter:

Information om hur du använder funktionsfilter finns i följande självstudier: