Sdílet prostřednictvím

Správa funkcí .NET

  • Článek

Microsoft.FeatureManagement
Microsoft.FeatureManagement.AspNetCore

Microsoft.FeatureManagement
Microsoft.FeatureManagement.AspNetCore
Microsoft.FeatureManagement.Telemetry.ApplicationInsights
Microsoft.FeatureManagement.Telemetry.ApplicationInsights.AspNetCore

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
    • 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í se skládají ze dvou částí, názvu a seznamu filtrů funkcí, které se používají k zapnutí funkce.

Filtry funkcí

Filtry funkcí definují scénář, kdy má být funkce povolená. Když se funkce vyhodnotí, jestli je zapnutá nebo vypnutá, její seznam filtrů funkcí se projde, dokud se některý z filtrů nerozhodne, že by měla být funkce povolená. V tomto okamžiku se funkce považuje za povolenou a procházení přes filtry funkcí se 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í by aktivoval 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 . Níže máme příklad formátu použitého k nastavení příznaků funkcí v souboru JSON.

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

    // Define feature flags in a json file
    "FeatureManagement": {
        "FeatureT": {
            "EnabledFor": [
                {
                    "Name": "AlwaysOn"
                }
            ]
        },
        "FeatureU": {
            "EnabledFor": []
        },
        "FeatureV": {
            "EnabledFor": [
                {
                    "Name": "TimeWindow",
                    "Parameters": {
                        "Start": "Wed, 01 May 2019 13:59:59 GMT",
                        "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                    }
                }
            ]
        }
    }
}

Část FeatureManagement dokumentu JSON se používá konvencí k načtení nastavení příznaku funkce. V předchozí části vidíme tři různé funkce. Funkce definují filtry funkcí pomocí EnabledFor vlastnosti. V filtrech funkcí pro FeatureT, vidíme AlwaysOn. Tento filtr funkcí je integrovaný a pokud je zadaný, funkci vždy povolí. AlwaysOn Filtr funkcí nevyžaduje žádnou konfiguraci, takže má Name pouze vlastnost. FeatureU nemá ve své EnabledFor vlastnosti žádné filtry, a proto se nikdy nepovolí. Všechny funkce, které spoléhají na povolení této funkce, nebudou přístupné, pokud filtry funkcí zůstanou prázdné. Jakmile se ale přidá filtr funkcí, který funkci povolí, může začít fungovat. FeatureV určuje filtr funkcí s názvem TimeWindow. Toto je příklad konfigurovatelného filtru funkcí. V příkladu vidíme, že filtr má Parameters vlastnost. Slouží ke konfiguraci filtru. V tomto případě se konfigurují počáteční a koncové časy aktivní funkce.

Podrobné schéma oddílu FeatureManagement najdete tady.

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

Deklarace zapnuto/vypnuto

Následující fragment kódu ukazuje alternativní způsob definování funkce, kterou lze použít pro funkce zapnuto/vypnuto.

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

    // Define feature flags in config file
    "FeatureManagement": {
        "FeatureT": true, // On feature
        "FeatureX": false // Off feature
    }
}

Typ požadavku

Vlastnost RequirementType příznaku funkce se používá k určení, jestli filtry mají použít Any nebo All logiku při vyhodnocování stavu funkce. Pokud RequirementType 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 RequirementType procházení. Za prvé, pokud nejsou k dispozici žádné filtry, je tato funkce zakázaná. Potom se filtry funkcí procházejí, dokud se některý z filtrů nerozhodne, že by měla být tato funkce zakázaná. Pokud žádný filtr neukazuje, že by funkce měla být zakázaná, považuje se za povolenou.

"FeatureW": {
    "RequirementType": "All",
    "EnabledFor": [
        {
            "Name": "TimeWindow",
            "Parameters": {
                "Start": "Mon, 01 May 2023 13:59:59 GMT",
                "End": "Sat, 01 Jul 2023 00:00:00 GMT"
            }
        },
        {
            "Name": "Percentage",
            "Parameters": {
                "Value": "50"
            }
        }
    ]
}

V předchozím příkladu určuje hodnotu RequirementType All, což znamená, FeatureW že všechny jeho filtry musí být vyhodnoceny jako true, aby byla funkce 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í Microsoftu

Knihovna pro správu funkcí podporuje také použití deklarování Microsoft Feature Management schema příznaků funkcí. Toto schéma je nezávislé na původu a podporuje ho všechny knihovny pro správu funkcí Microsoftu.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {  
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Mon, 01 May 2023 13:59:59 GMT",
                                "End": "Sat, 01 Jul 2023 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Poznámka:

feature_management Pokud oddíl najdete v konfiguraci, FeatureManagement oddíl se ignoruje.

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 ho všechny knihovny pro správu funkcí Microsoftu.

Níže máme příklad deklarování příznaků 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 není k dispozici, conditions je tato funkce zapnutá. Pokud jsou conditions a 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. Toto je příklad konfigurovatelného filtru funkcí. V příkladu vidíme, že filtr má Parameters 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_type conditions 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 bude zakázána. 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 neuvádí, že by měla být funkce zakázaná, bude považována 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 předchozím příkladu určuje hodnotu requirement_type All, což znamená, FeatureW že všechny jeho filtry musí být vyhodnoceny jako true, aby byla funkce povolena. V tomto případě bude tato funkce povolena 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 nebudou pro schéma správy funkcí .NET podporované nové funkce včetně variant a telemetrie.

Poznámka:

Pokud se v konfiguraci nachází příznak funkce napsaný Microsoft Feature Management schema pomocí, všechny příznaky funkcí napsané pomocí .NET feature management schema budou ignorovány.

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. To se provádí metodou IFeatureManager' IsEnabledAsync .

…
IFeatureManager 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 IFeatureManager získat prostřednictvím injektáže závislostí.

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;
    
    public HomeController(IFeatureManager 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. Tím zajistíte, ž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. To lze provést pomocí , FeatureGateAttributekterý lze najít v Microsoft.FeatureManagement.Mvc oboru názvů.

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

Výše HomeController uvedené je vrátné 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ýše Index uvedená 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 blokovány, protože nejsou povoleny žádné funkce, které určuje, bude vyvolána zaregistrovaná IDisabledFeaturesHandler akce. Ve výchozím nastavení je zaregistrovaná minimalická obslužná rutina, která vrací http 404. To je možné přepsat pomocí příznaku IFeatureManagementBuilder funkce při registraci příznaků.

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

<feature name="FeatureX">
  <p>This can only be seen if 'FeatureX' is enabled.</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í jenom 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>

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

<feature name="FeatureX,FeatureY">
  <p>This can only be seen if '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í lze přepsat přidáním atributu requirement , jak je vidět v následujícím příkladu.

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

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í jenom 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. To lze provést přidáním pomocné rutiny 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");
});

Výše uvedený 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. To lze provést 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 tomu 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 FeatureFilterEvaluationContext IFeatureFilter.EvaluateAsync.

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

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

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

To 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.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();
    …
}

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í. To se provádí pomocí IFeatureManager.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 IFeatureManager.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á se TargetingFilter s metodou WithTargeting , která je podrobně popsána Targeting v následující čá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 Dailyhodnotu .
    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 Weeklyhodnotu .
    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 .

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

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í níže. 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í. Tím zabráníte 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:

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

Tato strategie pro zavádění funkce je integrovaná do 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

Typ implementace používaný pro ITargetingContextAccessor službu musí implementovat aplikace, která používá filtr cílení. Tady je příklad nastavení správy funkcí ve webové aplikaci pro použití TargetingFilter s implementací volaného ITargetingContextAccessor HttpContextTargetingContextAccessor.

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

Kontextové přístupové objekty cílení a TargetingFilter jsou registrovány voláním WithTargeting<T> na IFeatureManagementBuilder.

ITargetingContextAccessor

K použití TargetingFilter ve webové aplikaci se vyžaduje implementace ITargetingContextAccessor . Důvodem je to, že při vyhodnocování cílení se vyžadují informace, jako je například aktuálně vyhodnocený uživatel. Tyto informace se označují jako kontext cílení. Různé webové 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říklad, který extrahuje informace o kontextu cílení z kontextu HTTP aplikace, je součástí ukázkového projektu FeatureFlagDemo . Tato metoda 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 To je podporováno pomocí nástroje 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 IFeatureManager.IsEnabledAsync , aby bylo možné vyhodnotit a zapnout funkci.

IFeatureManager 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. To je užitečné v případě, že se funkce zavádí do skupiny uživatelů, ale několik uživatelů nebo skupin musí být vyloučeno ze zavádění. 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 buď pomocí vlastností configuration_reference , nebo configuration_value pomocí těchto vlastností. configuration_reference je cesta řetězce, která odkazuje na část aktuální konfigurace, která obsahuje deklaraci příznaku funkce. configuration_value je vložená konfigurace, která může být řetězec, číslo, logická hodnota nebo objekt konfigurace. Pokud jsou zadány obě, configuration_value použije se. Pokud není zadána žádná hodnota, 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_reference": "ShoppingCart:Big" 
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    },

    "ShoppingCart": {
        "Big": {
            "Size": 600,
            "Color": "green"
        },
        "Small": {
            "Size": 300,
            "Color": "gray"
        }
    }
}

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_reference": "ShoppingCart:Big" 
    },  
    { 
        "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. To lze provést 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. Pokud volající kontroluje, jestli je povolený příznak s variantami, správce funkcí zkontroluje, jestli je varianta přiřazená aktuálnímu uživateli nastavená tak, aby přepsala výsledek. To 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 enabled false 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. Toho se dosahuje 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). Níže najdete 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 IAlgorithm IVariantServiceProvider 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 podporuje generování těchto událostí prostřednictvím vydavatelů telemetrie. Jeden nebo mnoho vydavatelů telemetrie je možné zaregistrovat k publikování událostí při každém vyhodnocení příznaků 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, to se provádí 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. To je indikováno telemetry objektem, 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í vydavatelé telemetrie

Vlastní zpracování telemetrie příznaků funkcí je možné implementací ITelemetryPublisher a registrací ve Správci funkcí. Pokaždé, když se vyhodnotí příznak funkce s povolenou telemetrií, získá vydavatel registrované telemetrie možnost publikovat odpovídající událost vyhodnocení.

public interface ITelemetryPublisher
{
    ValueTask PublishEvent(EvaluationEvent evaluationEvent, CancellationToken cancellationToken);
}

Typ EvaluationEvent najdete tady pro referenci.

Registrace vydavatelů telemetrie se provádí při volání AddFeatureManagement(). Tady je příklad nastavení správy funkcí pro generování telemetrie s implementací volaného ITelemetryPublisher MyTelemetryPublisher.

builder.services
    .AddFeatureManagement()
    .AddTelemetryPublisher<MyTelemetryPublisher>();

Vydavatel telemetrie Application Insights

Balíček Microsoft.FeatureManagement.Telemetry.ApplicationInsights poskytuje integrovanou implementaci vydavatele telemetrie, která odesílá data vyhodnocení příznaků funkcí do Application Insights. Pokud to chcete využít, přidejte odkaz na balíček a zaregistrujte vydavatele telemetrie Application Insights, jak je znázorněno níže.

builder.services
    .AddFeatureManagement()
    .AddTelemetryPublisher<ApplicationInsightsTelemetryPublisher>();

Poznámka:

Základní Microsoft.FeatureManagement balíček neobsahuje tohoto vydavatele telemetrie.

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

Požadavek

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

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 IFeatureManager 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í IFeatureManagerSnapshot. IFeatureManagerSnapshot lze načíst stejným způsobem jako IFeatureManager. IFeatureManagerSnapshot implementuje rozhraní , IFeatureManagerale 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 IFeatureDefinitionProvider InMemoryFeatureDefinitionProvider.

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

Pokud chcete zjistit, jak spouštět experimenty s příznaky variant funkcí, pokračujte následujícím kurzem.

Spouštění experimentů s příznaky variant funkcí