Megosztás a következőn keresztül:

.NET-szolgáltatáskezelés

  • Cikk

Microsoft.FeatureManagement
Microsoft.FeatureManagement.AspNetCore

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

A .NET szolgáltatásfelügyeleti kódtára lehetővé teszi az alkalmazásfunkciók funkciójelzők alapján történő fejlesztését és elérhetővé cióját. Egy új funkció fejlesztése után számos alkalmazás speciális követelményekkel rendelkezik, például mikor és milyen feltételek mellett kell engedélyezni a funkciót. Ez a kódtár lehetővé teszi ezeknek a kapcsolatoknak a meghatározását, valamint a közös .NET-kódmintákba való integrálást, hogy lehetővé tegye ezeknek a funkcióknak a feltárást.

A funkciójelzők lehetővé teszik, hogy a .NET és ASP.NET Core-alkalmazások dinamikusan kapcsolják be vagy ki a funkciókat. A fejlesztők olyan egyszerű használati esetekben is használhatnak funkciójelzőket, mint például feltételes utasítások a speciálisabb forgatókönyvekhez, például útvonalak feltételes hozzáadásához vagy MVC-szűrőkhöz. A funkciójelzők a .NET Core konfigurációs rendszerére épülnek. Bármely .NET Core-konfigurációszolgáltató képes a funkciójelzők gerinceként viselkedni.

A .NET szolgáltatásfelügyeleti kódtár használatának néhány előnye:

  • A funkciókezelés általános konvenciója

  • Alacsony belépési korlát

    • Beépített IConfiguration
    • Támogatja a JSON-fájlfunkció-jelző beállítását

  • Funkciójelölő élettartamának kezelése

    • A konfigurációs értékek valós időben változhatnak; A funkciójelzők a teljes kérelemben konzisztensek lehetnek

  • Az egyszerű és összetett forgatókönyvek lefedve

    • Szolgáltatások be- és kikapcsolása deklaratív konfigurációs fájlon keresztül
    • A szolgáltatás állapotának dinamikus kiértékelése a kiszolgáló hívása alapján

  • API-bővítmények ASP.NET Core- és MVC-keretrendszerhez

    • Útválasztás
    • Szűrők
    • Műveletattribútumok

    A .NET szolgáltatásfelügyeleti kódtára nyílt forráskód. További információkért látogasson el a GitHub-adattárba.

Funkciójelzők

A funkciójelzők két részből állnak, egy névből és a funkció bekapcsolásához használt funkciószűrők listájából.

Funkciószűrők

A funkciószűrők meghatároznak egy forgatókönyvet, amikor engedélyezni kell egy funkciót. Ha a rendszer kiértékel egy funkciót, hogy be- vagy kikapcsolt állapotban van-e, a szolgáltatásszűrők listája mindaddig bejáródik, amíg az egyik szűrő el nem dönti, hogy engedélyezni kell-e a funkciót. Ezen a ponton a szolgáltatás engedélyezve van, és a funkciószűrők leállnak. Ha nincs funkciószűrő, amely azt jelzi, hogy engedélyezni kell a funkciót, akkor az le van tiltva.

Ilyen például egy Microsoft Edge böngészőfunkció-szűrő. Ez a funkciószűrő aktiválja azokat a funkciókat, amelyekhez csatolva van, amíg a Microsoft Edge-ből http-kérés érkezik.

Funkciójelző konfigurálása

A .NET Core konfigurációs rendszer a funkciójelzők állapotának meghatározására szolgál. Ennek a rendszernek az alapja .IConfiguration Bármely szolgáltató IConfiguration használható a funkciójelző-kódtár szolgáltatásállapot-szolgáltatójaként. Ez a rendszer appsettings.json és Azure-alkalmazás konfigurációs forgatókönyveket tesz lehetővé.

Funkciójelző deklarációja

A szolgáltatásfelügyeleti kódtár támogatja a appsettings.json funkciójelző forrásként, mivel a .NET Core rendszerszolgáltatója IConfiguration . Az alábbiakban egy példa látható arra a formátumra, amellyel egy json-fájlban beállíthat funkciójelzőket.

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

A FeatureManagement json-dokumentum szakaszát a konvenciók a funkciójelző beállításainak betöltésére használják. A fenti szakaszban három különböző funkciót láthatunk. A funkciók a tulajdonság használatával határozzák meg a EnabledFor funkciószűrőket. A funkciószűrőkben FeatureTa következő látható AlwaysOn: . Ez a funkciószűrő beépített, és ha meg van adva, mindig engedélyezi a funkciót. A AlwaysOn funkciószűrő nem igényel konfigurációt, ezért csak a tulajdonsága Name van. FeatureU nem rendelkezik szűrőkkel a EnabledFor tulajdonságában, így soha nem lesz engedélyezve. A funkció engedélyezésére támaszkodó funkciók nem lesznek elérhetők mindaddig, amíg a funkciószűrők üresek maradnak. Amint azonban hozzáadunk egy olyan funkciószűrőt, amely lehetővé teszi a funkció működését. FeatureV a nevű szolgáltatásszűrőt TimeWindowadja meg. Ez egy konfigurálható funkciószűrő példája. A példában láthatjuk, hogy a szűrő rendelkezik tulajdonságával Parameters . Ez a szűrő konfigurálására szolgál. Ebben az esetben a szolgáltatás aktiválásának kezdő és befejező időpontjai konfigurálva vannak.

A szakasz részletes sémája FeatureManagement itt található.

Speciális: A ":" kettőspont használata tiltott a funkciójelzők neveiben.

Be- és kikapcsolási deklaráció

Az alábbi kódrészlet egy alternatív módszert mutat be a be- és kikapcsolható funkciókhoz használható funkciók definiálására.

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

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

RequirementType

A RequirementType funkciójelölő tulajdonsága határozza meg, hogy a szűrőknek használniuk Any kell-e vagy All logikát a funkció állapotának kiértékelésekor. Ha RequirementType nincs megadva, az alapértelmezett érték a következő Any.

  • Any azt jelenti, hogy csak egy szűrőnek kell igaznak lennie ahhoz, hogy a funkció engedélyezve legyen.
  • All azt jelenti, hogy minden szűrőnek igaznak kell lennie ahhoz, hogy a funkció engedélyezve legyen.

A RequirementType bejárás All módosítása. Először is, ha nincsenek szűrők, a funkció le van tiltva. Ezután a szolgáltatásszűrők mindaddig bejáródnak, amíg az egyik szűrő úgy nem dönt, hogy le kell tiltani a funkciót. Ha nincs szűrő, amely azt jelzi, hogy a funkciót le kell tiltani, az engedélyezettnek minősül.

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

A fenti példában egy értéket ad megAllRequirementType, ami azt jelenti, FeatureW hogy az összes szűrőjének igaznak kell lennie ahhoz, hogy a funkció engedélyezve legyen. Ebben az esetben a funkció a felhasználók 50%-a számára engedélyezve van a megadott időkeretben.

Microsoft Szolgáltatáskezelési séma

A szolgáltatásfelügyeleti kódtár a funkciójelzők deklarálásához is támogatja a Microsoft Feature Management schema használatát. Ez a séma nyelvi agnosztikus eredetű, és minden Microsoft-szolgáltatásfelügyeleti kódtár támogatja.

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

Feljegyzés

Ha a feature_management szakasz megtalálható a konfigurációban, a FeatureManagement szakasz figyelmen kívül lesz hagyva.

A szolgáltatásfelügyeleti kódtár támogatja a appsettings.json funkciójelző forrásként, mivel a .NET Core rendszerszolgáltatója IConfiguration . A funkciójelzők deklarálása a Microsoft Feature Management schema. Ez a séma nyelvi agnosztikus eredetű, és minden Microsoft-szolgáltatásfelügyeleti kódtár támogatja.

Az alábbiakban egy json-fájlban található funkciójelzők deklarálására mutatunk példát.

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

A feature_management json-dokumentum szakaszát a konvenciók a funkciójelző beállításainak betöltésére használják. A funkciójelző objektumokat a feature_flags szakasz alatti feature_management tömbben kell listázni. A fenti szakaszban láthatjuk, hogy három különböző funkciót biztosítottunk. Egy funkciójelölő rendelkezik és enabled tulajdonságokat tartalmazid. A id funkciójelző azonosításához és hivatkozásához használt név. A enabled tulajdonság a funkciójelző engedélyezett állapotát adja meg. A funkció ki van kapcsolva , ha enabled hamis. Ha enabled igaz, akkor a funkció állapota a conditions. Ha nincs conditions , akkor a funkció be van kapcsolva. Ha vannak conditions , és teljesülnek, akkor a funkció be van kapcsolva. Ha vannak conditions , és nem teljesülnek, akkor a funkció ki van kapcsolva. A conditions tulajdonság deklarálja a funkció dinamikus engedélyezéséhez használt feltételeket. A funkciók meghatározzák a funkciószűrőket a client_filters tömbben. FeatureV a nevű szolgáltatásszűrőt Microsoft.TimeWindowadja meg. Ez egy konfigurálható funkciószűrő példája. A példában láthatjuk, hogy a szűrő rendelkezik tulajdonságával Parameters . Ez a szűrő konfigurálására szolgál. Ebben az esetben a szolgáltatás aktiválásának kezdő és befejező időpontjai konfigurálva vannak.

Speciális: A ":" kettőspont használata tiltott a funkciójelzők neveiben.

RequirementType

A requirement_type tulajdonság azt conditions határozza meg, hogy a szűrők használnak-e Any vagy All logikát a funkció állapotának kiértékelésekor. Ha requirement_type nincs megadva, az alapértelmezett érték a következő Any.

  • Any azt jelenti, hogy csak egy szűrőnek kell igaznak lennie ahhoz, hogy a funkció engedélyezve legyen.
  • All azt jelenti, hogy minden szűrőnek igaznak kell lennie ahhoz, hogy a funkció engedélyezve legyen.

A requirement_type bejárás All módosítása. Először is, ha nincs szűrő, a funkció le lesz tiltva. Ha vannak szűrők, akkor a funkciószűrők mindaddig bejáródnak, amíg az egyik szűrő úgy nem dönt, hogy le kell tiltani a funkciót. Ha nincs szűrő, amely azt jelzi, hogy a funkciót le kell tiltani, akkor az engedélyezve lesz.

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

A fenti példában egy értéket ad megAllrequirement_type, ami azt jelenti, FeatureW hogy az összes szűrőjének igaznak kell lennie ahhoz, hogy a funkció engedélyezve legyen. Ebben az esetben a funkció a felhasználók 50%-a számára lesz engedélyezve a megadott időkeretben.

.NET szolgáltatáskezelési séma

A korábbi verziókban a szolgáltatásfelügyeleti kódtár elsődleges sémája a .NET feature management schema. A 4.0.0-s verziótól kezdődően a .NET szolgáltatáskezelési sémája nem támogatja az új funkciókat, köztük a változatokat és a telemetriát.

Feljegyzés

Ha a konfigurációban megtalálható egy funkciójelölő Microsoft Feature Management schema , a rendszer figyelmen kívül hagyja a vele .NET feature management schema írt funkciójelzőt.

Felhasználás

A funkciókezelés alapszintű formája annak ellenőrzése, hogy engedélyezve van-e a funkciójelző, majd az eredmény alapján hajt végre műveleteket. Ez a IFeatureManagermódszeren IsEnabledAsync keresztül történik.

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

Szolgáltatásregisztráció

A funkciókezelés a .NET Core-függőséginjektáláson alapul. A szolgáltatásfelügyeleti szolgáltatásokat standard konvenciók használatával regisztrálhatjuk.

using Microsoft.FeatureManagement;

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

Alapértelmezés szerint a szolgáltatáskezelő lekéri a funkciójelző konfigurációját a .NET Core konfigurációs adatainak "FeatureManagement" szakaszából. Ha a "FeatureManagement" szakasz nem létezik, a konfiguráció üresnek minősül.

Feljegyzés

Azt is megadhatja, hogy a szolgáltatásjelző konfigurációját egy másik konfigurációs szakaszból kell lekérni AddFeatureManagementa szakasz átadásával. Az alábbi példa arra utasítja a szolgáltatáskezelőt, hogy inkább olvassa fel a "MyFeatureFlags" nevű másik szakaszt:

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

Függőséginjektálás

Ha a szolgáltatásfelügyeleti kódtárat MVC-vel használja, az IFeatureManager függőséginjektálással szerezhető be.

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

Hatókörön belüli szolgáltatásfelügyeleti szolgáltatások

A AddFeatureManagement metódus az alkalmazáson belül egyetlen egységként adja hozzá a szolgáltatásfelügyeleti szolgáltatásokat, de vannak olyan helyzetek, amikor a szolgáltatásfelügyeleti szolgáltatások hatókörön belüli szolgáltatásként való hozzáadásához szükség lehet rá. Előfordulhat például, hogy a felhasználók olyan funkciószűrőket szeretnének használni, amelyek hatókörön belüli szolgáltatásokat használnak környezeti információkhoz. Ebben az esetben inkább a AddScopedFeatureManagement metódust kell használni. Ez biztosítja, hogy a szolgáltatásfelügyeleti szolgáltatások, köztük a szolgáltatásszűrők hatókörön belüli szolgáltatásokként legyenek hozzáadva.

services.AddScopedFeatureManagement();

ASP.NET Core-integráció

A szolgáltatásfelügyeleti kódtár a ASP.NET Core és az MVC funkcióit biztosítja a webalkalmazások gyakori funkciójelző-forgatókönyveinek engedélyezéséhez. Ezek a képességek a Microsoft.FeatureManagement.AspNetCore NuGet csomagra való hivatkozással érhetők el.

Vezérlők és műveletek

Az MVC-vezérlő és a műveletek végrehajtásához engedélyezni kell egy adott funkciót vagy a funkciók listájának egyikét. Ez egy , a Microsoft.FeatureManagement.Mvc névtérben található használatával végezhető elFeatureGateAttribute.

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

A HomeController fenti kaput a "FeatureX" határozza meg. A "FeatureX"-et engedélyezni kell, mielőtt bármilyen műveletet végrehajtanának a HomeController tartalmai.

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

A Index fenti MVC művelet végrehajtásához engedélyezni kell a "FeatureX" műveletet.

Letiltott műveletkezelés

Ha egy MVC-vezérlő vagy művelet le van tiltva, mert az általa megadott funkciók egyike sem engedélyezett, a rendszer meghív egy regisztráltat IDisabledFeaturesHandler . Alapértelmezés szerint egy minimalista kezelő van regisztrálva, amely HTTP 404-et ad vissza. Ezt felül lehet bírálni a IFeatureManagementBuilder funkciójelzők regisztrálásakor.

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

Nézet

Az MVC-nézetekben <feature> címkék használhatók a tartalom feltételes megjelenítésére attól függően, hogy engedélyezve van-e egy funkció.

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

Letilthatja a címke súgójának kiértékelését is, hogy tartalmat jelenítsen meg, ha egy funkció vagy funkciókészlet le van tiltva. Az alábbi példában megadott negate="true" tartalom csak akkor jelenik meg, ha FeatureX le van tiltva.

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

A <feature> címke több funkcióra is hivatkozhat az attribútumban name található szolgáltatások vesszővel tagolt listájának megadásával.

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

Alapértelmezés szerint az összes felsorolt funkciót engedélyezni kell a funkciócímke megjelenítéséhez. Ezt a viselkedést felül lehet bírálni az requirement alábbi példában látható attribútum hozzáadásával.

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

Az MVC-nézetekben <feature> a címkék a tartalom feltételes megjelenítésére használhatók attól függően, hogy engedélyezve van-e egy szolgáltatás, vagy egy funkció adott változata van-e hozzárendelve. További információkért tekintse meg a változatok szakaszt .

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

Letilthatja a címke súgójának kiértékelését is, hogy tartalmat jelenítsen meg, ha egy funkció vagy funkciókészlet le van tiltva. Az alábbi példában megadott negate="true" tartalom csak akkor jelenik meg, ha FeatureX le van tiltva.

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

A <feature> címke több jellemzőre/változatra is hivatkozhat az attribútumban name/variant található funkciók/változatok vesszővel tagolt listájának megadásával.

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

Feljegyzés

Ha variant meg van adva, csak egy funkciót kell megadni.

Alapértelmezés szerint az összes felsorolt funkciót engedélyezni kell a funkciócímke megjelenítéséhez. Ezt a viselkedést felül lehet bírálni az requirement alábbi példában látható attribútum hozzáadásával.

Feljegyzés

Ha az egyiket requirement And egy hibával variant együtt használja a rendszer, akkor több változatot soha nem lehet hozzárendelni.

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

A <feature> címke használatához egy címkesegítőre van szükség. Ezt úgy teheti meg, hogy hozzáadja a szolgáltatásfelügyeleti címke segédjét a ViewImports.cshtml fájlhoz.

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC-szűrők

Az MVC műveletszűrők beállíthatók a szolgáltatás állapota alapján feltételes végrehajtásra. Ez az MVC-szűrők funkcióérzékeny módon történő regisztrálásával végezhető el. A szolgáltatásfelügyeleti folyamat támogatja az aszinkron MVC-műveleti szűrőket, amelyek implementálják IAsyncActionFilterazokat.

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

A fenti kód hozzáad egy MVC-szűrőt.SomeMvcFilter Ez a szűrő csak akkor aktiválódik az MVC-folyamaton belül, ha a "FeatureX" engedélyezve van.

Razor Pages

Az MVC Razor-lapok futtatásához engedélyezni kell egy adott funkciót vagy bármely funkciólistát. Ez egy , a Microsoft.FeatureManagement.Mvc névtérben található használatával végezhető elFeatureGateAttribute.

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

A fenti kód beállít egy Razor-oldalt, amely megköveteli a "FeatureX" engedélyezését. Ha a funkció nincs engedélyezve, a lap HTTP 404 (NotFound) eredményt hoz létre.

Razor-oldalakon való használat esetén a FeatureGateAttribute lapkezelő típusára kell helyezni. Nem helyezhető el az egyes kezelőmetszeteken.

Alkalmazásépítés

A szolgáltatásfelügyeleti kódtár olyan alkalmazáságak és köztes szoftverek hozzáadására használható, amelyek a funkcióállapot alapján feltételesen futnak.

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

A fenti hívással az alkalmazás hozzáad egy köztes szoftver összetevőt, amely csak akkor jelenik meg a kérelemfolyamatban, ha a "FeatureX" funkció engedélyezve van. Ha a szolgáltatás futásidőben engedélyezve van/le van tiltva, a köztes szoftverfolyamat dinamikusan módosítható.

Ez kiépíti az általánosabb képességet, hogy a teljes alkalmazást elágaztathassa egy funkció alapján.

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

Funkciószűrő implementálása

A szolgáltatásszűrők létrehozásával lehetővé válik a szolgáltatások engedélyezése az Ön által meghatározott feltételek alapján. A funkciószűrő implementálásához az IFeatureFilter interfészt végre kell hajtani. IFeatureFilter egyetlen metódussal rendelkezik EvaluateAsync. Ha egy szolgáltatás megadja, hogy engedélyezhető egy szolgáltatásszűrőhöz, a EvaluateAsync metódus meghívása történik. Ha EvaluateAsync visszaadja true, az azt jelenti, hogy a funkciót engedélyezni kell.

Az alábbi kódrészlet bemutatja, hogyan adhat hozzá testre szabott funkciószűrőt MyCriteriaFilter.

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

A szolgáltatásszűrők regisztrálva vannak a IFeatureManagementBuilder visszaadott AddFeatureManagementfeladó meghívásávalAddFeatureFilter<T>. Ezek a szolgáltatásszűrők hozzáféréssel rendelkeznek a szolgáltatásgyűjteményben található szolgáltatásokhoz, amelyek funkciójelölők hozzáadására szolgálnak. A függőséginjektálás a szolgáltatások lekérésére használható.

Feljegyzés

Ha a szűrőkre a funkciójelölő beállításai hivatkoznak (például appsettings.json), a típusnév Szűrő részét ki kell hagyni. További információkért lásd a szakaszt Filter Alias Attribute .

Paraméteres funkciószűrők

Egyes funkciószűrőkhöz paraméterek szükségesek annak eldöntéséhez, hogy be kell-e kapcsolni egy funkciót. Előfordulhat például, hogy egy böngészőfunkció-szűrő bekapcsol egy funkciót bizonyos böngészőkben. Előfordulhat, hogy az Edge és a Chrome böngészők engedélyezik a funkciót, míg a Firefox nem. Ehhez egy funkciószűrőt úgy lehet megtervezni, hogy paramétereket várjon. Ezek a paraméterek a szolgáltatáskonfigurációban lesznek megadva, a kódban pedig a FeatureFilterEvaluationContext paraméteren IFeatureFilter.EvaluateAsynckeresztül érhetők el.

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 nevű tulajdonsága Parametersvan. Ezek a paraméterek egy nyers konfigurációt jelölnek, amellyel a szolgáltatásszűrő eldöntheti, hogyan kell értékelni, hogy engedélyezve legyen-e a szolgáltatás. Ha ismét példaként szeretné használni a böngészőfunkció-szűrőt, a szűrővel Parameters kinyerheti a funkcióhoz megadott engedélyezett böngészők készletét, majd ellenőrizheti, hogy a kérést az adott böngészők egyikéből küldi-e el.

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

Szűrő aliasattribútum

Ha egy szolgáltatásszűrő regisztrálva van egy funkciójelölőhöz, a konfigurációban használt alias a funkciószűrő típusának neve, ha van ilyen, eltávolítva a Szűrő utótaggal. A konfigurációban például MyCriteriaFilter MyCriteria-nak nevezik.

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

Ezt felül lehet bírálni a FilterAliasAttribute. Ezzel az attribútummal egy funkciószűrővel deklarálható az a név, amelyet a konfigurációban használni kell a funkciószűrőre való hivatkozáshoz egy funkciójelölőn belül.

Hiányzó funkciószűrők

Ha egy szolgáltatás úgy van konfigurálva, hogy engedélyezve legyen egy adott szolgáltatásszűrőhöz, és a funkciószűrő nincs regisztrálva, a szolgáltatás kiértékelése kivételt eredményez. A kivétel letiltható a szolgáltatásfelügyeleti beállítások használatával.

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

HttpContext használata

A funkciószűrők kiértékelhetik, hogy engedélyezni kell-e egy funkciót egy HTTP-kérés tulajdonságai alapján. Ezt a HTTP-környezet vizsgálatával hajtja végre. A funkciószűrők a függőséginjektáláson IHttpContextAccessor keresztüli beolvasással hivatkozhatnak a HTTP-környezetre.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

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

Az IHttpContextAccessor indításkor hozzá kell adni a függőséginjektáló tárolóhoz, hogy elérhető legyen. Az alábbi módszerrel regisztrálható IServiceCollection .

public void ConfigureServices(IServiceCollection services)
{
    …
    services.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();
    …
}

Speciális: IHttpContextAccessor/HttpContext nem használható a kiszolgálóoldali Blazor-alkalmazások Razor-összetevőiben. A Http-környezet Blazor-alkalmazásokban való átadásának ajánlott módszere az adatok hatókörrel rendelkező szolgáltatásba való másolása. A Blazor-alkalmazások AddScopedFeatureManagement esetében a szolgáltatásfelügyeleti szolgáltatások regisztrálásához kell használni. További információkért lásd a szakaszt Scoped Feature Management Services .

Környezet biztosítása a funkcióértékeléshez

A konzolalkalmazásokban nincs olyan környezeti környezet, mint amilyen például HttpContext az, hogy a funkciószűrők be- vagy kikapcsolhatják-e a funkciót. Ebben az esetben az alkalmazásoknak egy környezetet képviselő objektumot kell biztosítaniuk a szolgáltatásfelügyeleti rendszerbe a funkciószűrők általi használathoz. Ezt a következővel IFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext)végezheti el: . A funkciókezelőnek biztosított appContext objektumot a funkciószűrők használhatják a funkció állapotának kiértékeléséhez.

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

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

Környezeti funkciószűrők

A környezetfüggő funkciószűrők implementálják az interfészt IContextualFeatureFilter<TContext> . Ezek a speciális funkciószűrők kihasználhatják a meghíváskor IFeatureManager.IsEnabledAsync<TContext> átadott környezetet. A TContext típusparaméter azt írja le, IContextualFeatureFilter<TContext> hogy a szűrő milyen környezettípust képes kezelni. Ez lehetővé teszi egy környezetfüggő funkciószűrő fejlesztőjének, hogy leírja, mi szükséges azok számára, akik használni szeretnék. Mivel minden típus az objektum leszármazottja, egy implementálható IContextualFeatureFilter<object> szűrő bármilyen megadott környezethez hívható meg. Ha egy konkrétabb környezeti funkciószűrőre szeretne példát szemléltetni, fontolja meg az engedélyezett funkciók használatát, ha egy fiók szerepel az engedélyezett fiókok konfigurált listájában.

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

Láthatjuk, hogy a AccountIdFilter szükséges objektumnak meg kell adnia egy olyan objektumot, amely implementálva IAccountContext van a funkció állapotának kiértékeléséhez. A szolgáltatásszűrő használatakor a hívónak gondoskodnia kell arról, hogy az átadott objektum implementálva legyen IAccountContext.

Feljegyzés

Csak egyetlen funkciószűrő felület implementálható egyetlen típussal. Ha olyan funkciószűrőt próbál hozzáadni, amely egynél több funkciószűrő felületet implementál, az eredmény egy ArgumentException.

Környezetfüggő és nem környezetfüggő szűrők használata ugyanazzal az aliassal

IFeatureFilter A szűrők ugyanazt az aliast használhatják és IContextualFeatureFilter megoszthatják. Pontosabban egy szűrőaliast 0, 1 IFeatureFilter és 0 vagy N IContextualFeatureFilter<ContextType>oszthat meg, amennyiben legfeljebb egy szűrő használható.ContextType

Az alábbi szakasz a szűrő kiválasztásának folyamatát ismerteti, ha az azonos nevű környezetfüggő és nem környezetfüggő szűrők regisztrálva vannak egy alkalmazásban.

Tegyük fel, hogy van egy nem környezetfüggő szűrője, FilterA valamint két környezetfüggő szűrője FilterB , valamint a FilterC, amelyek elfogadják TypeB , illetve TypeC a környezeteket. Mindhárom szűrő ugyanazt az aliast SharedFilterNamehasználja.

Emellett rendelkezik egy funkciójelzővel MyFeature is, amely a szolgáltatásszűrőt SharedFilterName használja a konfigurációjában.

Ha mindhárom szűrő regisztrálva van:

  • Az IsEnabledAsync("MyFeature" hívása esetén a rendszer a FilterA funkciójelző kiértékelésére szolgál.
  • Az IsEnabledAsync("MyFeature", context) hívása esetén a rendszer a környezet típusát TypeBFilterB használja. Ha a környezet típusa az, FilterC akkor a TypeCrendszer használja.
  • Az IsEnabledAsync("MyFeature", context) hívása esetén a rendszer a környezet típusát TypeFFilterA használja.

Beépített funkciószűrők

Van néhány funkciószűrő, amelyek a Microsoft.FeatureManagement csomaghoz tartoznak: PercentageFilter, TimeWindowFilterés ContextualTargetingFilter TargetingFilter. A rendszer az összes szűrőt automatikusan hozzáadja, ha a TargetingFilterszolgáltatáskezelést metódussal regisztráljákAddFeatureManagement. A TargetingFilter rendszer hozzáadja az WithTargeting alábbi szakaszban részletezett Targeting metódust.

Minden beépített funkciószűrő saját paraméterekkel rendelkezik. Íme a szolgáltatásszűrők listája a példákkal együtt.

Microsoft.Percentage

Ez a szűrő lehetővé teszi egy funkció engedélyezését egy megadott százalék alapján.

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

Microsoft.TimeWindow

Ez a szűrő lehetővé teszi egy szolgáltatás időkereten alapuló engedélyezését. Ha csak End a megadott érték van megadva, a szolgáltatás addig is be van kapcsolva. Ha csak Start meg van adva, a szolgáltatás az adott időpont után minden ponton figyelembe lesz véve.

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

Az időablak konfigurálható úgy, hogy rendszeresen ismétlődjön. Ez olyan helyzetekben lehet hasznos, amikor előfordulhat, hogy egy funkciót egy nap vagy egy hét bizonyos napjainak alacsony vagy nagy forgalmú időszakában kell bekapcsolni. Ha az egyes időablakokat ismétlődő időablakokként szeretné kibontani, az ismétlődési szabályt meg kell adni a Recurrence paraméterben.

Feljegyzés

Start és End mindkettőt meg kell adni az engedélyezéshez 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"
                    }
                }
            }
        }
    ]
}

A Recurrence beállítások két részből állnak: Pattern (milyen gyakran ismétlődik az időablak) és Range (mennyi ideig ismétlődik az ismétlődési minta).

Ismétlődési minta

Két lehetséges ismétlődési mintatípus létezik: Daily és Weekly. Egy időablak például "minden nap", "három naponta", "minden hétfőn" vagy "minden második pénteken" ismétlődhet.

A típustól függően a Pattern mezők bizonyos mezői kötelezőek, nem kötelezőek vagy figyelmen kívül hagyhatók.

  • Daily

    A napi ismétlődési minta miatt az időablak ismétlődik az egyes előfordulások közötti napok száma alapján.

    Tulajdonság Relevancia Leírás
    Típus Kötelező A beállításnak a Dailykövetkezőnek kell lennie: .
    Intervallum Választható Az egyes előfordulások közötti napok számát adja meg. Az alapértelmezett érték 1.

  • Weekly

    A heti ismétlődési minta miatt az időablak a hét ugyanazon napján vagy napjaiban ismétlődik az egyes előfordulások között eltelt hetek száma alapján.

    Tulajdonság Relevancia Leírás
    Típus Kötelező A beállításnak a Weeklykövetkezőnek kell lennie: .
    DaysOfWeek Kötelező Megadja, hogy a hét mely napjain történjen az esemény.
    Intervallum Választható Az egyes előfordulások közötti hetek számát adja meg. Az alapértelmezett érték 1.
    FirstDayOfWeek Választható Megadja, hogy melyik nap számít a hét első napjának. Az alapértelmezett érték Sunday.

    Az alábbi példa minden második hétfőn és kedden megismétli az időablakot

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

Feljegyzés

Start Az ismétlődési mintának megfelelő érvényes első előfordulásnak kell lennie. Emellett az időablak időtartama nem lehet hosszabb, mint amilyen gyakran előfordul. Érvénytelen például, hogy naponta 25 órás időablak ismétlődik.

Ismétlődési tartomány

Három lehetséges ismétlődési tartománytípus létezik: NoEndés EndDate Numbered.

  • NoEnd

    A NoEnd tartomány miatt az ismétlődés határozatlan ideig ismétlődik.

    Tulajdonság Relevancia Leírás
    Típus Kötelező A beállításnak a NoEndkövetkezőnek kell lennie: .

  • EndDate

    A EndDate tartomány azt eredményezi, hogy az időablak minden olyan napon bekövetkezik, amely megfelel az alkalmazandó mintának a befejezési dátumig.

    Tulajdonság Relevancia Leírás
    Típus Kötelező A beállításnak a EndDatekövetkezőnek kell lennie: .
    EndDate Kötelező Megadja a minta alkalmazásának leállításának dátumát. Mindaddig, amíg az utolsó előfordulás kezdő időpontja a befejezési dátum elé esik, az előfordulás záró időpontja túllépheti azt.

    Az alábbi példa minden nap megismétli az időkeretet, amíg az utolsó előfordulás 2024. április 1-jén meg nem történik.

    "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

    A Numbered tartomány miatt az időablak rögzített számú alkalommal fordul elő (a minta alapján).

    Tulajdonság Relevancia Leírás
    Típus Kötelező A beállításnak a Numberedkövetkezőnek kell lennie: .
    NumberOfOccurrences Kötelező Az előfordulások számát adja meg.

    A következő példa megismétli az időkeretet hétfőn és kedden, amíg három esemény nem következik be, amelyek április 1-jén (hétfő), április 2-án (kedd) és április 8-án (hétfő) történnek.

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

Ismétlődési szabály létrehozásához mindkét Pattern Rangeszabályt meg kell adnia. Bármely mintatípus bármilyen tartománytípussal használható.

Speciális: A tulajdonság időzóna-eltolása Start az ismétlődési beállításokra lesz alkalmazva.

Microsoft.Targeting

Ez a szűrő lehetővé teszi egy szolgáltatás engedélyezését a célközönség számára. A célzás részletes magyarázatát az alábbi célzási szakasz ismerteti. A szűrőparaméterek közé tartoznak a Audience felhasználókat, csoportokat, kizárt felhasználókat/csoportokat leíró objektumok, valamint a szolgáltatáshoz hozzáféréssel rendelkező felhasználói bázis alapértelmezett százalékos aránya. A szakaszban felsorolt csoportobjektumoknak Groups azt is meg kell adniuk, hogy a csoport tagjainak hány százaléka rendelkezzen hozzáféréssel. Ha egy felhasználó közvetlenül vagy kizárt csoportban van megadva a Exclusion szakaszban, a szolgáltatás le van tiltva. Ellenkező esetben, ha egy felhasználó közvetlenül a Users szakaszban van megadva, vagy ha a felhasználó szerepel a csoport bevezetésének százalékos arányában, vagy ha a felhasználó az alapértelmezett bevezetési százalékra esik, akkor a felhasználónak engedélyezve lesz a 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"
                        ]
                    }
                }
            }
        }
    ]
}

Szolgáltatásszűrő aliasnévterei

Az összes beépített funkciószűrő-alias a funkciószűrő névterében Microsoft található. Ennek célja, hogy megakadályozza az azonos aliast használó más funkciószűrőkkel való ütközéseket. A szolgáltatásszűrő-névtér szegmenseit a "." karakter osztja fel. A szolgáltatásszűrőkre hivatkozhat teljes mértékben minősített aliasa, például Microsoft.Percentage az utolsó szegmens, amely esetében Microsoft.Percentage az .Percentage

Célcsoportkezelés

A célzás egy funkciókezelési stratégia, amely lehetővé teszi a fejlesztők számára, hogy fokozatosan új funkciókat vezessenek be a felhasználói bázisukra. A stratégia a célközönségként ismert felhasználók egy csoportjának megcélzására épül. A célközönség meghatározott felhasználókból, csoportokból, kizárt felhasználókból/csoportokból és a teljes felhasználói bázis meghatározott százalékából áll. A közönségbe felvett csoportok további bontásban, a teljes tagok százalékos arányára bonthatók.

Az alábbi lépések egy új bétaverziós funkció fokozatos bevezetésére mutatnak be példát:

  1. Jeff és Alicia egyes felhasználók számára hozzáférést kapnak a bétaverzióhoz
  2. Egy másik felhasználó, Mark, kéri, hogy jelentkezzen be, és szerepel benne.
  3. A "Ring1" nevű csoport felhasználóinak húsz százaléka szerepel a bétaverzióban.
  4. A bétaverzióban szereplő "Ring1" felhasználók száma 100%-ra csökken.
  5. A felhasználói bázis öt százaléka szerepel a bétaverzióban.
  6. A bevezetési százalék akár 100 százalék is lehet, és a funkció teljesen ki lett adva.

A szolgáltatás üzembe helyezésének stratégiája a beépített Microsoft.Targeting funkciószűrőn keresztül van beépítve a kódtárba .

Célzás webalkalmazásban

A célzási funkciószűrőt használó webalkalmazások a FeatureFlagDemo példaprojektben érhetők el.

Az alkalmazás használatának TargetingFilter megkezdéséhez hozzá kell adni az alkalmazás szolgáltatásgyűjteményéhez, ugyanúgy, mint bármely más funkciószűrőt. A többi beépített szűrővel ellentétben a TargetingFilter szolgáltatás egy másik szolgáltatásra támaszkodik, amelyet hozzá kell adni az alkalmazás szolgáltatásgyűjteményéhez. Ez a szolgáltatás egy ITargetingContextAccessor.

A szolgáltatáshoz ITargetingContextAccessor használt implementálási típust a célzási szűrőt használó alkalmazásnak kell implementálnia. Íme egy példa a funkciókezelés webalkalmazásban való beállítására, hogy a TargetingFilter rendszer a meghívásos HttpContextTargetingContextAccessorimplementációt ITargetingContextAccessor használja.

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

A célkörnyezeti tartozék, és TargetingFilter regisztrálva van a IFeatureManagementBuilder.WithTargeting<T>

ITargetingContextAccessor

A webalkalmazások használatához TargetingFilter implementálásra ITargetingContextAccessor van szükség. Ennek az az oka, hogy a célkiértékelés végrehajtásakor olyan információkra van szükség, mint például az, hogy milyen felhasználót értékelnek ki éppen. Ezt az információt célzási környezetnek nevezzük. A különböző webalkalmazások ezeket az információkat különböző helyekről nyerhetik ki. Néhány gyakori példa arra, hogy egy alkalmazás hol húzhatja le a célkörnyezetet, a kérelem HTTP-környezete vagy egy adatbázis.

A FeatureFlagDemo példaprojekt tartalmaz egy példát, amely az alkalmazás HTTP-környezetéből nyeri ki a célkörnyezet adatait. Ez a módszer az itt tárgyalt módszer használatára IHttpContextAccessortámaszkodik.

Célzás konzolalkalmazásban

A célzási szűrő egy célzási környezetre támaszkodik annak kiértékeléséhez, hogy be kell-e kapcsolni egy funkciót. Ez a célkörnyezet olyan információkat tartalmaz, mint például a jelenleg kiértékelt felhasználó és a felhasználó csoportosítása. A konzolalkalmazásokban általában nincs olyan környezeti környezet, amely ezeket az információkat a célszűrőbe továbbíthassa, ezért közvetlenül kell továbbítani, amikor FeatureManager.IsEnabledAsync meghívják. Ezt a ContextualTargetingFilter. Az olyan alkalmazásoknak, amelyeknek a célkörnyezetet a funkciókezelőbe kell lebegtetnie, ezt kell használniuk ahelyett, hogy a TargetingFilter.

Mivel ContextualTargetingFilter ez egy IContextualTargetingFilter<ITargetingContext>olyan implementáció, amelyet ITargetingContext át kell adni IFeatureManager.IsEnabledAsync annak, hogy kiértékelhesse és bekapcsolhassa a funkciót.

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

await fm.IsEnabledAsync(featureName, targetingContext);

A ContextualTargetingFilter rendszer továbbra is a Microsoft.Targeting szolgáltatásszűrő aliast használja, így a szűrő konfigurációja összhangban van az ebben a szakaszban említettekkel.

A TargetingConsoleApp példaprojektben egy konzolalkalmazásban használt ContextualTargetingFilter példa érhető el.

A célzás kiértékelési beállításai

A beállítások segítségével testre szabhatja, hogyan történik a célértékek kiértékelése az összes funkcióban. Ezek a beállítások a funkciókezelés beállításakor konfigurálhatók.

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

Célzás kizárása

Célközönség meghatározásakor a felhasználók és csoportok kizárhatók a célközönségből. Ez akkor hasznos, ha egy szolgáltatást egy felhasználói csoportnak ad ki, de néhány felhasználót vagy csoportot ki kell zárni a bevezetésből. A kizárást a felhasználók és csoportok listájának a célközönség tulajdonságához való hozzáadásával lehet definiálni Exclusion .

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

A fenti példában a funkció engedélyezve van az elnevezett Jeff és Aliciaa . A csoporthoz tartozó felhasználók számára is engedélyezve Ring0van. Ha azonban a felhasználó neve el van nevezve Mark, a szolgáltatás le van tiltva, függetlenül attól, hogy a csoportban Ring0 vannak-e, vagy sem. A kizárások elsőbbséget élveznek a célszűrő többi részével szemben.

Változatok

Amikor új funkciókat adnak hozzá egy alkalmazáshoz, előfordulhat, hogy egy funkció több különböző javasolt tervezési lehetőséggel rendelkezik. A tervezéssel kapcsolatos döntés egyik gyakori megoldása az A/B tesztelés valamilyen formája, amely magában foglalja a funkció egy másik verziójának biztosítását a felhasználói bázis különböző szegmensei számára, és a felhasználói interakciók alapján kiválasztja a verziót. Ebben a kódtárban ez a funkció egy funkció különböző konfigurációinak variánsokkal való ábrázolásával engedélyezve van.

A változatok lehetővé teszik, hogy egy funkciójelző több legyen, mint egy egyszerű be- és kikapcsolási jelző. A variánsok egy funkciójelző értékét jelölik, amely lehet sztring, szám, logikai vagy akár konfigurációs objektum is. A változatokat deklaráló funkciójelzőnek meg kell határoznia, hogy milyen körülmények között kell használni az egyes változatokat, amelyről részletesebben a Kiosztási változatok szakaszban olvashat.

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

Változatok lekérése

Minden funkcióhoz lekérhető egy variáns a IVariantFeatureManager"metódus" GetVariantAsync használatával.

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

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration

A változat lekérése után a változat konfigurációja közvetlenül IConfigurationSection használható a változat tulajdonságából Configuration . Egy másik lehetőség, ha a konfigurációt egy objektumhoz köti a használatával. A NET konfigurációkötési mintája.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

A visszaadott variáns az éppen kiértékelt felhasználótól függ, és az információ a következő példányból származik TargetingContext: . Ez a környezet átadható híváskor GetVariantAsync , vagy automatikusan lekérhető annak egy implementációjából ITargetingContextAccessor , ha van regisztrálva.

Variant Feature Flag Deklaráció

A normál funkciójelzőkhöz képest a változatfunkció-jelzők két további tulajdonsággal rendelkeznek: variants és allocation. A variants tulajdonság egy tömb, amely a funkcióhoz definiált változatokat tartalmazza. A allocation tulajdonság határozza meg, hogyan kell lefoglalni ezeket a változatokat a funkcióhoz. A normál funkciójelzők deklarálásával egy JSON-fájlban is beállíthat változatfunkció-jelzőket. Íme egy példa egy változatfunkció-jelzőre.

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

Variánsok definiálása

Mindegyik változat két tulajdonsággal rendelkezik: egy névvel és egy konfigurációval. A név egy adott változatra hivatkozik, a konfiguráció pedig az adott változat értéke. A konfiguráció a tulajdonságok vagy configuration_value a configuration_reference tulajdonságok használatával állítható be. configuration_reference egy sztring elérési útja, amely az aktuális konfiguráció egy szakaszára hivatkozik, amely tartalmazza a funkciójelölő deklarációját. configuration_value egy beágyazott konfiguráció, amely lehet sztring, szám, logikai vagy konfigurációs objektum. Ha mindkettő meg van adva, configuration_value akkor a rendszer használja. Ha egyik sincs megadva, a visszaadott változat tulajdonsága Configuration null értékű lesz.

A tulajdonság minden egyes funkciójára vonatkozóan meg van határozva az variants összes lehetséges változat listája.

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

Változatok kiosztása

A funkcióváltozatok kiosztásának folyamatát a allocation funkció tulajdonsága határozza meg.

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

A allocation funkció beállítása a következő tulajdonságokkal rendelkezik:

Tulajdonság Leírás
default_when_disabled Megadja, hogy melyik változatot kell használni, amikor egy változatot kérnek, miközben a funkció le van tiltva.
default_when_enabled Megadja, hogy melyik változatot kell használni, amikor egy változatot kérnek, miközben a funkció engedélyezve van, és nem rendeltek hozzá más változatot a felhasználóhoz.
user Egy változatot és azon felhasználók listáját adja meg, akikhez a változatot hozzá kell rendelni.
group Egy variánst és egy csoportlistát határoz meg. A variáns akkor lesz hozzárendelve, ha a felhasználó legalább egy csoportban van.
percentile Egy variánst és egy százalékos tartományt ad meg, amelyhez a felhasználó számított százalékos aránya igazodik a hozzárendelendő változathoz.
seed Az az érték, amelyre a percentile százalékos számítások alapulnak. Ha ugyanazt seed az értéket használja, az adott felhasználó százalékos kiszámítása minden szolgáltatásban azonos lesz. Ha nincs seed megadva, a rendszer létrehoz egy alapértelmezett magot a szolgáltatásnév alapján.

A fenti példában, ha a funkció nincs engedélyezve, a funkciókezelő hozzárendeli az aktuális felhasználóhoz jelölt default_when_disabled változatot, amely ebben az esetben van Small .

Ha a funkció engedélyezve van, a funkciókezelő ellenőrzi a , groupés percentile a foglalásokat abban a usersorrendben, hogy hozzárendeljen egy változatot. Ebben a konkrét példában, ha a kiértékelt felhasználó neve el van nevezve Marsha, a névvel ellátott Ring1csoportban, vagy a felhasználó a 0 és a 10. percentilis közé esik, akkor a megadott változat lesz hozzárendelve a felhasználóhoz. Ebben az esetben ezek mindegyike a variánst Big adja vissza. Ha egyik foglalás sem egyezik meg, a felhasználóhoz hozzá lesz rendelve a default_when_enabled variáns, azaz a Small.

A kiosztási logika hasonló a Microsoft.Targeting szolgáltatásszűrőhöz, de vannak olyan paraméterek, amelyek nem szerepelnek a kiosztásban, és fordítva. A célzás és a kiosztás eredményei nem kapcsolódnak egymáshoz.

Feljegyzés

A funkcióvariánsok kiosztásának engedélyezéséhez regisztrálnia ITargetingContextAccessorkell. Ezt a metódus meghívásával WithTargeting<T> teheti meg.

Engedélyezett állapot felülírása Variant használatával

A változatok használatával felülbírálhatja egy funkciójelző engedélyezett állapotát. Ez lehetőséget ad a variánsoknak egy funkciójelző kiértékelésének kiterjesztésére. Ha egy hívó ellenőrzi, hogy engedélyezve van-e egy változókat tartalmazó jelző, a szolgáltatáskezelő ellenőrzi, hogy az aktuális felhasználóhoz rendelt változat felülbírálja-e az eredményt. Ez az opcionális változattulajdonság status_overridehasználatával történik. Alapértelmezés szerint ez a tulajdonság be van állítva None, ami azt jelenti, hogy a változat nem befolyásolja, hogy a jelző engedélyezve vagy letiltva van-e. Beállítás status_override , amely lehetővé teszi, hogy Enabled a variáns a választáskor felülbíráljon egy jelölőt. Disabled A beállítás status_override az ellenkező funkciót biztosítja, ezért letiltja a jelölőt a változat kiválasztásakor. Egy állapotú enabled false funkció nem bírálható felül.

Ha bináris változatokkal rendelkező funkciójelzőt használ, a status_override tulajdonság nagyon hasznos lehet. Lehetővé teszi, hogy továbbra is használja az API-kat az alkalmazásban és FeatureGateAttribute az IsEnabledAsync alkalmazásban, miközben kihasználja a variánsokkal járó új funkciókat, például a percentilis kiosztást és a magot.

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

A fenti példában a funkció mindig engedélyezve van. Ha az aktuális felhasználó a számított percentilistartományban van 10 és 20 között, akkor a rendszer visszaadja a On variánst. Ellenkező esetben a rendszer visszaadja a Off variánst, és mivel status_override az egyenlő Disabled, a funkció le lesz tiltva.

Variánsok a függőséginjektálásban

A variant funkciójelzők a függőséginjektálással együtt használhatók egy szolgáltatás különböző implementációinak felszínre hozásához a különböző felhasználók számára. Ez a felület használatával IVariantServiceProvider<TService> történik.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken);

A fenti kódrészletben a IVariantServiceProvider<IAlgorithm> függőséginjektálási tároló implementációját IAlgorithm kéri le. A választott megvalósítás a következőtől függ:

  • A szolgáltatás által regisztrált funkciójelző IAlgorithm .
  • A szolgáltatáshoz lefoglalt változat.

A IVariantServiceProvider<T> hívással IFeatureManagementBuilder.WithVariantService<T>(string featureName)elérhetővé válik az alkalmazás számára. Lásd alább egy példát.

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

A fenti hívás elérhetővé válik IVariantServiceProvider<IAlgorithm> a szolgáltatásgyűjteményben. A megvalósításokat IAlgorithm külön kell hozzáadni egy olyan hozzáadási módszerrel, mint a services.AddSingleton<IAlgorithm, SomeImplementation>(). Ennek megvalósítása IAlgorithm a IVariantServiceProvider változat funkciójelzőtől függ ForecastAlgorithm . Ha nincs implementáció IAlgorithm hozzáadva a szolgáltatásgyűjteményhez, a IVariantServiceProvider<IAlgorithm>.GetServiceAsync() rendszer null eredményt ad vissza.

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

Variant Service Alias attribútum

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

A változatszolgáltató a implementációk típusneveit fogja használni a lefoglalt változatnak megfelelően. Ha egy változatszolgáltatást a rendszer a VariantServiceAliasAttributekövetkezővel deklarál, az attribútumban deklarált nevet kell használni a konfigurációban a változatszolgáltatásra való hivatkozáshoz.

Telemetria

Amikor üzembe helyez egy funkciójelző-módosítást, gyakran fontos elemezni az alkalmazásra gyakorolt hatását. Íme például néhány kérdés, amely felmerülhet:

  • A jelzők a várt módon vannak engedélyezve/letiltva?
  • A megcélzott felhasználók a várt módon férnek hozzá egy adott funkcióhoz?
  • Melyik változatot látja egy adott felhasználó?

Ezekre a kérdésekre a funkciójelzők kiértékelési eseményeinek kibocsátásával és elemzésével lehet válaszolni. Ez a kódtár támogatja ezeknek az eseményeknek a telemetriai közzétevőken keresztüli kibocsájtását. Egy vagy több telemetriai közzétevő regisztrálható az események közzétételére a funkciójelzők kiértékelésekor.

Telemetria engedélyezése

Alapértelmezés szerint a funkciójelzők nem bocsátanak ki telemetriát. Egy adott funkciójelző telemetriai adatainak közzétételéhez a jelölőnek deklarálnia kell , hogy engedélyezve van a telemetriai kibocsátáshoz.

A tulajdonságban appsettings.jsondefiniált funkciójelzők esetében ez a telemetry tulajdonság használatával történik.

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

A fenti appsettings-kódrészlet egy olyan funkciójelölőt MyFeatureFlag határoz meg, amely engedélyezve van a telemetriához. Ezt az telemetry igaz értékre állító enabled objektum jelzi. A tulajdonság értékét a enabled jelölő telemetriájának közzétételéhez kell megadni true .

A telemetry funkciójelölő szakasza a következő tulajdonságokkal rendelkezik:

Tulajdonság Leírás
enabled Megadja, hogy közzé kell-e tenni a telemetriát a funkciójelölőhöz.
metadata A kulcs-érték párok szótárként modellezett gyűjteménye, amely a funkciójelző egyéni metaadatainak a kiértékelési eseményekhez való csatolására használható.

Egyéni telemetriai közzétevők

A funkciójelző telemetriai adatainak egyéni kezelése a funkciókezelőben történő implementálással ITelemetryPublisher és regisztrálással lehetséges. Amikor egy telemetria-kompatibilis funkciójelző kiértékelése történik, a regisztrált telemetriai közzétevőnek lehetősége lesz közzétenni a megfelelő kiértékelési eseményt.

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

A EvaluationEvent típus itt található referenciaként.

A telemetriai közzétevők regisztrálása híváskor AddFeatureManagement()történik. Íme egy példa a szolgáltatásfelügyelet beállítására a telemetriai adatok kibocsájtásához a nevesított MyTelemetryPublisherimplementációvalITelemetryPublisher.

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

Application Insights telemetriai közzétevő

A Microsoft.FeatureManagement.Telemetry.ApplicationInsights csomag egy beépített telemetriai közzétevői implementációt biztosít, amely a funkciójelző kiértékelési adatait küldi el az Application Insightsnak. Ennek kihasználásához adjon hozzá egy hivatkozást a csomaghoz, és regisztrálja az Application Insights telemetriai közzétevőt az alább látható módon.

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

Feljegyzés

Az alapcsomag Microsoft.FeatureManagement nem tartalmazza ezt a telemetriai közzétevőt.

A használatra példa a EvaluationDataToApplicationInsights példában található.

Előfeltétel

Ez a telemetriai közzétevő attól függ, hogy az Application Insights már telepítve van, és alkalmazásszolgáltatásként van regisztrálva. Ez például itt történik a példaalkalmazásban.

Gyorsítótárazás

A szolgáltatás állapotát a IConfiguration rendszer biztosítja. A gyorsítótárazást és a dinamikus frissítést várhatóan a konfigurációszolgáltatók fogják kezelni. A funkciókezelő a funkció állapotának legújabb értékét kéri IConfiguration , amikor egy funkció engedélyezve van.

Pillanatkép

Vannak olyan forgatókönyvek, amelyek megkövetelik, hogy egy szolgáltatás állapota konzisztens maradjon a kérések élettartama alatt. A szabványból IFeatureManager visszaadott értékek változhatnak, ha a IConfiguration lekérés forrása frissül a kérés során. Ez megelőzhető a következő használatával IFeatureManagerSnapshot: . IFeatureManagerSnapshot ugyanúgy kérhető le, mint IFeatureManagera . IFeatureManagerSnapshot implementálja a felületét IFeatureManager, de gyorsítótárazza egy szolgáltatás első kiértékelt állapotát egy kérés során, és ugyanazt az állapotot adja vissza egy szolgáltatásnak az élettartama során.

Egyéni szolgáltatásszolgáltatók

Az egyéni szolgáltatásszolgáltató implementálása lehetővé teszi, hogy a fejlesztők lekérjenek funkciójelzőket olyan forrásokból, mint egy adatbázis vagy egy szolgáltatásfelügyeleti szolgáltatás. Az alapértelmezett szolgáltatásszolgáltató lekéri a .NET Core konfigurációs rendszeréből a funkciójelzőket. Ez lehetővé teszi, hogy a funkciók appsettings.json fájlban vagy olyan konfigurációszolgáltatókban definiálhatók, mint a Azure-alkalmazás Configuration. Ez a viselkedés helyettesíthető a funkciódefiníciók olvasásának teljes ellenőrzéséhez.

A funkciódefiníciók betöltésének testreszabásához implementálnia kell a IFeatureDefinitionProvider felületet.

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

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

A implementáció IFeatureDefinitionProviderhasználatához hozzá kell adni a szolgáltatásgyűjteményhez a funkciókezelés hozzáadása előtt. Az alábbi példa egy elnevezett InMemoryFeatureDefinitionProviderimplementációt IFeatureDefinitionProvider ad hozzá.

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

Következő lépések

Ha meg szeretné tudni, hogyan használhatja a funkciójelzőket az alkalmazásokban, folytassa az alábbi rövid útmutatókkal.

ASP.NET Core

.NET/.NET-keretrendszer konzolalkalmazás

.NET háttérszolgáltatás

A funkciószűrők használatának megismeréséhez folytassa az alábbi oktatóanyagokkal.

Feltételes szolgáltatások engedélyezése funkciószűrőkkel

Funkciók engedélyezése ütemezés szerint

Szolgáltatások bevezetése a célközönségek számára

Ha meg szeretné tudni, hogyan futtathat kísérleteket a változatfunkció-jelzőkkel, folytassa az alábbi oktatóanyaggal.

Kísérletek futtatása variánsfunkció-jelzőkkel