Oktatóanyag: Funkciójelzők használata egy ASP.NET Core-alkalmazásban

Cikk
03/05/2024

A .NET szolgáltatásfelügyeleti kódtárak idiomatikus támogatást nyújtanak a funkciójelzők .NET-ben vagy ASP.NET Core-alkalmazásokban való implementálására. Ezek a kódtárak lehetővé teszik a funkciójelzők deklaratív hozzáadását a kódhoz, hogy ne kelljen manuálisan írnia a kódot a funkciók utasításokkal if való engedélyezéséhez vagy letiltásához.

A szolgáltatásfelügyeleti kódtárak a funkciójelző életciklusait is kezelik a színfalak mögött. A kódtárak például frissítik és gyorsítótárazják a jelölő állapotát, vagy garantálják, hogy a jelölő állapota nem módosítható egy kéréshívás során. A ASP.NET Core-kódtár emellett beépített integrációkat is kínál, beleértve az MVC-vezérlő műveleteit, nézeteit, útvonalait és köztes szoftvereit.

A ASP.NET Core szolgáltatásfelügyeleti API referenciadokumentációját a Microsoft.FeatureManagement Névtérben találja.

Az oktatóanyag során a következőket fogja elsajátítani:

A funkció rendelkezésre állásának szabályozásához adjon hozzá funkciójelzőket az alkalmazás főbb részeihez.
Integrálható az Alkalmazáskonfigurációval, amikor a funkciójelzők kezelésére használja.

Előfeltételek

A Funkciójelölők hozzáadása egy ASP.NET Core-alkalmazáshoz – rövid útmutató egy egyszerű példát mutat be a funkciójelzők ASP.NET Core-alkalmazásokban való használatára. Ez az oktatóanyag a funkciókezelési kódtárak további beállítási lehetőségeit és képességeit mutatja be. A rövid útmutatóban létrehozott mintaalkalmazással kipróbálhatja az oktatóanyagban látható mintakódot.

Funkciókezelés beállítása

A .NET-funkciókezelő eléréséhez az alkalmazásnak a nuGet-csomagokra Microsoft.Azure.AppConfiguration.AspNetCoreMicrosoft.FeatureManagement.AspNetCore mutató hivatkozásokkal kell rendelkeznie.

A .NET szolgáltatáskezelő a keretrendszer natív konfigurációs rendszeréből van konfigurálva. Ennek eredményeképpen meghatározhatja az alkalmazás funkciójelző beállításait a .NET által támogatott konfigurációs forrás használatával, beleértve a helyi appsettings.json fájl- vagy környezeti változókat is.

Alapértelmezés szerint a szolgáltatáskezelő lekéri a szolgáltatásjelző konfigurációját a "FeatureManagement" .NET-konfigurációs adatok szakaszából. Az alapértelmezett konfigurációs hely használatához hívja meg az indítási osztály ConfigureServices metódusába átadott IServiceCollection AddFeatureManagement metódusát.

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

A Configuration.GetSection meghívásával és a kívánt szakasz nevének átadásával megadhatja, hogy a szolgáltatásfelügyeleti konfigurációt egy másik konfigurációs szakaszból kell lekérni. Az alábbi példa arra utasítja a szolgáltatáskezelőt, hogy egy másik, úgynevezett "MyFeatureFlags" szakaszból olvasson:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));

Funkciószűrőkkel engedélyezheti a feltételes funkciójelzőket. Ha beépített funkciószűrőket szeretne használni, vagy sajátot szeretne létrehozni, olvassa el a Feltételes szolgáltatások engedélyezése funkciószűrőkkel című témakört.

Ahelyett, hogy keményen kódolta a funkciójelzőket az alkalmazásba, javasoljuk, hogy tartsa meg a funkciójelzőket az alkalmazáson kívül, és külön kezelje őket. Ezzel bármikor módosíthatja a jelzőállapotokat, és azonnal érvénybe léptetheti a módosításokat az alkalmazásban. A Azure-alkalmazás Konfigurációs szolgáltatás egy dedikált portál felhasználói felületet biztosít az összes funkciójelző kezeléséhez. A Azure-alkalmazás Konfigurációs szolgáltatás a szolgáltatásjelzőket is közvetlenül az alkalmazásnak továbbítja a .NET-ügyfélkódtárakon keresztül.

A ASP.NET Core-alkalmazás alkalmazáskonfigurációhoz való csatlakoztatásának legegyszerűbb módja a NuGet-csomagban Microsoft.Azure.AppConfiguration.AspNetCore található konfigurációszolgáltatón keresztül. Miután felvesz egy hivatkozást a csomagra, kövesse az alábbi lépéseket a NuGet-csomag használatához.

Nyissa meg Program.cs fájlt, és adja hozzá a következő kódot.

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
        .UseFeatureFlags());

Frissítse az alkalmazás köztes szoftver- és szolgáltatáskonfigurációit az alábbi kóddal.

Az osztályon program.cs belül regisztrálja a Azure-alkalmazás konfigurációs szolgáltatásokat és köztes szoftvereket az és app objektumokonbuilder:
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

Egy tipikus forgatókönyvben rendszeresen frissíti a funkciójelző értékeit, amikor üzembe helyezi és engedélyezi az alkalmazás különböző funkcióit. Alapértelmezés szerint a szolgáltatásjelző értékeit 30 másodpercig gyorsítótárazza a rendszer, ezért a köztes szoftver kérésének fogadásakor aktivált frissítési művelet nem frissíti az értéket, amíg a gyorsítótárazott érték el nem jár. Az alábbi kód bemutatja, hogyan módosíthatja a gyorsítótár lejárati idejét vagy a lekérdezési időközt 5 percre a CacheExpirationInterval beállításával a UseFeatureFlags hívásában.

config.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
            .UseFeatureFlags(featureFlagOptions => {
                featureFlagOptions.CacheExpirationInterval = TimeSpan.FromMinutes(5);
    }));

Funkciójelző deklarációja

Minden funkciójelző-deklaráció két részből áll: egy névből és egy vagy több szűrőből álló listával, amelyek alapján kiértékelhető, hogy egy szolgáltatás állapota be van-e kapcsolva (vagyis ha az értéke).True A szűrő meghatározza azt a feltételt, hogy mikor kell bekapcsolni egy funkciót.

Ha egy funkciójelző több szűrővel rendelkezik, a szűrőlista sorrendben halad végig, amíg az egyik szűrő nem határozza meg, hogy engedélyezni kell a funkciót. Ekkor be van kapcsolva a funkciójelző, és a rendszer kihagyja a fennmaradó szűrőeredményeket. Ha nincs szűrő, amely azt jelzi, hogy a funkciót engedélyezni kell, a funkciójelző ki van kapcsolva.

A funkciókezelő támogatja a appsettings.json konfigurációs forrásként a funkciójelzőkhöz. Az alábbi példa bemutatja, hogyan állíthat be funkciójelzőket egy JSON-fájlban:

{"FeatureManagement": {
        "FeatureA": true, // Feature flag set to on
        "FeatureB": false, // Feature flag set to off
        "FeatureC": {
            "EnabledFor": [
                {
                    "Name": "Percentage",
                    "Parameters": {
                        "Value": 50
                    }
                }
            ]
        }
    }
}

Konvenció szerint ennek a JSON-dokumentumnak a FeatureManagement szakasza használható a funkciójelző beállításaihoz. Az előző példában három funkciójelző látható a tulajdonságban EnabledFor definiált szűrőkkel:

FeatureA be van kapcsolva.
FeatureB ki van kapcsolva.
FeatureC egy tulajdonsággal elnevezett Percentage szűrőt Parameters ad meg. Percentage egy konfigurálható szűrő. Ebben a példában Percentage a jelölő 50 százalékos valószínűségét FeatureC adja meg. A funkciószűrők használatával kapcsolatos útmutatót a Feltételes funkciójelzők engedélyezéséhez a funkciószűrők használata című témakörben találja.

Függőséginjektálás használata az IFeatureManager eléréséhez

Bizonyos műveletekhez, például a funkciójelölők értékének manuális ellenőrzéséhez be kell szereznie az IFeatureManager egy példányát. A ASP.NET Core MVC-ben függőséginjektálással érheti el a funkciókezelőt IFeatureManager . Az alábbi példában egy típus IFeatureManager argumentumot ad hozzá a vezérlő konstruktorának aláírásához. A futtatókörnyezet automatikusan feloldja a referenciát, és a konstruktor meghívásakor biztosítja a felület implementációját. Ha olyan alkalmazássablont használ, amelyben a vezérlő már rendelkezik egy vagy több függőséginjektálási argumentumtal a konstruktorban, például ILoggeregyszerűen hozzáadhat IFeatureManager további argumentumokat:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

    public HomeController(ILogger<HomeController> logger, IFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

Funkciójelölő hivatkozásai

A funkciójelölőket sztringváltozókként definiálhatja, hogy kódból hivatkozhasson rájuk:

public static class MyFeatureFlags
{
    public const string FeatureA = "FeatureA";
    public const string FeatureB = "FeatureB";
    public const string FeatureC = "FeatureC";
}

Funkciójelző-ellenőrzések

A funkciókezelés gyakori mintája annak ellenőrzése, hogy be van-e kapcsolva egy funkciójelző, és ha igen, futtassa a kód egy szakaszát. Példa:

IFeatureManager featureManager;
...
if (await featureManager.IsEnabledAsync(MyFeatureFlags.FeatureA))
{
    // Run the following code
}

Vezérlőműveletek

Az MVC-vezérlőkkel az FeatureGate attribútum segítségével szabályozhatja, hogy egy teljes vezérlőosztály vagy egy adott művelet engedélyezve van-e. A vezérlőosztály által tartalmazott műveletek végrehajtása előtt a következő HomeController vezérlőnek FeatureA be kell kapcsolnia:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public class HomeController : Controller
{
    ...
}

A következő Index műveletnek FeatureA be kell kapcsolnia, mielőtt futtatható lenne:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public IActionResult Index()
{
    return View();
}

Ha egy MVC-vezérlő vagy művelet le van tiltva, mert a vezérlőfunkció-jelző ki van kapcsolva, a rendszer meghív egy regisztrált IDisabledFeaturesHandler-felületet . Az alapértelmezett IDisabledFeaturesHandler felület egy 404-ben megadott állapotkódot ad vissza az ügyfélnek választörzs nélkül.

MVC-nézetek

Nyissa meg a _ViewImports.cshtml fájlt a Views könyvtárban, és adja hozzá a funkciókezelő címkesegédjét:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC-nézetekben címke használatával <feature> jeleníthet meg tartalmakat attól függően, hogy engedélyezve van-e a funkciójelző:

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

Alternatív tartalom megjelenítéséhez, ha a követelmények nem teljesülnek, az negate attribútum használható.

<feature name="FeatureA" negate="true">
    <p>This will be shown if 'FeatureA' is disabled.</p>
</feature>

A funkciócímke <feature> a tartalom megjelenítésére is használható, ha a lista bármely vagy minden funkciója engedélyezve van.

<feature name="FeatureA, FeatureB" requirement="All">
    <p>This can only be seen if 'FeatureA' and 'FeatureB' are enabled.</p>
</feature>
<feature name="FeatureA, FeatureB" requirement="Any">
    <p>This can be seen if 'FeatureA', 'FeatureB', or both are enabled.</p>
</feature>

MVC-szűrők

Beállíthatja az MVC-szűrőket, hogy azok a funkciójelző állapota alapján aktiválódjon. Ez a képesség az IAsyncActionFiltert implementáló szűrőkre korlátozódik. Az alábbi kód egy MVC-szűrőt ad ThirdPartyActionFilterhozzá. Ez a szűrő csak akkor aktiválódik az MVC-folyamaton belül, ha FeatureA engedélyezve van.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options => {
        options.Filters.AddForFeature<ThirdPartyActionFilter>(MyFeatureFlags.FeatureA);
    });
}

Közbenső szoftver

A szolgáltatásjelölők használatával feltételesen adhat hozzá alkalmazáságakat és köztes szoftvereket. A következő kód csak akkor szúr be köztes szoftverösszetevőt a kérelemfolyamatba, ha FeatureA engedélyezve van:

app.UseMiddlewareForFeature<ThirdPartyMiddleware>(MyFeatureFlags.FeatureA);

Ez a kód kiépíti az általánosabb képességet a teljes alkalmazás elágaztatására egy funkciójelző alapján:

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

Következő lépések

Ebben az oktatóanyagban megtanulta, hogyan implementálhat funkciójelzőket a ASP.NET Core-alkalmazásban a Microsoft.FeatureManagement kódtárak használatával. Az ASP.NET Core és az Alkalmazáskonfiguráció szolgáltatásfelügyeleti támogatásával kapcsolatos további információkért tekintse meg az alábbi forrásokat:

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