Správa funkcí .NET

Knihovna pro správu funkcí .NET poskytuje způsob vývoje a zveřejnění funkcí aplikace na základě příznaků funkcí. Při vývoji nové funkce má mnoho aplikací zvláštní požadavky, například kdy by měla být funkce povolena a za jakých podmínek. Tato knihovna poskytuje způsob, jak tyto relace definovat. Integruje se také s běžnými vzory kódu .NET, aby bylo možné tyto funkce zpřístupnit.

Příznaky funkcí poskytují způsob dynamického zapnutí nebo vypnutí funkcí pro aplikace .NET a ASP.NET Core. Příznaky funkcí můžete použít v základních případech použití, jako jsou podmíněné příkazy. Příznaky funkcí můžete použít také v pokročilejších scénářích, jako je podmíněné přidávání tras nebo filtrů MVC (model-view-controller). Příznaky funkcí jsou postavené na konfiguračním systému .NET Core. Každý poskytovatel konfigurace .NET Core dokáže pracovat jako páteřní síť pro příznaky funkcí.

Tady jsou některé výhody používání knihovny pro správu funkcí .NET:

Používá běžné konvence pro správu funkcí.
Má malou bariéru pro vstup:
- Je postavená na IConfiguration rozhraní.
- Podporuje nastavení příznaků funkcionality v souborech JSON.
Poskytuje správu životnosti příznaků funkcí.
- Hodnoty konfigurace se můžou měnit v reálném čase.
- Feature flags můžou být konzistentní v rámci celého požadavku.
Zahrnuje základní až složité scénáře tím, že nabízí podporu pro následující možnosti:
- Zapnutí a vypnutí funkcí prostřednictvím deklarativního konfiguračního souboru
- Prezentace různých variant funkce různým uživatelům
- Dynamické vyhodnocení stavu funkce na základě volání serveru
Poskytuje rozšíření rozhraní API pro architekturu ASP.NET Core a MVC v následujících oblastech:
- Směrování
- Filtry
- Atributy akce

Knihovna pro správu funkcí .NET je open source. Další informace najdete v úložišti FeatureManagement-Dotnet Na GitHubu.

Hlavní příznaky

Příznaky funkcí můžou být povolené nebo zakázané. Stav příznaku lze podmínit pomocí filtrů vlastností.

Filtry funkcí

Filtry funkcí definují scénář, kdy má být funkce povolená. Pokud chcete vyhodnotit stav funkce, seznam filtrů funkcí se prochází, dokud některý z filtrů nesdělí, že je tato funkce povolená. V tomto okamžiku se procházení filtry funkcí zastaví. Pokud žádný filtr funkcí indikuje, že by měla být tato funkce povolená, považuje se za zakázanou.

Předpokládejme například, že navrhujete filtr funkcí prohlížeče Microsoft Edge. Pokud požadavek HTTP pochází z Microsoft Edge, filtr funkcí aktivuje všechny funkce, ke které je připojený.

Konfigurace přepínače funkcí

Konfigurační systém .NET Core slouží k určení stavu příznaků funkcí. Základem tohoto systému je IConfiguration rozhraní. Jako zprostředkovatele stavu funkce pro knihovnu příznaků funkcí je možné použít libovolného zprostředkovatele IConfiguration . Tento systém podporuje scénáře od konfiguračního souboruappsettings.json až po Azure App Configuration.

Deklarace příznaku funkce

Knihovna pro správu funkcí podporuje konfigurační souborappsettings.json jako zdroj příznaků funkce, protože se jedná o zprostředkovatele pro systém .NET Core IConfiguration . Příznaky funkce jsou deklarovány pomocí .Microsoft Feature Management schema Toto schéma je nezávislé na původu a podporuje se ve všech knihovnách pro správu funkcí Microsoftu.

Kód v následujícím příkladu deklaruje příznaky funkcí v souboru JSON:

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

Část feature_management dokumentu JSON se používá podle konvence k načtení nastavení funkčních příznaků. Je nutné vypsat objekty příznaků funkce v feature_flags poli v této části. Tento kód obsahuje tři příznaky funkcí. Každý objekt příznaku funkce má vlastnost id a enabled.

Hodnota id je název, který používáte k identifikaci a odkaz na příznak funkce.
Vlastnost enabled určuje povolený stav příznaku funkce.

Funkce je vypnutá, pokud enabled je false. Pokud enabled je true, stav funkce závisí na conditions vlastnosti. Vlastnost conditions deklaruje podmínky, které se používají k dynamickému povolení funkce.

Pokud příznak funkce nemá conditions vlastnost, je tato funkce zapnutá.
Pokud má příznak conditions funkce vlastnost a její podmínky jsou splněny, je tato funkce zapnutá.
Pokud má feature flag conditions vlastnost, ale jeho podmínky nejsou splněné, je funkce vypnutá.

Filtry funkcí jsou definovány v client_filters poli. V předchozím kódu má přepínač funkce FeatureV filtr s názvem Microsoft.TimeWindow. Tento filtr je příkladem konfigurovatelného filtru funkcí. V tomto kódu má parameters tento filtr vlastnost. Tato vlastnost slouží ke konfiguraci filtru. V tomto případě se konfigurují počáteční a koncové časy aktivní funkce.

Pokročilý: Znak dvojtečky (:) je zakázán v názvech příznaků funkce.

Typ požadavku

V rámci conditions vlastnosti se vlastnost používá k určení, requirement_type zda filtry mají použít Any nebo All logiku při vyhodnocování stavu funkce. Pokud requirement_type není zadána, výchozí hodnota je Any. Výsledkem requirement_type hodnot je následující chování:

Any: Aby byla funkce povolena, stačí, aby byl vyhodnocen jenom jeden filtr na hodnotu true.
All: Každý filtr se musí vyhodnotit na true, aby byla funkce povolena.

requirement_type All mění způsob procházení filtrů:

Pokud nejsou uvedené žádné filtry, je tato funkce zakázaná.
Pokud jsou filtry uvedené, budou procházeny, dokud podmínky jednoho z nich nezadají, že by měla být funkce zakázaná. Pokud žádný filtr neukazuje, že by funkce měla být zakázaná, považuje se za povolenou.

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

V tomto příkladu má příznak funkce FeatureW hodnotu All. V důsledku toho se všechny jeho filtry musí vyhodnotit jako true, aby byla funkce povolená. V tomto případě je tato funkce povolená pro 50 procent uživatelů během zadaného časového intervalu.

Zpracování více zdrojů konfigurace

Od verze 4.3.0 se můžete rozhodnout pro vlastní slučování příznaků funkcí schématu Microsoftu (oddíl).feature_management Pokud se stejné ID příznaku funkce zobrazí ve více zdrojích konfigurace, instance předdefinované ConfigurationFeatureDefinitionProvider třídy tyto definice sloučí podle pořadí registrace poskytovatele konfigurace. Při konfliktu se použije poslední definice feature flag. Toto chování se liší od výchozího sloučení založeného na indexech pole v .NET.

Následující kód umožňuje sloučení konfigurace feature flagu prostřednictvím injektování závislostí:

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

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

Vlastní slučování můžete také povolit při vytváření instance ConfigurationFeatureDefinitionProvider:

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

Příklad chování:

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

Když povolíte vlastní slučování, FeatureA zůstane povoleno a FeatureB se nastaví na povoleno, protože se použije poslední deklarace. Pokud použijete výchozí slučování .NET, kde je vlastní slučování zakázané, pole se sloučí podle indexu. Tento přístup může přinést neočekávané výsledky, pokud zdroje nejsou zarovnané podle pozice.

Schéma správy funkcí .NET

V předchozích verzích knihovny pro správu funkcí byla primárním schématem schéma správy funkcí .NET.

Počínaje verzí 4.0.0 knihovny nejsou ve schématu správy funkcí .NET podporované nové funkce, včetně variant a telemetrie.

Poznámka:

Pokud konfigurace příznaku funkce obsahuje deklaraci, která je uvedena jak v oddíle feature_management, tak v oddíle FeatureManagement, přijme se ta z oddílu feature_management.

Spotřeba

V základní implementaci správa funkcí kontroluje, jestli je povolený příznak funkce. Pak provede akce na základě výsledku. Tato kontrola se provádí metodou IsEnabledAsyncIVariantFeatureManager.

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

Registrace služby

Správa funkcí spoléhá na injektáž závislostí .NET Core. Jak ukazuje následující kód, můžete k registraci služeb správy funkcí použít standardní konvence:

using Microsoft.FeatureManagement;

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

Ve výchozím nastavení správce funkcí načte konfiguraci příznaku funkce z části feature_management nebo FeatureManagement konfiguračních dat .NET Core. Pokud žádný oddíl neexistuje, konfigurace se považuje za prázdnou.

Poznámka:

Můžete také určit, že konfigurace příznaku funkce by se měla načíst z jiné konfigurační sekce předáním této sekce do AddFeatureManagement. Následující příklad určuje, že správce funkcí by měl číst z oddílu nazývaného MyFeatureFlags místo toho:

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

Injekce závislostí

Pokud používáte knihovnu pro správu funkcí s MVC, můžete získat objekt, který implementuje IVariantFeatureManager pomocí injektáže závislostí.

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

Služby správy funkcí s vymezeným oborem

Metoda AddFeatureManagement přidá služby správy funkcí jako singletony v rámci aplikace. Některé scénáře vyžadují přidání služeb správy funkcí jako služby s vymezeným oborem. Můžete například chtít použít filtry funkcí, které využívají vymezené služby pro kontextové informace. V tomto případě byste měli použít metodu AddScopedFeatureManagement . Tato metoda zajišťuje, že služby správy funkcí, včetně filtrů funkcí, se přidají jako služby s vymezeným oborem.

services.AddScopedFeatureManagement();

integrace ASP.NET Core

Knihovna pro správu funkcí poskytuje funkce v ASP.NET Core a MVC, které umožňují ve webových aplikacích běžné scénáře příznaků funkcí. Tyto funkce jsou k dispozici odkazem na balíček NuGet Microsoft.FeatureManagement.AspNetCore .

Kontrolery a akce

Kontroler MVC a akce můžou vyžadovat, aby byla daná funkce nebo některý ze seznamů funkcí povolený, aby bylo možné spustit. Tento požadavek můžete splnit pomocí objektu FeatureGateAttribute . Třída FeatureGateAttribute je definována v oboru názvů Microsoft.FeatureManagement.Mvc.

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

V předchozím příkladu je třída HomeController řízena pomocí FeatureX. HomeController Akce se můžou spouštět jenom v případě, že FeatureX je tato funkce povolená.

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

V předchozím příkladu Index se akce MVC může spustit jenom v případě, že FeatureX je tato funkce povolená.

Deaktivované zpracování akcí

Pokud je kontroler MVC nebo akce blokovány, protože nejsou povoleny žádné funkce, které určuje, je vyvolána registrovaná implementace IDisabledFeaturesHandler . Ve výchozím nastavení je zaregistrovaná minimalická obslužná rutina, která vrací chybu HTTP 404. Tuto obslužnou rutinu můžete přepsat pomocí IFeatureManagementBuilder při registraci příznaků funkcí.

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

Zobrazení

V zobrazeních MVC můžete použít <feature> značky k podmíněnému vykreslení obsahu. Podmínky vykreslování můžete založit na tom, zda je funkce povolená nebo zda je přiřazena konkrétní varianta funkce. Další informace naleznete v tématu Varianty, dále v tomto článku.

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

Pokud chcete zobrazit obsah při zakázání funkce nebo sady funkcí, můžete také negovat tag helper. Pokud zadáte negate="true", jako v následujících příkladech, obsah se vykreslí pouze v případě, že FeatureX je zakázaný.

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

Značku můžete použít <feature> k odkazování na více funkcí. Uděláte to tak, že zadáte čárkami oddělený seznam funkcí v atributu name .

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

Ve výchozím nastavení musí být všechny uvedené funkce povolené, aby se značka funkce vykreslovala. Toto chování můžete přepsat přidáním atributu requirement , jak ukazuje následující příklad.

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

Značku můžete použít <feature> také k odkazování na více variant. Uděláte to tak, že použijete requirement hodnotu Any a zadáte seznam variant oddělených čárkami v atributu variant .

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

Poznámka:

Pokud zadáte variantu, měli byste zadat pouze jednu funkci.
Pokud zadáte více variant a použijete requirement hodnotu And, vyvolá se chyba. Nemůžete přiřadit více variant.

Značka <feature> vyžaduje, aby fungoval pomocník značky. Pokud chcete tuto značku použít, přidejte pomocníka pro značku řízení funkcí do souboru _ViewImports.cshtml.

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

Filtry MVC

Můžete nastavit filtry akcí MVC, které použijete podmíněně na základě stavu funkce. Pokud chcete tyto filtry nastavit, zaregistrujte je způsobem s podporou funkcí. Kanál správy funkcí podporuje asynchronní filtry akcí MVC, které implementují IAsyncActionFilter rozhraní.

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

Předchozí kód zaregistruje filtr MVC s názvem SomeMvcFilter. Tento filtr se aktivuje jenom v rámci kanálu MVC, pokud FeatureX je povolený.

Razor Pages

MVC Razor Pages může vyžadovat povolení dané funkce nebo některého ze seznamu funkcí, aby bylo možné spustit. Tento požadavek můžete přidat pomocí objektu FeatureGateAttribute . Třída FeatureGateAttribute je definována v oboru názvů Microsoft.FeatureManagement.Mvc.

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

Předchozí kód nastaví stránku Razor Page, která vyžaduje povolení FeatureX . Pokud funkce není povolená, stránka vygeneruje výsledek HTTP 404 (Nenalezeno).

Pokud používáte FeatureGateAttribute objekt na stránkách Razor Pages, musíte umístit FeatureGateAttribute na typ obslužné rutiny stránky. Nemůžete ho aplikovat na jednotlivé metody obsluhy.

Vytváření aplikací

Knihovnu pro správu funkcí můžete použít k přidání větví aplikací a middlewaru, které se spouští podmíněně na základě stavu funkce.

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

V předchozím kódu aplikace přidá komponentu middlewaru, která se zobrazí v kanálu požadavku pouze v případě, že je tato funkce povolena. Pokud je funkce povolená nebo zakázaná během běhu, je možné kanál middlewaru dynamicky změnit.

Jak ukazuje následující kód, tato funkce vychází z obecnější schopnosti větvení celé aplikace na základě funkce.

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

Implementace filtru funkcí

Vytvoření filtru funkcí poskytuje způsob, jak povolit funkce na základě kritérií, která definujete. Pokud chcete implementovat filtr funkcí, musíte implementovat IFeatureFilter rozhraní. IFeatureFilter má jednu metodu s názvem EvaluateAsync. Když funkce určuje, že je možné ji povolit pro filtr funkcí, EvaluateAsync volá se metoda. Pokud se EvaluateAsync vrátí true, funkce by měla být povolena.

Následující kód ukazuje, jak přidat přizpůsobený filtr funkcí volaný MyCriteriaFilter.

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

Filtr funkcí můžete zaregistrovat tak, že zavoláte AddFeatureFilter<T> na implementaci IFeatureManagementBuilder , kterou vrátí AddFeatureManagement. Filtr funkcí má přístup ke službám v kolekci služeb, které používáte k přidání příznaků funkcí. Tyto služby můžete použít pomocí injektování závislostí.

Poznámka:

Když odkazujete na filtry v nastavení příznaku funkce (například appsettings.json), měli byste část názvu typu vynechat Filter . Další informace najdete v tématu Atribut aliasu filtru, dále v tomto článku.

Parametrizované filtry funkcí

Některé filtry funkcí vyžadují parametry k vyhodnocení, jestli má být funkce zapnutá. Filtr funkcí prohlížeče může například zapnout funkci pro určitou sadu prohlížečů. Funkci můžete zapnout v prohlížečích Microsoft Edge a Chrome, ale ne ve Firefoxu.

Pokud chcete toto filtrování implementovat, můžete navrhnout filtr funkcí tak, aby očekával parametry. Tyto parametry zadáte v konfiguraci funkce. V kódu k nim přistupujete prostřednictvím parametru 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; }
}

Třída FeatureFilterEvaluationContext má vlastnost s názvem Parameters. Parametry této vlastnosti představují nezpracovanou konfiguraci, kterou může filtr funkcí použít při vyhodnocování, zda má být tato funkce povolena. V příkladu filtru funkcí prohlížeče může filtr použít Parameters vlastnost k extrahování sady povolených prohlížečů určených pro tuto funkci. Filtr pak může zkontrolovat, jestli požadavek pochází z některého z těchto prohlížečů.

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

Atribut aliasu filtru

Když zaregistrujete filtr vlastností pro funkční příznak, alias používaný v konfiguraci je název typu filtru vlastností s odstraněnou příponou Filter, pokud existuje. Měli byste například odkazovat na MyCriteriaFilter jako MyCriteria v konfiguraci.

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

Tento název můžete přepsat použitím třídy FilterAliasAttribute. Pokud chcete deklarovat název, který se má použít v konfiguraci pro odkazování na filtr funkcí v rámci příznaku funkce, můžete filtr funkcí vyzdobit tímto atributem.

Chybějící filtry funkcí

Předpokládejme, že nakonfigurujete funkci tak, aby byla povolena pro konkrétní filtr funkcí. Pokud tento filtr funkcí není zaregistrovaný, při vyhodnocení funkce se vyvolá výjimka. Jak ukazuje následující kód, můžete výjimku zakázat pomocí možností správy funkcí.

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

Použití httpContextu

Filtry funkcí můžou vyhodnotit, jestli má být funkce povolená, na základě vlastností požadavku HTTP. Tato kontrola se provádí kontrolou kontextu HTTP. Jak ukazuje následující kód, filtr funkcí může získat odkaz na kontext HTTP pomocí injektáže závislostí k získání implementace IHttpContextAccessor.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

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

Aby byla k dispozici, musíte do kontejneru injektáže závislostí přidat IHttpContextAccessor implementaci při spuštění. K registraci implementace ve službách můžete použít následující metodu IServiceCollection .

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

Pokročilý:IHttpContextAccessor a HttpContext neměli byste je používat v komponentách Razor aplikací Blazor na straně serveru. Doporučeným přístupem pro předávání kontextu HTTP v aplikacích Blazor je zkopírování dat do vymezené služby. V případě aplikací Blazor byste měli použít AddScopedFeatureManagement k registraci služeb správy funkcí. Další informace najdete v tématu Služby správy funkcí s vymezeným oborem výše v tomto článku.

Poskytnutí kontextu pro vyhodnocení funkcí

V konzolových aplikacích neexistuje žádný kontext prostředí, jako je HttpContext, který by mohly funkce filtrů použít ke kontrole, zda by měla být funkce zapnuta. V tomto případě musí aplikace poskytnout objekt, který představuje kontext systému správy funkcí pro použití filtry funkcí. Tento kontext můžete poskytnout pomocí IVariantFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext). Pokud chcete vyhodnotit stav funkce, filtry funkcí můžou použít appContext objekt, který zadáte správci funkcí.

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

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

Filtry kontextových funkcí

Kontextové filtry funkcí implementují IContextualFeatureFilter<TContext> rozhraní. Tyto filtry speciálních funkcí můžou využít kontext, který se předává při volání IVariantFeatureManager.IsEnabledAsync<TContext>. Parameter typu TContext v IContextualFeatureFilter<TContext> popisuje typ kontextu, který může filtr zpracovat. Při vývoji filtru kontextových funkcí můžete stanovit požadavky na použití filtru zadáním typu kontextu.

Vzhledem k tomu, že každý typ je potomkem třídy Object, lze volat filtr, který implementuje IContextualFeatureFilter<object> v jakémkoli zadaném kontextu. Následující kód poskytuje příklad konkrétního kontextového filtru funkcí. V tomto kódu je funkce povolená, pokud je účet v nakonfigurovaného seznamu povolených účtů.

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

Třída AccountIdFilter vyžaduje objekt, který implementuje IAccountContext , aby bylo možné vyhodnotit stav funkce. Při použití filtru této funkce musí volající zajistit, aby předaný objekt implementoval IAccountContext.

Poznámka:

Jediným typem je možné implementovat pouze jedno rozhraní filtru funkcí. Při pokusu o přidání filtru funkcí, který implementuje více než jedno rozhraní filtru funkcí, dojde k výjimce ArgumentException .

Použití kontextových a nekonkonaktivních filtrů se stejným aliasem

Filtry, které implementují IFeatureFilter a IContextualFeatureFilter můžou sdílet stejný alias. Konkrétně můžete mít jeden alias filtru sdílený nulou nebo jednou IFeatureFilter implementací a nula nebo NIContextualFeatureFilter<ContextType> implementace, pokud existuje maximálně jeden použitelný filtr pro ContextType.

Pokud chcete porozumět procesu výběru filtru, pokud jsou v aplikaci zaregistrovány kontextové a nerelační filtry se stejným názvem, zvažte následující příklad.

Tři filtry sdílí alias SharedFilterName.

Nekontextový filtr s názvem FilterA
Kontextový filtr nazvaný FilterB, který přijímá TypeB kontext
Kontextový filtr FilterC, který přijímá kontext TypeC.

Funkční příznak nazvaný MyFeature používá filtr funkcí SharedFilterName ve své konfiguraci.

Pokud jsou zaregistrované všechny tři filtry:

Při volání IsEnabledAsync("MyFeature") se filtr FilterA použije k vyhodnocení příznaku funkce.
Při volání IsEnabledAsync("MyFeature", context):
- Pokud je typ contextTypeB, je použit FilterB.
- Pokud je context typ TypeC, FilterC je použit.
- Pokud je typ contextTypeF, použije se FilterA.

Předdefinované filtry funkcí

Balíček Microsoft.FeatureManagement obsahuje několik funkcí filtrů: PercentageFilter, TimeWindowFilter, ContextualTargetingFilter, a TargetingFilter. Všechny filtry s výjimkou TargetingFilter se při registraci správy funkcí přidají AddFeatureManagement. TargetingFilter se přidá pomocí WithTargeting metody. Další informace najdete v tématu Cílení dále v tomto článku.

Každý z předdefinovaných filtrů funkcí má vlastní parametry. Následující části popisují tyto filtry funkcí a poskytují příklady.

Microsoft.Percentage

Filtr Microsoft.Percentage poskytuje způsob, jak povolit funkci na základě nastaveného procenta.

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

Microsoft.TimeWindow

Filtr Microsoft.TimeWindow poskytuje způsob, jak povolit funkci na základě časového intervalu.

Pokud zadáte pouze End hodnotu, funkce se do té doby považuje za zapnutou.
Pokud zadáte pouze hodnotu Start, vlastnost se považuje za zapnutou ve všech bodech od tohoto okamžiku.

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

Filtr můžete nakonfigurovat tak, aby se opakovaně použil časový interval. Tato funkce může být užitečná, když potřebujete zapnout funkci během období s nízkým provozem nebo obdobím vysokého provozu v průběhu dne nebo určitého dne v týdnu. Chcete-li rozbalit jednotlivé časové okno na opakující se časové okno, použijte Recurrence parametr k zadání pravidla opakování.

Poznámka:

Chcete-li použít opakování, je nutné zadat Start a End hodnoty. Při opakování nezadává část End hodnoty koncové datum pro zvážení aktivního filtru. Místo toho filtr používá koncové datum vzhledem k počátečnímu datu k definování doby trvání časového intervalu, který se opakuje.

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

Nastavení Recurrence se skládá ze dvou částí:

Nastavení Pattern určují, jak často se časové intervaly opakují.
Nastavení Range určuje, jak dlouho se vzorec opakování opakuje.

Opakování

Existují dva možné typy opakování: Daily a Weekly. Například časové okno se může opakovat každý den, každé tři dny, každé pondělí nebo každý druhý pátek.

V závislosti na typu jsou určitá pole Pattern nastavení povinná, volitelná nebo ignorováná.

Daily

Způsob denního opakování způsobí opakování časového intervalu na základě zadaného počtu dní mezi každým výskytem.

Vlastnost	Relevance	Popis
`Type`	Požaduje se	Typ způsobu opakování. Musí být nastavena na `Daily`hodnotu .
`Interval`	Volitelné	Počet dní mezi každým výskytem. Výchozí hodnota je `1`.

Weekly

Způsob týdenního opakování způsobí opakování časového intervalu ve stejném dni nebo dnech v týdnu. Můžete ale zadat počet týdnů mezi jednotlivými sadami výskytů.

Vlastnost	Relevance	Popis
`Type`	Požaduje se	Typ způsobu opakování. Musí být nastavena na `Weekly`hodnotu .
`DaysOfWeek`	Požaduje se	Dny v týdnu, na které se událost vyskytuje.
`Interval`	Volitelné	Počet týdnů mezi každou sadou výskytů. Výchozí hodnota je `1`.
`FirstDayOfWeek`	Volitelné	Den, který se použije jako první den v týdnu. Výchozí hodnota je `Sunday`.

Následující příklad opakuje časové okno každé druhé pondělí a úterý:

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

Poznámka:

Hodnota Start musí být platným prvním výskytem, který odpovídá vzoru opakování. Doba trvání časového intervalu také nemůže být delší, než jak často k němu dochází. Například 25hodinový časový interval se nemůže opakovat každý den.

Rozsah opakování

Existují tři možné typy rozsahu opakování: NoEnd, EndDatea Numbered.

NoEnd

Rozsah NoEnd způsobí, že opakování proběhne neomezeně dlouho.

Vlastnost Relevance Popis

Type Požaduje se Typ rozsahu opakování. Musí být nastavena na NoEndhodnotu .

Vlastnost	Relevance	Popis
`Type`	Požaduje se	Typ rozsahu opakování. Musí být nastavena na `NoEnd`hodnotu .

EndDate

Rozsah EndDate způsobí, že časový interval nastane ve všech dnech, které odpovídají příslušnému vzoru do koncového data.

Vlastnost	Relevance	Popis
`Type`	Požaduje se	Typ rozsahu opakování. Musí být nastavena na `EndDate`hodnotu .
`EndDate`	Požaduje se	Datum a čas, kdy se má vzor přestat používat. Pokud počáteční čas posledního výskytu spadá před koncové datum, může koncový čas tohoto výskytu přesahovat toto datum.

V následujícím příkladu se časové okno opakuje každý den až do posledního výskytu 1. dubna 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

Rozsah Numbered způsobí, že časové okno nastane zadaný početkrát.

Vlastnost Relevance Popis

Type Požaduje se Typ rozsahu opakování. Musí být nastavena na Numberedhodnotu .

NumberOfOccurrences Požaduje se Počet výskytů.

V následujícím příkladu se časové okno opakuje v pondělí a úterý pro celkem tři výskyty, ke kterým dochází v následujících datech:
- Pondělí, duben 1
- Úterý, duben 2
- Pondělí, duben 8
```
"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
    }
}
```

Vlastnost	Relevance	Popis
`Type`	Požaduje se	Typ rozsahu opakování. Musí být nastavena na `Numbered`hodnotu .
`NumberOfOccurrences`	Požaduje se	Počet výskytů.

Pokud chcete vytvořit pravidlo opakování, musíte zadat nastavení Pattern i Range. Jakýkoli typ vzoru může pracovat s libovolným typem rozsahu.

Upřesnit: Posun časového pásma Start vlastnosti se použije na nastavení opakování.

Microsoft.Targeting

Filtr Microsoft.Targeting poskytuje způsob, jak povolit funkci pro cílovou skupinu. Podrobné vysvětlení cílení najdete v části Cílení dále v tomto článku.

Parametry filtru zahrnují Audience objekt, který popisuje, kdo má k této funkci přístup. V rámci objektu Audience můžete zadat uživatele, skupiny, vyloučené uživatele a skupiny a výchozí procento uživatelské základny.

Pro každý objekt skupiny, který v oddílu vypíšete Groups , musíte také určit, jaké procento členů skupiny by mělo mít přístup.

Pro každého uživatele se funkce vyhodnotí následujícím způsobem:

Pokud je uživatel vyloučený, funkce je pro uživatele zakázaná. Uživatele můžete vyloučit:
- Zadejte jejich jméno v UsersExclusion části.
- Vypsání skupiny, do které Groups patří, v sekci Exclusion.
Pokud uživatel není vyloučený, je tato funkce povolená, pokud jsou splněny některé z následujících podmínek:
- Uživatel je uvedený v Users části.
- Uživatel se nachází v zahrnutém procentu některé ze skupinových nasazení.
- Uživatel spadá do výchozího procenta rozložení.
Pokud se žádný z předchozích případů nepoužije, funkce je pro uživatele zakázaná. Pokud například uživatel není v zahrnuté procentuální hodnotě, funkce je zakázaná.

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

Obory názvů aliasů filtru funkcí

Všechny předdefinované aliasy filtru funkcí jsou v Microsoft oboru názvů filtru funkcí. Být v tomto oboru názvů zabraňuje konfliktům s jinými filtry funkcí, které sdílejí stejný alias. Segmenty oboru názvů filtru funkcí jsou rozděleny znakem .. Funkční filtr můžete odkazovat podle jeho plně kvalifikovaného aliasu, například Microsoft.Percentage. Nebo můžete odkazovat na poslední segment, například Percentage.

Cílení

Cílení je strategie správy funkcí, kterou můžete použít k postupnému zavedení nových funkcí do uživatelské základny. Strategie je založená na konceptu cílení na skupinu uživatelů, kteří se označují jako cílová skupina. Cílová skupina se skládá z konkrétních uživatelů, skupin, vyloučených uživatelů a skupin a určeného procenta celé uživatelské základny. Skupiny, které jsou součástí cílové skupiny, je možné dále rozdělit do procent jejich celkových členů.

Následující kroky ukazují příklad postupného zavedení nové funkce s názvem Beta:

Jednotlivým uživatelům Jeff a Alicia je udělen přístup k funkci Beta.
Jiný uživatel, Mark, žádá, aby se přihlásil a je zahrnutý.
Dvacet procent uživatelů ve skupině Ring1 je součástí funkce Beta.
Počet uživatelů zahrnutých do skupiny Ring1 se zvýší na 100 procent.
Součástí funkce Beta je pět procent uživatelské základny.
Procento zavedení bylo zvýšeno na 100 procent, aby byla funkce zcela zavedena.

Knihovna podporuje tuto strategii pro nasazení funkce prostřednictvím integrovaného filtru funkcí Microsoft.Targeting.

Cílení ve webové aplikaci

Příklad webové aplikace, která používá filtr funkcí cílení, naleznete v ukázkovém projektu FeatureFlagDemo .

Pokud chcete v aplikaci začít používat TargetingFilter , musíte ji přidat do kolekce služeb aplikace stejně jako jakýkoli jiný filtr funkcí. Na rozdíl od jiných předdefinovaných filtrů TargetingFilter spoléhá na přidání jiné služby do kolekce služeb aplikace. Tato služba je implementace ITargetingContextAccessor.

Knihovna Microsoft.FeatureManagement.AspNetCore poskytuje výchozí implementaciITargetingContextAccessor, která extrahuje cílené informace z hodnoty požadavkuHttpContext. Při nastavování cílení můžete použít výchozí přístupový objekt kontextu cílení pomocí negenerického WithTargeting přetíženíIFeatureManagementBuilder.

Chcete-li zaregistrovat výchozí přístupový objekt kontextu cílení a TargetingFilter, volejte WithTargeting na IFeatureManagementBuilder.

services.AddFeatureManagement()
        .WithTargeting();

Můžete také zaregistrovat přizpůsobenou implementaci pro ITargetingContextAccessor a TargetingFilter voláním WithTargeting<T>. Následující kód nastaví správu funkcí ve webové aplikaci tak, aby používal TargetingFilter s implementací nazvanou ITargetingContextAccessorExampleTargetingContextAccessor.

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

ITargetingContextAccessor

K použití TargetingFilter ve webové aplikaci se vyžaduje implementace ITargetingContextAccessor . Důvodem tohoto požadavku je, že pro cílení na vyhodnocení se vyžadují kontextové informace, jako jsou například informace o uživateli. Tyto informace jsou uloženy v instancích TargetingContext třídy. Různé aplikace extrahují tyto informace z různých míst, jako je kontext HTTP požadavku nebo databáze.

Příklad, který extrahuje informace o kontextu cílení z kontextu HTTP aplikace, najdete DefaultHttpTargetingContextAccessor v Microsoft.FeatureManagement.AspNetCore balíčku. Extrahuje následující informace:

Cílení informací z vlastnosti HttpContext.User
UserId informace z Identity.Name pole
Groups informace z deklarací typu Role

Tato implementace spoléhá na použití IHttpContextAccessor. Další informace o IHttpContextAccessor použití HttpContext, dříve v tomto článku.

Cílení v konzolové aplikaci

Filtr cílení spoléhá na kontext cílení a vyhodnocuje, jestli má být funkce zapnutá. Tento kontext cílení obsahuje informace, jako je uživatel, který se vyhodnocuje, a skupiny, ke kterým uživatel patří. V konzolových aplikacích není obvykle k dispozici žádný kontext okolí pro předávání těchto informací do filtru cílení. V důsledku toho jej musíte předat přímo při volání FeatureManager.IsEnabledAsync. Tento typ kontextu je podporován pomocí .ContextualTargetingFilter Aplikace, které potřebují odeslat kontext cílení správci funkcí, by měly používat ContextualTargetingFilter místo TargetingFilter.

Vzhledem k tomu, že ContextualTargetingFilter implementuje IContextualTargetingFilter<ITargetingContext>, musíte předat implementaci ITargetingContext do IVariantFeatureManager.IsEnabledAsync, aby byla schopna vyhodnotit a zapnout funkci.

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 používá alias Microsoft.Targetingfiltru funkcí , takže konfigurace tohoto filtru je konzistentní s informacemi v Microsoft.Targeting, dříve v tomto článku.

Příklad, který se používá ContextualTargetingFilter v konzolové aplikaci, najdete v ukázkovém projektu TargetingConsoleApp .

Možnosti vyhodnocení cílení

Možnosti jsou k dispozici pro přizpůsobení způsobu, jakým se hodnocení cílení provádí napříč všemi funkcemi. Tyto možnosti můžete nakonfigurovat při nastavování správy funkcí.

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

Vyloučení z cílení

Když definujete cílovou skupinu, můžete z cílové skupiny vyloučit uživatele a skupiny. Tato funkce je užitečná při zavádění funkce skupině uživatelů, ale musíte vyloučit několik uživatelů nebo skupin ze zavádění. Pokud chcete určit uživatele a skupiny, které chcete vyloučit, použijte Exclusion vlastnost cílové skupiny.

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

Předchozí kód umožňuje funkci pro uživatele pojmenované Jeff a Alicia. Tato funkce je také povolena pro uživatele ve skupině s názvem Ring0. Funkce je však pro uživatele s názvem Markzakázaná, i když je daný uživatel ve skupině Ring0 . Vyloučení mají přednost před zbytkem filtru cílení.

Varianty

Když do aplikace přidáte novou funkci, má tato funkce několik navrhovaných možností návrhu. Testování A/B poskytuje společné řešení pro rozhodování o návrhu. Testování A/B zahrnuje poskytnutí jiné verze funkce pro různé segmenty uživatelské základny a následnou volbu verze na základě interakce uživatele. V knihovně pro správu funkcí .NET můžete implementovat testování A/B pomocí variant, které představují různé konfigurace funkce.

Varianty poskytují způsob, jak udělat z příznaku funkce více než pouhý základní příznak zapnuto/vypnuto. Varianta představuje hodnotu příznaku funkce, který může být řetězec, číslo, logická hodnota nebo dokonce objekt konfigurace. Příznak funkce, který deklaruje varianty, by měl definovat okolnosti, za kterých se má každá varianta použít. Další informace naleznete v tématu Přidělení variant, dále v tomto článku.

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

Načtení variant

Pro načtení varianty pro každou funkci můžete použít metodu GetVariantAsync rozhraní IVariantFeatureManager.

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

IConfigurationSection variantConfiguration = variant.Configuration;

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

Po načtení varianty můžete její konfiguraci použít přímo jako implementaci IConfigurationSection z vlastnosti varianty Configuration . Další možností je svázat konfiguraci s objektem pomocí vzoru vazby konfigurace .NET.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

Vrácená varianta závisí na uživateli, který se vyhodnocuje. Informace o uživateli můžete získat z instance TargetingContext. Tento kontext můžete předat při volání GetVariantAsync. Nebo může být automaticky načtena z implementace ITargetingContextAccessor, pokud je tato zaregistrována.

Deklarace funkčního příznaku varianty

Ve srovnání se standardními příznaky funkcí mají příznaky varianty dvě další vlastnosti: variants a allocation. Vlastnost variants je pole, které obsahuje varianty definované pro funkci. Vlastnost allocation definuje, jak mají být tyto varianty přiděleny pro tuto funkci. Stejně jako deklarování standardních příznaků funkcí můžete v souboru JSON nastavit příznaky variant funkcí. Následující kód je příkladem příznaku variantní funkce:

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

Definování variant

Každá varianta má dvě vlastnosti: název a konfiguraci. Název se používá k odkazování na konkrétní variantu a konfigurace je hodnota této varianty. Pomocí vlastnosti configuration_value můžete zadat konfiguraci. Vlastnost configuration_value je vložená konfigurace, která může být řetězec, číslo, logická hodnota nebo objekt konfigurace. Pokud nenakonfigurujete vlastnost configuration_value, je vlastnost Configuration vrácené varianty null.

Pokud chcete zadat všechny možné varianty pro vlastnost, uvedete je pod variants vlastností.

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

Přidělit varianty

Pokud chcete přidělit varianty funkce, použijte allocation vlastnost funkce.

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

Nastavení allocation má následující vlastnosti:

Vlastnost	Popis
`default_when_disabled`	Varianta, která se má použít, když je požadována varianta, zatímco je tato funkce považována za zakázanou.
`default_when_enabled`	Varianta, která se má použít, když je požadována varianta, zatímco je tato funkce považována za povolenou a uživateli se nepřiřazuje žádná jiná varianta.
`user`	Varianta a seznam uživatelů, kteří mají přiřadit variantu.
`group`	Varianta a seznam skupin. Varianta se přiřadí, pokud je aktuální uživatel alespoň v jedné ze skupin.
`percentile`	Varianta a procentuální rozsah, do kterého musí být přiřazena počítaná procentuální hodnota uživatele.
`seed`	Hodnota, na které jsou výpočty procenta pro `percentile` založeny. Procento výpočtu pro konkrétního uživatele je stejné ve všech funkcích, pokud se použije stejná `seed` hodnota. Pokud není zadána žádná `seed` hodnota, vytvoří se výchozí počáteční hodnota na základě názvu funkce.

Pokud funkce není povolena, správce funkcí přiřadí aktuálnímu uživateli variantu zadanou pro default_when_disabled. V předchozím příkladu se tato funkce nazývá Small.

Pokud je tato funkce povolená, správce funkcí zkontroluje přidělení user, group, a percentile ve zmíněném pořadí, aby přiřadil variantu. V předchozím příkladu je zadaná varianta Bigpřiřazena uživateli v následujících případech:

Uživatel, který se vyhodnocuje, má název Marsha.
Uživatel je ve skupině Ring1 .
Uživatel se náhodou nachází mezi nulovým a desátým percentilem.

Pokud se žádné z těchto přidělení neshoduje, uživateli je přiřazena varianta default_when_enabled. V příkladu je tato varianta Small.

Logika přidělení je podobná logice, kterou používáte pro filtr funkcí Microsoft.Targeting . Existují ale některé parametry, které se nacházejí v cílení, ale nikoliv při přidělení, a naopak. Výsledky cílení a přidělování nesouvisí.

Poznámka:

Pokud chcete přidělit varianty funkcí, musíte zaregistrovat ITargetingContextAccessor voláním metody WithTargeting<T>.

Přepsání povoleného stavu pomocí varianty

Varianty můžete použít k přepsání povoleného stavu příznaku funkce. Pokud využijete tuto funkci, můžete rozšířit vyhodnocení příznaku funkčnosti. Během volání IsEnabledAsync příznaku s variantami správce funkcí zkontroluje, jestli je varianta přiřazená aktuálnímu uživateli nakonfigurovaná tak, aby přepsala výsledek.

Přepsání můžete implementovat s použitím volitelné vlastnosti varianty status_override. Tato vlastnost může mít následující hodnoty:

None: Varianta nemá vliv na to, jestli je příznak považován za povolený nebo zakázaný. None je výchozí hodnota.
Enabled: Při výběru varianty se příznak funkce vyhodnotí jako povolený.
Disabled: Při výběru varianty se příznak funkce vyhodnotí jako zakázaný.

Funkci nelze přepsat, pokud má stav enabledfalse.

Pokud použijete příznak funkce s binárními variantami, status_override může být tato vlastnost užitečná. Můžete dál používat rozhraní API, jako jsou IsEnabledAsync a FeatureGateAttribute ve své aplikaci. Můžete ale také využít funkce, které jsou součástí variant, jako je například přidělení percentilu a použití počáteční hodnoty pro procentuální výpočty.

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

V předchozím příkladu je funkce vždy povolená. Pokud je aktuální uživatel v počítaném rozsahu percentilu 10 až 20, vrátí se varianta On . V opačném případě je vrácena varianta Off, a protože hodnota status_override je Disabled, funkce je považována za zakázanou.

Varianty injektáže závislostí

Příznaky variantní funkce můžete použít společně s injektáží závislostí k zveřejnění různých implementací služby různým uživatelům. Rozhraní IVariantServiceProvider<TService> poskytuje způsob, jak tuto kombinaci dosáhnout.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken);

V předchozím kódu implementace IVariantServiceProvider<IAlgorithm> načte z kontejneru pro správu závislostí implementaci IAlgorithm. Zvolená implementace závisí na:

Funkční příznak, s nímž je služba IAlgorithm zaregistrována.
Přidělená varianta pro tuto funkci.

Implementace IVariantServiceProvider<T> je zpřístupněna aplikaci voláním IFeatureManagementBuilder.WithVariantService<T>(string featureName), jak ukazuje následující příklad. Volání v tomto kódu zpřístupní IVariantServiceProvider<IAlgorithm> v kolekci služeb.

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

Každou implementaci IAlgorithm musíte přidat samostatně prostřednictvím metody přidání, například services.AddSingleton<IAlgorithm, SomeImplementation>(). Implementace IAlgorithm , IVariantServiceProvider, která se používá, závisí na příznaku ForecastAlgorithm varianty funkce. Pokud do kolekce služeb není přidána žádná implementace IAlgorithm , IVariantServiceProvider<IAlgorithm>.GetServiceAsync() vrátí úloha s null výsledkem.

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

Atribut aliasu služby Variant

Poskytovatel služeb variant používá názvy typů implementací tak, aby odpovídaly přidělené variantě. Pokud je varianta služby zdobena VariantServiceAliasAttribute, název deklarovaný v tomto atributu by se měl použít v konfiguraci pro odkazování na tuto variantu služby.

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

Telemetrie

Když nasadíte změnu příznaku funkce, je často důležité analyzovat její vliv na aplikaci. Tady je například několik otázek, které mohou nastat:

Jsou vlajky povolené a zakázané podle očekávání?
Mají cíloví uživatelé přístup k určité funkci podle očekávání?
Jakou variantu vidí konkrétní uživatel?

Při zodpovídání těchto typů otázek vám může pomoci emise a analýza vyhodnocovacích událostí funkčních příznaků. Knihovna .NET pro správu funkcí používá System.Diagnostics.Activity rozhraní API k produkci trasovací telemetrie během vyhodnocování příznaků funkcí.

Povolení telemetrie

Ve výchozím nastavení příznaky funkcí nevygenerují telemetrii. Aby bylo možné publikovat telemetrii pro určený příznak funkce, příznak musí deklarovat povolení pro emise telemetrie.

U příznaků funkcí definovaných v appsettings.jsonmůžete povolit telemetrii pomocí telemetry vlastnosti.

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

Předchozí kód ze souboru appsettings.json definuje příznak funkce s názvem MyFeatureFlag , který je povolený pro telemetrii. Stav telemetrie je označen objektem telemetry, který nastaví enabled na true. Hodnota enabled vlastnosti musí být true k publikování telemetrie příznaku.

Část telemetry příznaku funkce má následující vlastnosti:

Vlastnost	Popis
`enabled`	Logická hodnota, která určuje, jestli má být telemetrie publikována pro příznak funkce.
`metadata`	Kolekce párů klíč-hodnota, modelovaná jako slovník, které můžete použít k připojení vlastních metadat o funkčním příznaku k událostem vyhodnocení.

Vlastní publikování telemetrie

Správce funkcí má vlastní ActivitySource instanci s názvem Microsoft.FeatureManagement. Pokud je pro příznak funkce povolená telemetrie:

Když se spustí vyhodnocení příznaku funkce, správce funkcí spustí instanci Activity.
Po dokončení vyhodnocení příznaku funkce přidá správce funkcí instanci pojmenovanou ActivityEventFeatureFlag k aktuální aktivitě.

Událost FeatureFlag obsahuje značky s informacemi o vyhodnocení funkční kontrolky. Značky používají pole definovaná ve schématu FeatureEvaluationEvent .

Poznámka:

Všechny páry klíč-hodnota zadané ve vlastnosti příznaku telemetry.metadata funkce jsou také zahrnuty do tagů.

Pokud chcete povolit vlastní publikování telemetrie, můžete vytvořit instanci ActivityListener a naslouchat zdroji aktivit Microsoft.FeatureManagement. Následující kód ukazuje, jak naslouchat zdroji aktivity správy funkcí a přidat zpětné volání při vyhodnocení funkce.

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

Další informace naleznete v tématu Shromáždění distribuovaného trasování.

Telemetrie aplikace Insights

Balíček Microsoft.FeatureManagement.Telemetry.ApplicationInsights poskytuje integrovaného vydavatele telemetrie, který odesílá data vyhodnocení příznaků funkcí do Application Insights. Balíček Microsoft.FeatureManagement.Telemetry.ApplicationInsights také poskytuje inicializátor telemetrie, který automaticky označí všechny události tak TargetingId , aby události mohly být propojeny s vyhodnocením příznaků. Pokud chcete využít výhod této funkce, přidejte odkaz na balíček a zaregistrujte telemetrii Application Insights. Následující kód obsahuje příklad:

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

Poznámka:

Pokud chcete zajistit, aby telemetrie Application Insights fungovala podle očekávání, měli byste použít TargetingHttpContextMiddleware třídu.

Pokud chcete v aktuální aktivitě povolit trvalost kontextu cílení, můžete použít TargetingHttpContextMiddleware třídu.

app.UseMiddleware<TargetingHttpContextMiddleware>();

Příklad použití najdete v příkladu VariantAndTelemetryDemo .

Požadavek

Vydavatel telemetrie, který balíček poskytuje, Microsoft.FeatureManagement.Telemetry.ApplicationInsights vyžaduje, aby služba Application Insights byla nastavena a registrována jako aplikační služba. Ukázkový kód najdete v ukázkové aplikaci VariantAndTelemetryDemo .

Ukládání do mezipaměti

Systém poskytuje IConfiguration stav funkce. Očekává se, že poskytovatelé konfigurace zpracují veškeré ukládání do mezipaměti a dynamické aktualizace. Správce funkcí požádá IConfiguration o nejnovější hodnotu stavu funkce pokaždé, když vyhodnotí, jestli je funkce povolená.

Snímek

Některé scénáře vyžadují, aby stav funkce zůstal konzistentní během životnosti požadavku. Hodnoty vrácené standardní IVariantFeatureManager implementací se můžou změnit, pokud IConfiguration se zdroj, ze kterého se načítá, během požadavku aktualizuje.

Toto chování můžete zabránit použitím funkce IVariantFeatureManagerSnapshot. Můžete načíst IVariantFeatureManagerSnapshot stejným způsobem jako IVariantFeatureManager. IVariantFeatureManagerSnapshot implementuje IVariantFeatureManager rozhraní, ale IVariantFeatureManagerSnapshot ukládá do mezipaměti první vyhodnocený stav funkce během požadavku. Tento stav se vrátí během životnosti této funkcionality.

Vlastní poskytovatelé funkcí

Při implementaci vlastního poskytovatele funkcí můžete vyžádat příznaky funkcí ze zdrojů, jako je databáze nebo služba pro správu funkcí. Výchozí poskytovatel funkcí načítá příznaky funkcí z konfiguračního systému .NET Core. Tento systém poskytuje podporu pro definování funkcí v souboru appsettings.json nebo v poskytovatelích konfigurace, jako je Azure App Configuration. Toto chování můžete přizpůsobit tak, aby bylo možné určit, odkud se čtou definice funkcí.

Pokud chcete přizpůsobit načítání definic funkcí, musíte implementovat IFeatureDefinitionProvider rozhraní.

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

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

Pokud chcete použít implementaci IFeatureDefinitionProvider, musíte ji před přidáním správy funkcí přidat do kolekce služeb. Následující příklad přidá implementaci pojmenovaného IFeatureDefinitionProviderInMemoryFeatureDefinitionProvider.

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

Další kroky

Informace o používání funkčních přepínačů v aplikacích najdete v následujících rychlých příručkách:

ASP.NET Core

Konzolová aplikace .NET/.NET Framework

Služba .NET background

Pokud chcete zjistit, jak používat filtry funkcí, projděte si následující kurzy:

Povolení podmíněných funkcí s filtry funkcí

Povolení funkcí podle plánu

Zavedení funkcí cílovým skupinám

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-30

Sdílet prostřednictvím

Správa funkcí .NET

Hlavní příznaky

Filtry funkcí

Konfigurace přepínače funkcí

Deklarace příznaku funkce

Typ požadavku

Zpracování více zdrojů konfigurace

Schéma správy funkcí .NET

Spotřeba

Registrace služby

Injekce závislostí

Služby správy funkcí s vymezeným oborem

integrace ASP.NET Core

Kontrolery a akce

Deaktivované zpracování akcí

Zobrazení

Filtry MVC

Razor Pages

Vytváření aplikací

Implementace filtru funkcí

Parametrizované filtry funkcí

Atribut aliasu filtru

Chybějící filtry funkcí

Použití httpContextu

Poskytnutí kontextu pro vyhodnocení funkcí

Filtry kontextových funkcí

Použití kontextových a nekonkonaktivních filtrů se stejným aliasem

Předdefinované filtry funkcí

Microsoft.Percentage

Microsoft.TimeWindow

Opakování

Rozsah opakování

Microsoft.Targeting

Obory názvů aliasů filtru funkcí

Cílení

Cílení ve webové aplikaci

ITargetingContextAccessor

Cílení v konzolové aplikaci

Možnosti vyhodnocení cílení

Vyloučení z cílení

Varianty

Načtení variant

Deklarace funkčního příznaku varianty

Definování variant

Přidělit varianty

Přepsání povoleného stavu pomocí varianty

Varianty injektáže závislostí

Atribut aliasu služby Variant

Telemetrie

Povolení telemetrie

Vlastní publikování telemetrie

Telemetrie aplikace Insights

Požadavek

Ukládání do mezipaměti

Snímek

Vlastní poskytovatelé funkcí

Další kroky

Váš názor

Další materiály