Správa funkcí .NET

Článek
01/14/2025

Knihovna pro správu funkcí .NET poskytuje způsob, jak vyvíjet a zveřejňovat funkce aplikace na základě příznaků funkcí. Po vytvoření nové funkce má mnoho aplikací zvláštní požadavky, například kdy by měla být tato funkce povolená a za jakých podmínek. Tato knihovna poskytuje způsob, jak tyto relace definovat, a také se integruje do běžných vzorů 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. Vývojáři můžou používat příznaky funkcí v jednoduchých případech použití, jako jsou podmíněné příkazy, k pokročilejším scénářům, jako jsou podmíněné přidávání tras nebo filtrů MVC. 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:

Běžná konvence správy funkcí
Nízká bariéra- vstup
- Postaveno na IConfiguration
- Podporuje nastavení příznaku příznaku souboru JSON.
Správa životnosti příznaků funkcí
- Hodnoty konfigurace se mohou měnit v reálném čase; příznaky funkcí můžou být konzistentní v rámci celého požadavku.
Probírané jednoduché až složité scénáře
- Zapnutí/vypnutí funkcí prostřednictvím deklarativního konfiguračního souboru
- Surface different variants of a feature to different users
- Dynamické vyhodnocení stavu funkce na základě volání serveru
Rozšíření rozhraní API pro architekturu ASP.NET Core a MVC
- Směrování
- Filtry
- Atributy akce
Knihovna pro správu funkcí .NET je open source. Další informace najdete v úložišti GitHub.

Příznaky funkcí

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

Filtry funkcí

Filtry funkcí definují scénář, kdy má být funkce povolená. Když je funkce vyhodnocena jako zapnutá nebo vypnutá, její 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.

Jako příklad je možné navrhnout filtr funkcí prohlížeče Microsoft Edge. Tento filtr funkcí aktivuje všechny funkce, ke které je připojen, pokud požadavek HTTP pochází z Microsoft Edge.

Konfigurace příznaku funkce

Konfigurační systém .NET Core slouží k určení stavu příznaků funkcí. Základem tohoto systému je IConfiguration. Jako zprostředkovatele stavu funkce pro knihovnu příznaků funkcí je možné použít libovolného zprostředkovatele IConfiguration . Tento systém umožňuje scénáře od appsettings.json až po konfiguraci Aplikace Azure a další.

Deklarace příznaku funkce

Knihovna pro správu funkcí podporuje appsettings.json jako zdroj příznaků funkce, protože se jedná o poskytovatele systému .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.

Následující příklad 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": "Mon, 01 May 2023 13:59:59 GMT",
                                "End": "Sat, 01 July 2023 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Část feature_management dokumentu JSON se používá konvencí k načtení nastavení příznaku funkce. Objekty příznaku funkce musí být uvedeny v feature_flags poli v oddílu feature_management . V předchozí části vidíme, že jsme poskytli tři různé funkce. Příznak funkce má id a enabled vlastnosti. Jedná se id o název použitý k identifikaci příznaku funkce a odkaz na tento příznak. Vlastnost enabled určuje povolený stav příznaku funkce. Funkce je vypnutá , pokud enabled je false. Pokud enabled je pravda, stav funkce závisí na hodnotě conditions. Pokud neexistuje, conditionsje tato funkce zapnutá. Pokud jsou conditionsa jsou splněné, je tato funkce zapnutá. Pokud existují conditions a nejsou splněné, je tato funkce vypnutá. Vlastnost conditions deklaruje podmínky používané k dynamickému povolení funkce. Funkce definují filtry funkcí v client_filters poli. FeatureV určuje filtr funkcí s názvem Microsoft.TimeWindow. Tento filtr je příkladem konfigurovatelného filtru funkcí. V příkladu vidíme, že filtr má Parameters vlastnost. Tato vlastnost slouží ke konfiguraci filtru. V tomto případě se konfigurují počáteční a koncové časy aktivní funkce.

Upřesnit: Použití dvojtečky :je zakázáno v názvech příznaků funkce.

Typ požadavku

Vlastnost requirement_typeconditions slouží k určení, jestli se 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.

Any znamená, že pouze jeden filtr musí být vyhodnocen jako true, aby byla funkce povolená.
All znamená, že každý filtr musí být vyhodnocen jako true, aby byla funkce povolená.

All Změna requirement_type procházení. Za prvé, pokud neexistuje žádný filtr, funkce je zakázaná. Pokud existují filtry, filtry funkcí se projdou, dokud se některý z filtrů nerozhodne, že by tato funkce měla být 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": "Mon, 01 May 2023 13:59:59 GMT",
                    "End": "Sat, 01 Jul 2023 00:00:00 GMT"
                }
            },
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": "50"
                }
            }
        ]
    }
}

V tomto příkladu určuje hodnotu requirement_typeAll, což znamená, FeatureW že všechny jeho filtry musí být vyhodnoceny jako true, aby funkce byla povolena. V tomto případě je tato funkce povolená pro 50 % uživatelů během zadaného časového intervalu.

Schéma správy funkcí .NET

V předchozích verzích byl primárním schématem .NET feature management schemaknihovny pro správu funkcí . Od verze 4.0.0 nejsou pro schéma správy funkcí .NET podporované nové funkce včetně variant a telemetrie.

Poznámka:

Pokud existuje deklarace příznaku funkce, kterou najdete v obou feature_management částech i FeatureManagement v oddílech, přijme se ta z feature_management této části.

Využití

Základní forma správy funkcí kontroluje, jestli je povolený příznak funkce, a pak provádí akce na základě výsledku. Tato kontrola se provádí prostřednictvím IVariantFeatureManagermetody ' IsEnabledAsync .

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

Registrace služby

Správa funkcí spoléhá na injektáž závislostí .NET Core. Služby správy funkcí můžeme zaregistrovat pomocí standardních konvencí.

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 FeatureManagement konfiguračních dat .NET Core. Pokud část FeatureManagement neexistuje, konfigurace se považuje za prázdnou.

Poznámka:

Můžete také určit, že konfigurace příznaku funkce by měla být načtena z jiného oddílu konfigurace předáním oddílu AddFeatureManagementdo . Následující příklad říká správci funkcí, aby místo toho četl z jiné části s názvem "MyFeatureFlags":

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

Injektáž závislostí

Při použití knihovny pro správu funkcí s MVC je možné ji IVariantFeatureManager získat prostřednictvím 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ává služby správy funkcí jako singletony v rámci aplikace, ale existují scénáře, kdy může být nutné přidat služby správy funkcí jako služby s vymezeným oborem. Uživatelé můžou například chtít použít filtry funkcí, které využívají vymezené služby pro kontextové informace. V tomto případě AddScopedFeatureManagement by se měla použít metoda. 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 se daná funkce nebo některý ze seznamů funkcí povolily, aby bylo možné provést. Tento požadavek lze provést pomocí , FeatureGateAttributekterý lze najít v Microsoft.FeatureManagement.Mvc oboru názvů.

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

V tomto příkladu HomeController je chráněn funkcí FeatureX. Aby bylo možné provést jakoukoli akci HomeController obsahující, musí být povolená funkce FeatureX.

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

V tomto příkladu Index akce MVC vyžaduje, aby byla povolena funkce FeatureX, aby bylo možné ji spustit.

Zakázané zpracování akcí

Pokud je kontroler MVC nebo akce blokované, protože nejsou povoleny žádné funkce, které určuje, je vyvolána zaregistrovaná IDisabledFeaturesHandler akce. Ve výchozím nastavení je zaregistrovaná minimalická obslužná rutina, která vrací http 404. Tuto obslužnou rutinu lze přepsat pomocí příznaku IFeatureManagementBuilder funkce při registraci.

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

Zobrazení

Značky zobrazení <feature> MVC lze použít k podmíněnému vykreslení obsahu na základě toho, jestli je funkce povolená nebo jestli je přiřazena konkrétní varianta funkce. Další informace najdete v části Varianty .

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

<feature name="FeatureX" variant="Alpha">
  <p>This can only be seen if variant 'Alpha' of 'FeatureX' is assigned.</p>
</feature>

Pokud je funkce nebo sada funkcí zakázaná, můžete také negovat vyhodnocení pomocné rutiny značek. negate="true" Nastavením v následujícím příkladu se obsah vykreslí pouze v případě, že FeatureX je zakázaný.

<feature negate="true" name="FeatureX">
  <p>This can only be seen if 'FeatureX' is disabled.</p>
</feature>

<feature negate="true" name="FeatureX" variant="Alpha">
  <p>This can only be seen if variant 'Alpha' of 'FeatureX' isn't assigned.</p>
</feature>

Značka <feature> může odkazovat na více funkcí/variant zadáním čárkami odděleného seznamu funkcí/variant v atributu/namevariant.

<feature name="FeatureX,FeatureY">
  <p>This can only be seen if 'FeatureX' and 'FeatureY' are enabled.</p>
</feature>

<feature name="FeatureX" variant="Alpha,Beta">
  <p>This can only be seen if variant 'Alpha' or 'Beta' of 'FeatureX' is assigned.</p>
</feature>

Poznámka:

Pokud variant je zadána, měla by být zadána pouze jedna funkce.

Ve výchozím nastavení musí být všechny uvedené funkce povolené, aby se značka funkce vykreslovala. Toto chování lze přepsat přidáním atributu requirement , jak je vidět v následujícím příkladu.

Poznámka:

requirement And Pokud je použita ve spojení s variant chybou, bude vyvolán, protože více variant nelze nikdy přiřadit.

<feature name="FeatureX,FeatureY" requirement="Any">
  <p>This can only be seen if either 'FeatureX' or 'FeatureY' or both are enabled.</p>
</feature>

Značka <feature> vyžaduje, aby fungoval pomocník značky. Pokud chcete tuto značku použít, přidejte pomocnou rutinu značky správy funkcí do souboru ViewImports.cshtml .

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

Filtry MVC

Filtry akcí MVC je možné nastavit tak, aby se podmíněně spouštěly na základě stavu funkce. To se provádí registrací filtrů MVC způsobem pracujícím s funkcemi. Kanál správy funkcí podporuje asynchronní filtry akcí MVC, které implementují IAsyncActionFilter.

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

Tento kód přidá filtr MVC s názvem SomeMvcFilter. Tento filtr se aktivuje jenom v rámci kanálu MVC, pokud je povolená funkce FeatureX.

Razor Pages

MVC Razor Pages může vyžadovat povolení dané funkce nebo některého ze seznamu funkcí, aby bylo možné provést. Tento požadavek lze přidat pomocí , FeatureGateAttributekterý lze najít v Microsoft.FeatureManagement.Mvc oboru názvů.

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

Výše uvedený kód nastaví stránku Razor Page tak, aby vyžadovala povolení featureX. Pokud funkce není povolená, stránka vygeneruje výsledek HTTP 404 (Nenalezeno).

Pokud se používá na stránkách Razor Pages, FeatureGateAttribute musí být umístěn na typ obslužné rutiny stránky. Nelze ji umístit na jednotlivé metody obslužné rutiny.

Vytváření aplikací

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

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

Při výše uvedeném volání přidá aplikace komponentu middlewaru, která se zobrazí pouze v kanálu požadavku, pokud je povolená funkce FeatureX. Pokud je funkce povolená nebo zakázaná během běhu, je možné kanál middlewaru dynamicky změnit.

Tím se sestaví obecnější funkce pro 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. Aby bylo možné implementovat filtr funkcí, musí být implementováno 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 EvaluateAsync se vrátí true, znamená to, že by funkce měla být povolená.

Následující fragment kódu ukazuje, jak přidat přizpůsobený filtr MyCriteriaFilterfunkcí .

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

Filtry funkcí jsou registrovány voláním AddFeatureFilter<T> vráceného IFeatureManagementBuilder z AddFeatureManagement. Tyto filtry funkcí mají přístup ke službám, které existují v kolekci služeb, které se použily k přidání příznaků funkcí. Injektáž závislostí se dá použít k načtení těchto služeb.

Poznámka:

Pokud jsou filtry odkazovány v nastavení příznaku funkce (například appsettings.json), část Filtr názvu typu by měla být vynechána. Další informace najdete v Filter Alias Attribute části.

Filtry parametrizovaných funkcí

Některé filtry funkcí vyžadují parametry k určení, jestli má být funkce zapnutá nebo ne. Filtr funkcí prohlížeče může například zapnout funkci pro určitou sadu prohlížečů. Může být žádoucí, aby prohlížeče Edge a Chrome povolily funkci, zatímco Firefox ne. K tomuto filtrování je možné navrhnout filtr funkcí tak, aby očekával parametry. Tyto parametry by byly zadány v konfiguraci funkce a v kódu by byly přístupné 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; }
}

FeatureFilterEvaluationContext má vlastnost s názvem Parameters. Tyto parametry představují nezpracovanou konfiguraci, pomocí které může filtr funkcí rozhodnout, jak vyhodnotit, jestli má být funkce povolená nebo ne. Pokud chcete znovu použít filtr funkcí prohlížeče jako příklad, filtr by mohl použít Parameters k extrahování sady povolených prohlížečů, které by byly pro tuto funkci zadány, a pak zkontrolujte, jestli se požadavek odesílá 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();

        //
        // Here we would use the settings and see if the request was sent from any of BrowserFilterSettings.AllowedBrowsers
    }
}

Atribut aliasu filtru

Pokud je filtr funkcí zaregistrovaný pro příznak funkce, alias použitý v konfiguraci je název typu filtru funkce s příponou Filtru ( pokud existuje) odebrán. Například MyCriteriaFilter by se v konfiguraci označovala jako MyCriteria .

"MyFeature": {
    "EnabledFor": [
        {
            "Name": "MyCriteria"
        }
    ]
}

Tento název lze přepsat pomocí .FilterAliasAttribute Filtr funkcí lze dekorovat tímto atributem a deklarovat název, který by se měl použít v konfiguraci pro odkazování na tento filtr funkcí v rámci příznaku funkce.

Chybějící filtry funkcí

Pokud je funkce nakonfigurovaná tak, aby byla povolená pro konkrétní filtr funkcí a tento filtr funkcí není zaregistrovaný, při vyhodnocení funkce se vyvolá výjimka. Výjimku je možné 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. To se provádí kontrolou kontextu HTTP. Filtr funkcí může získat odkaz na kontext HTTP získáním IHttpContextAccessor injektáže závislostí.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

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

Aby IHttpContextAccessor byl kontejner injektáže závislostí dostupný, musí být přidaný do kontejneru injektáže závislostí. Lze ji zaregistrovat pomocí IServiceCollection následující metody.

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

Rozšířené:IHttpContextAccessor/HttpContext Neměly by se 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 služby s vymezeným oborem. U aplikací AddScopedFeatureManagement Blazor by se měly používat k registraci služeb správy funkcí. Další informace najdete v Scoped Feature Management Services části.

Poskytnutí kontextu pro vyhodnocení funkce

V konzolových aplikacích neexistuje žádný kontext okolí, například HttpContext filtry funkcí, které by mohly získat a využít ke kontrole, jestli má být funkce zapnutá nebo vypnutá. V tomto případě musí aplikace poskytnout objekt představující kontext do systému pro správu funkcí, aby je bylo možné použít filtry funkcí. Tento kontext lze dát pomocí IVariantFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext). Objekt appContext, který je poskytován správci funkcí, lze použít filtry funkcí k vyhodnocení stavu funkce.

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

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

Kontextové filtry funkcí

Kontextové filtry funkcí implementují IContextualFeatureFilter<TContext> rozhraní. Tyto speciální filtry funkcí mohou využít kontext, který se předává při IVariantFeatureManager.IsEnabledAsync<TContext> zavolání. Parametr TContext typu popisuje IContextualFeatureFilter<TContext> , jaký typ kontextu je filtr schopen zpracovat. To umožňuje vývojáři kontextového filtru funkcí popsat, co je potřeba pro ty, kteří ho chtějí využívat. Vzhledem k tomu, že každý typ je potomkem objektu, lze volat filtr, který implementuje IContextualFeatureFilter<object> jakýkoli zadaný kontext. Pokud chcete ilustrovat příklad konkrétnějšího kontextového filtru funkcí, zvažte funkci, která je povolená, pokud je účet v konfigurovaném 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 if the feature should be on with the help of the provided IAccountContext
    }
}

Vidíme, že AccountIdFilter vyžaduje objekt, který implementuje IAccountContext poskytnutí, aby mohl vyhodnotit stav funkce. Při použití tohoto filtru funkce volající musí zajistit, aby předaný objekt implementuje IAccountContext.

Poznámka:

Jediným typem je možné implementovat pouze jedno rozhraní filtru funkcí. Pokus o přidání filtru funkcí, který implementuje více než jeden rozhraní filtru funkcí výsledky v ArgumentException.

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

IFeatureFilter Filtry a IContextualFeatureFilter můžou sdílet stejný alias. Konkrétně můžete mít jeden alias filtru sdílený 0 nebo 1 IFeatureFilter a 0 nebo N IContextualFeatureFilter<ContextType>, pokud existuje maximálně jeden použitelný filtr pro ContextType.

Následující část popisuje proces výběru filtru, pokud jsou v aplikaci zaregistrovány kontextové a nerelační filtry stejného názvu.

Řekněme, že máte filtr, který není kontextový, a FilterA dva kontextové filtry FilterB a FilterC, které přijímají TypeB kontexty a TypeC v uvedeném pořadí. Všechny tři filtry sdílejí stejný alias SharedFilterName.

Máte také příznak MyFeature funkce, který používá filtr SharedFilterName funkcí v jeho konfiguraci.

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

Při volání IsEnabledAsync("MyFeature"), FilterA slouží k vyhodnocení příznaku funkce.
Při volání IsEnabledAsync("MyFeature", context), pokud je TypeBtyp kontextu , FilterB je použit. Pokud je TypeCtyp kontextu , FilterC použije se.
Při volání IsEnabledAsync("MyFeature", context), pokud je TypeFtyp kontextu , FilterA je použit.

Předdefinované filtry funkcí

Existuje několik filtrů funkcí, které jsou součástí Microsoft.FeatureManagement balíčku: PercentageFilter, TimeWindowFilterContextualTargetingFilter a TargetingFilter. Při registraci správy funkcí metodou AddFeatureManagement se automaticky přidají všechny filtry s výjimkou této TargetingFilterfunkce. Přidá TargetingFilter se s metodou WithTargeting , která je podrobně popsána Targeting v části.

Každý z předdefinovaných filtrů funkcí má vlastní parametry. Tady je seznam filtrů funkcí spolu s příklady.

Microsoft.Percentage

Tento filtr poskytuje možnost povolit funkci na základě nastaveného procenta.

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "Name": "Microsoft.Percentage",
            "Parameters": {
                "Value": 50
            }
        }
    ]
}

Microsoft.TimeWindow

Tento filtr poskytuje možnost povolit funkci na základě časového intervalu. Pokud je zadána pouze End tato funkce, bude tato funkce do té doby považována za zapnutou. Pokud je zadána pouze Start tato funkce, bude funkce považovaná za všechny body po uplynutí této doby.

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "Name": "Microsoft.TimeWindow",
            "Parameters": {
                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
            }
        }
    ]
}

Časové období je možné nakonfigurovat tak, aby se pravidelně opakovalo. To může být užitečné ve scénářích, kdy může být potřeba zapnout funkci během období nízkého nebo vysokého provozu dne nebo určitého dne v týdnu. Pokud chcete rozbalit jednotlivé časové intervaly na opakující se časová období, mělo by být v parametru Recurrence zadáno pravidlo opakování.

Poznámka:

Start a End musí být zadány oba, aby bylo možné povolit Recurrence.

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "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í: Pattern (jak často se časové okno opakuje) a Range (jak dlouho se vzorec opakování opakuje).

Způsob opakování

Existují dva možné typy opakování: Daily a Weekly. Například časové okno 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 povinná, nepovinná nebo ignorováná.

Daily

Způsob denního opakování způsobí opakování časového intervalu na základě počtu dnů mezi jednotlivými výskyty.

Vlastnost	Relevance	Popis
Typ	Požaduje se	Musí být nastavena na `Daily`hodnotu .
Interval	Volitelné	Určuje 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ý den nebo dny v týdnu na základě počtu týdnů mezi jednotlivými sadami výskytů.

Vlastnost	Relevance	Popis
Typ	Požaduje se	Musí být nastavena na `Weekly`hodnotu .
DaysOfWeek	Požaduje se	Určuje, ve kterých dnech v týdnu dojde k události.
Interval	Volitelné	Určuje počet týdnů mezi každou sadou výskytů. Výchozí hodnota je 1.
FirstDayOfWeek	Volitelné	Určuje, který den se považuje za 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:

Start musí být platný první výskyt, který odpovídá vzoru opakování. Kromě toho doba trvání časového intervalu nemůže být delší, než jak často k němu dochází. Například je neplatné, aby se každý den opakovalo 25hodinové časové intervaly.

Rozsah opakování

Existují tři možné typy rozsahu opakování: NoEndEndDate a Numbered.

NoEnd

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

Vlastnost Relevance Popis

Typ Požaduje se Musí být nastavena na NoEndhodnotu .

Vlastnost	Relevance	Popis
Typ	Požaduje se	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
Typ	Požaduje se	Musí být nastavena na `EndDate`hodnotu .
KoncovéDatum	Požaduje se	Určuje datum, kdy se má model přestat používat. Pokud počáteční čas posledního výskytu spadá před koncové datum, je možné, že koncový čas tohoto výskytu přesahuje jeho rámec.

Následující příklad opakuje časové intervaly každý den, dokud se poslední výskyt nestane 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ý interval nastane pevného počtu (na základě vzoru).

Vlastnost Relevance Popis

Typ Požaduje se Musí být nastavena na Numberedhodnotu .

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

Následující příklad zopakuje časové okno v pondělí a úterý, dokud nedojde ke třem výskytům, které probíhají 1. dubna, 2. dubna a 8. dubna.
```
"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
Typ	Požaduje se	Musí být nastavena na `Numbered`hodnotu .
NumberOfOccurrences	Požaduje se	Určuje počet výskytů.

Chcete-li vytvořit pravidlo opakování, musíte zadat obě Pattern a 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

Tento filtr poskytuje možnost povolit funkci cílové cílové skupině. Podrobné vysvětlení cílení je vysvětleno v části cílení . Parametry filtru zahrnují Audience objekt, který popisuje uživatele, skupiny, vyloučené uživatele/skupiny a výchozí procento uživatelské základny, které by měly mít přístup k této funkci. Každý objekt skupiny, který je uveden v oddílu Groups , musí také určit, jaké procento členů skupiny by mělo mít přístup. Pokud je uživatel zadaný v oddílu Exclusion , buď přímo, nebo pokud je uživatel ve vyloučené skupině, je tato funkce zakázaná. Jinak platí, že pokud je uživatel zadán přímo v oddílu Users nebo pokud je uživatel zahrnuté v procentech uvedení skupiny nebo pokud uživatel spadá do výchozího procenta uvedení, bude mít tento uživatel povolenou funkci.

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "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í. Tento obor názvů je zabránit konfliktům s jinými filtry funkcí, které můžou sdílet stejný alias. Segmenty oboru názvů filtru funkcí jsou rozděleny znakem ".". Na filtr funkcí lze odkazovat pomocí plně kvalifikovaného aliasu, jako Microsoft.Percentage je nebo podle posledního Microsoft.Percentage segmentu, který je Percentagev případě .

Cílení

Cílení je strategie správy funkcí, která vývojářům umožňuje postupně zavádět nové funkce 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ů/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 Beta:

Jednotlivým uživatelům Jeff a Alicia je udělen přístup k beta verzi.
Jiný uživatel, Mark, žádá, aby se přihlásil a je zahrnutý.
Do beta verze je zahrnuta dvacet procent skupiny, která se označuje jako "Ring1".
Počet uživatelů okruhu 1 zahrnutých v beta verzi se zhrouží až na 100 procent.
Pět procent uživatelské základny je součástí beta verze.
Procento zavedení se přeplní až na 100 procent a funkce se kompletně zavádí.

Tato strategie pro zavádění funkce je součástí knihovny prostřednictvím zahrnutého filtru funkcí Microsoft.Targeting .

Cílení ve webové aplikaci

Ukázková webová aplikace, která používá filtr funkcí cílení, je k dispozici v ukázkovém projektu FeatureFlagDemo .

Pokud chcete začít používat TargetingFilter aplikaci, 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 se spoléhá na přidání jiné služby do kolekce služeb aplikace. Tato služba je .ITargetingContextAccessor

Microsoft.FeatureManagement.AspNetCore poskytuje výchozí implementaci, která ITargetingContextAccessor extrahuje informace o cílení z žádosti HttpContext. Při nastavování cílení můžete použít výchozí přístupový objekt kontextu cílení pomocí ne generického WithTargeting přetížení v objektu IFeatureManagementBuilder.

Výchozí přístupové objekty kontextu cílení a TargetingFilter jsou registrovány voláním WithTargeting .IFeatureManagementBuilder

services.AddFeatureManagement()
        .WithTargeting();

Můžete také zaregistrovat přizpůsobenou implementaci pro ITargetingContextAccessor a TargetingFilter voláním WithTargeting<T>. Tady je příklad nastavení správy funkcí ve webové aplikaci pro použití TargetingFilter s implementací volaného ITargetingContextAccessorExampleTargetingContextAccessor.

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

ITargetingContextAccessor

K použití TargetingFilter ve webové aplikaci se vyžaduje implementace ITargetingContextAccessor . Tento požadavek je způsoben tím, že při vyhodnocování cílení se vyžadují kontextové informace, například to, co se právě vyhodnocuje uživateli. Tyto informace se označují jako TargetingContext. Různé aplikace mohou tyto informace extrahovat z různých míst. Mezi běžné příklady, kdy může aplikace vyžádat kontext cílení, jsou kontext HTTP požadavku nebo databáze.

Příkladem, který extrahuje informace o kontextu cílení z kontextu HTTP aplikace, je DefaultHttpTargetingContextAccessor poskytnutý Microsoft.FeatureManagement.AspNetCore balíčkem. Extrahuje informace o cílení z HttpContext.User. UserId informace budou extrahovány z Identity.Name pole a Groups informace budou extrahovány z deklarací typu Role. Tato implementace spoléhá na použití IHttpContextAccessor, který je zde popsán.

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 například aktuálně vyhodnocovaný uživatel a jaké skupiny uživatel používá. V konzolovýchaplikacích FeatureManager.IsEnabledAsync Tento typ kontextu je podporován pomocí znaku ContextualTargetingFilter. Aplikace, které potřebují plout kontext cílení do správce funkcí, by měly místo TargetingFilter.

Vzhledem k tomu ContextualTargetingFilter , že je to , IContextualTargetingFilter<ITargetingContext>implementace ITargetingContext musí být předána IVariantFeatureManager.IsEnabledAsync , aby bylo možné vyhodnotit a zapnout funkci.

IVariantFeatureManager fm;
…
// userId and groups defined somewhere earlier in application
TargetingContext targetingContext = new TargetingContext
{
   UserId = userId,
   Groups = groups
};

await fm.IsEnabledAsync(featureName, targetingContext);

Stále ContextualTargetingFilter používá alias filtru funkcí Microsoft.Targeting, takže konfigurace tohoto filtru je konzistentní s tím, co je uvedeno v této části.

Příklad, který používá ContextualTargetingFilter konzolovou aplikaci, je k dispozici 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 je možné nakonfigurovat při nastavování správy funkcí.

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

Vyloučení cílení

Při definování cílové skupiny mohou být uživatelé a skupiny vyloučeni z cílové skupiny. Vyloučení je užitečné, když se funkce zavádí skupině uživatelů, ale několik uživatelů nebo skupin musí být vyloučeno z uvedení. Vyloučení je definováno přidáním seznamu uživatelů a skupin do Exclusion vlastnosti cílové skupiny.

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

V předchozím příkladu je funkce povolena pro uživatele pojmenované Jeff a Alicia. Je také povolená pro uživatele ve skupině s názvem Ring0. Pokud je však uživatel pojmenován Mark, je funkce zakázaná bez ohledu na to, jestli jsou ve skupině Ring0 nebo ne. Vyloučení mají přednost před zbytkem filtru cílení.

Varianty

Když se do aplikace přidají nové funkce, může přijít čas, kdy má funkce několik různých navrhovaných možností návrhu. Běžným řešením pro rozhodování o návrhu je určitá forma testování A/B, která zahrnuje poskytnutí jiné verze funkce různým segmentům uživatelské základny a výběru verze na základě interakce uživatele. V této knihovně je tato funkce povolena reprezentací různých konfigurací funkce s variantami.

Varianty umožňují, aby se příznak funkce stal více než jednoduchým příznakem 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 za jakých okolností se má každá varianta použít, což je podrobněji popsáno v části Přidělování variant .

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

Získání variant

Pro každou funkci je možné načíst variantu IVariantFeatureManagerpomocí metody 's GetVariantAsync .

…
IVariantFeatureManager featureManager;
…
Variant variant = await featureManager.GetVariantAsync(MyFeatureFlags.FeatureU, CancellationToken.None);

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration

Po načtení varianty lze konfiguraci varianty použít přímo jako vlastnost IConfigurationSection varianty Configuration . Další možností je svázat konfiguraci s objektem pomocí . Model konfigurační vazby rozhraní NET

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

Vrácená varianta závisí na uživateli, který se právě vyhodnocuje, a že informace jsou získány z instance TargetingContext. Tento kontext lze předat při volání GetVariantAsync , nebo jej lze automaticky načíst z implementace ITargetingContextAccessor , pokud je zaregistrován.

Deklarace příznaku funkce Variant

Ve srovnání s normálními příznaky funkcí mají příznaky varianty dvě další vlastnosti: variants a allocation. Vlastnost variants je pole, které obsahuje varianty definované pro tuto funkci. Vlastnost allocation definuje, jak mají být tyto varianty přiděleny pro tuto funkci. Stejně jako deklarování normálních příznaků funkcí můžete v souboru JSON nastavit příznaky variant funkcí. Tady je příklad příznaku funkce varianty.

{
    "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. Konfiguraci lze nastavit pomocí configuration_value vlastnosti. configuration_value je vložená konfigurace, která může být řetězec, číslo, logická hodnota nebo objekt konfigurace. Pokud configuration_value není zadána, vrácená vlastnost varianty Configuration bude null.

Seznam všech možných variant je definován pro každou funkci v rámci variants vlastnosti.

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

Přidělování variant

Proces přidělování variant funkce je určen 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 funkce má následující vlastnosti:

Vlastnost	Popis
`default_when_disabled`	Určuje, která varianta se má použít, když se vyžaduje varianta, zatímco je tato funkce považována za zakázanou.
`default_when_enabled`	Určuje, která varianta se má použít, když je varianta požadována, zatímco je funkce považována za povolenou a uživateli nebyla přiřazena žádná jiná varianta.
`user`	Určuje variantu a seznam uživatelů, kterým má být tato varianta přiřazena.
`group`	Určuje variantu a seznam skupin. Varianta bude přiřazena, pokud je uživatel alespoň v jedné ze skupin.
`percentile`	Určuje variantu a procento rozsahu, do kterého se musí přiřadit vypočítané procento uživatele.
`seed`	Hodnota, na které jsou založeny procentuální výpočty `percentile` . Procento výpočtu pro konkrétního uživatele bude 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.

V předchozím příkladu, pokud funkce není povolená, správce funkcí přiřadí variantu označenou jako default_when_disabled aktuálnímu uživateli, což je Small v tomto případě.

Pokud je tato funkce povolená, správce funkcí zkontroluje usergrouppercentile a přidělení v daném pořadí, aby přiřadil variantu. V tomto konkrétním příkladu platí, že pokud je vyhodnocený uživatel pojmenovaný Marsha, ve skupině s názvem Ring1nebo se stane, že uživatel spadá mezi 0 a 10. percentil, pak je zadaná varianta přiřazena uživateli. V tomto případě by všechny tyto hodnoty vrátily variantu Big . Pokud se žádné z těchto přidělení neshoduje, přiřadí se uživateli varianta default_when_enabled , což je Small.

Logika přidělení je podobná filtru funkcí Microsoft.Targeting , ale existují některé parametry, které jsou přítomné v cílení, které nejsou v přidělení, a naopak. Výsledky cílení a přidělování nesouvisí.

Poznámka:

Pokud chcete povolit přidělování variant funkcí, musíte se zaregistrovat ITargetingContextAccessor voláním WithTargeting<T> metody.

Přepsání povoleného stavu variantou

Varianty můžete použít k přepsání povoleného stavu příznaku funkce. To dává variantám příležitost rozšířit vyhodnocení příznaku funkce. Při volání IsEnabled 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í se provádí pomocí volitelné vlastnosti status_overridevarianty . Ve výchozím nastavení je tato vlastnost nastavena na None, což znamená, že varianta nemá vliv na to, zda je příznak považován za povolený nebo zakázaný. Nastavení status_override pro Enabled povolení varianty, pokud je zvoleno, přepsat příznak, který se má povolit. Nastavení status_override pro Disabled poskytnutí opačných funkcí, a proto zakázání příznaku při výběru varianty. Funkci se stavem enabledfalse nelze přepsat.

Pokud používáte příznak funkce s binárními variantami, status_override může být vlastnost velmi užitečná. Umožňuje pokračovat v používání rozhraní API, jako IsEnabledAsync je a FeatureGateAttribute v aplikaci, a využívat přitom nové funkce, které jsou součástí variant, jako je přidělování percentilu a počáteční hodnota.

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

Ve výše uvedené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ě se varianta Off vrátí a protože status_override je rovna Disabled, funkce bude nyní považována za zakázanou.

Varianty injektáže závislostí

Příznaky variant funkcí lze použít ve spojení s injektáží závislostí k zobrazení různých implementací služby pro různé uživatele. Tato kombinace se provádí pomocí IVariantServiceProvider<TService> rozhraní.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken);

Ve výše uvedeném fragmentu kódu načte IVariantServiceProvider<IAlgorithm> implementaci IAlgorithm z kontejneru injektáže závislostí. Zvolená implementace závisí na:

Příznak funkce, ke IAlgorithm kterému byla služba zaregistrovaná.
Přidělená varianta pro tuto funkci.

Aplikace IVariantServiceProvider<T> je zpřístupněna voláním IFeatureManagementBuilder.WithVariantService<T>(string featureName). Viz následující příklad.

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

Výše uvedené volání zpřístupní IVariantServiceProvider<IAlgorithm> v kolekci služeb. IAlgorithm Implementace musí být přidány samostatně prostřednictvím metody přidání, například services.AddSingleton<IAlgorithm, SomeImplementation>(). Implementace IAlgorithmIVariantServiceProvider použití závisí na příznaku ForecastAlgorithm varianty funkce. Pokud do kolekce služby není přidána žádná implementace IAlgorithm , IVariantServiceProvider<IAlgorithm>.GetServiceAsync() vrátí úkol s výsledkem null .

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

Atribut aliasu služby Variant

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

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

Telemetrie

Při nasazení změny 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 moje příznaky povolené nebo 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?

Na tyto typy otázek je možné odpovědět prostřednictvím emisí a analýzy událostí vyhodnocení příznaků funkcí. Tato knihovna používá System.Diagnostics.Activity rozhraní API k vytvoření telemetrie trasování během vyhodnocení příznaku funkce.

Povolení telemetrie

Ve výchozím nastavení příznaky funkcí nevygenerují telemetrii. Pokud chcete publikovat telemetrii pro daný příznak funkce, musí příznak deklarovat, že má povolené emise telemetrie.

Pro příznaky funkcí definované v appsettings.json, telemetrie lze povolit pomocí telemetry vlastnosti.

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

Výše uvedený fragment kódu appsettings definuje příznak funkce s názvem MyFeatureFlag , který je povolený pro telemetrii. Stav telemetrie je označen objektem telemetry , který se 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`	Určuje, jestli má být telemetrie publikována pro příznak funkce.
`metadata`	Kolekce párů klíč-hodnota, modelovaná jako slovník, která se dá použít k připojení vlastních metadat o příznaku funkce k vyhodnocení událostí.

Vlastní publikování telemetrie

Správce funkcí má vlastní ActivitySource název Microsoft.FeatureManagement. Pokud telemetry je příznak funkce povolen, při každém spuštění vyhodnocení příznaku funkce spustí správce funkcí .Activity Po dokončení vyhodnocení příznaku funkce přidá správce ActivityEvent funkcí název FeatureFlag k aktuální aktivitě. Událost FeatureFlag bude obsahovat značky, které obsahují informace o vyhodnocení příznaku funkce podle polí definovaných ve schématu FeatureEvaluationEvent .

Poznámka:

Všechny páry klíč-hodnota zadané v telemetry.metadata příznaku funkce budou také zahrnuty do značek.

Pokud chcete povolit vlastní publikování telemetrie, můžete vytvořit ActivityListener zdroj aktivity a naslouchat ho Microsoft.FeatureManagement . Tady je příklad, který ukazuje, jak naslouchat zdroji aktivity správy funkcí a jak 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 najdete v tématu Shromáždění distribuovaného trasování.

Telemetrie Application 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 to chcete využít, přidejte odkaz na balíček a zaregistrujte telemetrii Application Insights jako v následujícím příkladu.

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

Poznámka:

Pokud chcete zajistit, aby telemetrie Application Insights fungovala podle očekávání, TargetingHttpContextMiddleware měla by se použít.

Chcete-li povolit trvalost kontextu cílení v aktuální aktivitě, můžete použít TargetingHttpContextMiddleware.

app.UseMiddleware<TargetingHttpContextMiddleware>();

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

Požadavek

Tento vydavatel telemetrie závisí na tom, že služba Application Insights už je zaregistrovaná jako aplikační služba. To se například provádí tady v ukázkové aplikaci.

Tento vydavatel telemetrie závisí na tom, že služba Application Insights už je nastavená a zaregistrovaná jako aplikační služba.

Ukládání do mezipaměti

Systém poskytuje IConfiguration stav funkce. Očekává se, že veškeré ukládání do mezipaměti a dynamické aktualizace budou zpracovávat poskytovatelé konfigurace. Správce funkcí požádá o IConfiguration nejnovější hodnotu stavu funkce pokaždé, když je funkce zaškrtnutá, aby byla povolena.

Snímek

Existují scénáře, které vyžadují, aby stav funkce zůstal konzistentní během životnosti požadavku. Hodnoty vrácené ze standardu IVariantFeatureManager se můžou změnit, pokud IConfiguration se zdroj, ze kterého se načítá, během požadavku aktualizuje. To může být znemožněno pomocí IVariantFeatureManagerSnapshot. IVariantFeatureManagerSnapshot lze načíst stejným způsobem jako IVariantFeatureManager. IVariantFeatureManagerSnapshot implementuje rozhraní , IVariantFeatureManagerale ukládá do mezipaměti první vyhodnocený stav funkce během požadavku a vrací stejný stav funkce během jeho životnosti.

Vlastní zprostředkovatelé funkcí

Implementace vlastního poskytovatele funkcí umožňuje vývojářům vyžádat příznaky funkcí ze zdrojů, jako je databáze nebo služba pro správu funkcí. Zahrnutý poskytovatel funkcí, který se používá ve výchozím nastavení, načítá příznaky funkcí z konfiguračního systému .NET Core. To umožňuje definovat funkce v souboru appsettings.json nebo v poskytovatelích konfigurace, jako je Aplikace Azure Konfigurace. Toto chování lze nahradit tak, aby poskytovalo úplnou kontrolu nad tím, odkud se čtou definice funkcí.

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

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

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

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

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

Další kroky

Pokud chcete zjistit, jak ve svých aplikacích používat příznaky funkcí, pokračujte následujícími rychlými starty.

ASP.NET Core

Konzolová aplikace .NET/.NET Framework

Služba .NET background

Pokud se chcete dozvědět, jak používat filtry funkcí, pokračujte následujícími kurzy.

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

Povolení funkcí podle plánu

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

Sdílet prostřednictvím

Správa funkcí .NET

Příznaky funkcí

Filtry funkcí

Konfigurace příznaku funkce

Deklarace příznaku funkce

Typ požadavku

Schéma správy funkcí .NET

Využití

Registrace služby

Injektáž závislostí

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

Integrace ASP.NET Core

Kontrolery a akce

Zakázané zpracování akcí

Zobrazení

Filtry MVC

Razor Pages

Vytváření aplikací

Implementace filtru funkcí

Filtry parametrizovaných funkcí

Atribut aliasu filtru

Chybějící filtry funkcí

Použití httpContextu

Poskytnutí kontextu pro vyhodnocení funkce

Kontextové filtry funkcí

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

Předdefinované filtry funkcí

Microsoft.Percentage

Microsoft.TimeWindow

Způsob 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í cílení

Varianty

Získání variant

Deklarace příznaku funkce Variant

Definování variant

Přidělování variant

Přepsání povoleného stavu variantou

Varianty injektáže závislostí

Atribut aliasu služby Variant

Telemetrie

Povolení telemetrie

Vlastní publikování telemetrie

Telemetrie Application Insights

Požadavek

Ukládání do mezipaměti

Snímek

Vlastní zprostředkovatelé funkcí

Další kroky

Váš názor

Další materiály