Öğretici: ASP.NET Core uygulamasında özellik bayraklarını kullanma

Makale
02/28/2024

.NET Özellik Yönetimi kitaplıkları bir .NET veya ASP.NET Core uygulamasında özellik bayrakları uygulamak için idiomatic desteği sağlar. Bu kitaplıklar, deyimlerle if özellikleri etkinleştirmek veya devre dışı bırakmak için el ile kod yazmanız gerekmeyecek şekilde kodunuza bildirim temelli olarak özellik bayrakları eklemenize olanak tanır.

Özellik Yönetimi kitaplıkları, arka planda özellik bayrağı yaşam döngülerini de yönetir. Örneğin, kitaplıklar bayrak durumlarını yeniler ve önbelleğe alır veya bir istek çağrısı sırasında bir bayrak durumunun sabit olmasını garanti eder. Ayrıca ASP.NET Core kitaplığı MVC denetleyici eylemleri, görünümler, yollar ve ara yazılım gibi kullanıma açık tümleştirmeler sunar.

ASP.NET Core özellik yönetimi API'sine başvuru belgeleri için bkz . Microsoft.FeatureManagement Ad Alanı.

Bu öğreticide şunların nasıl yapıldığını öğrenirsiniz:

Özellik kullanılabilirliğini denetlemek için uygulamanızın önemli bölümlerine özellik bayrakları ekleyin.
Özellik bayraklarını yönetmek için kullanırken Uygulama Yapılandırması ile tümleştirin.

Önkoşullar

ASP.NET Core uygulamasına özellik bayrakları ekleme Hızlı Başlangıcı, ASP.NET Core uygulamasında özellik bayraklarının nasıl kullanılacağına ilişkin basit bir örnek gösterir. Bu öğretici, Özellik Yönetimi kitaplıklarının ek kurulum seçeneklerini ve özelliklerini gösterir. Bu öğreticide gösterilen örnek kodu denemek için hızlı başlangıçta oluşturulan örnek uygulamayı kullanabilirsiniz.

Özellik yönetimini ayarlama

.NET özellik yöneticisine erişmek için uygulamanızın ve Microsoft.FeatureManagement.AspNetCore NuGet paketlerine Microsoft.Azure.AppConfiguration.AspNetCore başvuruları olmalıdır.

.NET özellik yöneticisi, çerçevenin yerel yapılandırma sisteminden yapılandırılır. Sonuç olarak, yerel appsettings.json dosya veya ortam değişkenleri dahil olmak üzere .NET'in desteklediği herhangi bir yapılandırma kaynağını kullanarak uygulamanızın özellik bayrağı ayarlarını tanımlayabilirsiniz.

Varsayılan olarak, özellik yöneticisi .NET yapılandırma verilerinin "FeatureManagement" bölümünden özellik bayrağı yapılandırmasını alır. Varsayılan yapılandırma konumunu kullanmak için, Başlangıç sınıfının ConfigureServices yöntemine geçirilen IServiceCollection'ınAddFeatureManagement yöntemini çağırın.

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

Configuration.GetSection çağrısı yaparak ve istenen bölümün adını geçirerek özellik yönetimi yapılandırmasının farklı bir yapılandırma bölümünden alınması gerektiğini belirtebilirsiniz. Aşağıdaki örnek, özellik yöneticisine bunun yerine adlı "MyFeatureFlags" farklı bir bölümden okumasını söyler:

using Microsoft.FeatureManagement;

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

Özellik bayraklarınızda filtreler kullanıyorsanız, Microsoft.FeatureManagement.FeatureFilters ad alanını eklemeniz ve yöntemin genel türü olarak kullanmak istediğiniz filtrenin tür adını belirten AddFeatureFilter çağrısı eklemeniz gerekir. İşlevselliği dinamik olarak etkinleştirmek ve devre dışı bırakmak için özellik filtrelerini kullanma hakkında daha fazla bilgi için bkz . Hedeflenen hedef kitleler için aşamalı özellik dağıtımını etkinleştirme.

Aşağıdaki örnekte adlı PercentageFilteryerleşik özellik filtresinin nasıl kullanılacağı gösterilmektedir:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement()
    .AddFeatureFilter<PercentageFilter>();

Özellik bayraklarınızı uygulamanıza sabit kodlamak yerine, özellik bayraklarını uygulamanın dışında tutmanızı ve bunları ayrı olarak yönetmenizi öneririz. Bunu yapmak, bayrak durumlarını istediğiniz zaman değiştirmenize ve bu değişikliklerin uygulamada hemen geçerli olmasını sağlar. Azure Uygulaması Yapılandırma hizmeti, tüm özellik bayraklarınızı yönetmek için ayrılmış bir portal kullanıcı arabirimi sağlar. Azure Uygulaması Yapılandırma hizmeti ayrıca özellik bayraklarını doğrudan .NET istemci kitaplıkları aracılığıyla uygulamanıza sunar.

ASP.NET Core uygulamanızı Uygulama Yapılandırması bağlamanın en kolay yolu NuGet paketine Microsoft.Azure.AppConfiguration.AspNetCore dahil edilen yapılandırma sağlayıcısını kullanmaktır. Pakete başvuruyu dahil ettikten sonra, bu NuGet paketini kullanmak için bu adımları izleyin.

Program.cs dosyasını açın ve aşağıdaki kodu ekleyin.

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

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

Aşağıdaki kodu kullanarak uygulamanız için ara yazılım ve hizmet yapılandırmalarını güncelleştirin.

program.cs sınıfının içinde ve app nesnelerine Azure Uygulaması Yapılandırma hizmetlerini ve ara yazılımı builder kaydedin:
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

Tipik bir senaryoda, uygulamanızın ve farklı özelliklerini dağıtıp etkinleştirdikçe özellik bayrağı değerlerinizi düzenli aralıklarla güncelleştireceksiniz. Varsayılan olarak, özellik bayrağı değerleri 30 saniye süreyle önbelleğe alınır, bu nedenle ara yazılım bir istek aldığında tetiklenen bir yenileme işlemi, önbelleğe alınan değerin süresi dolana kadar değeri güncelleştirmez. Aşağıdaki kod, çağrıdaki CacheExpirationInterval değerini UseFeatureFlags olarak ayarlayarak önbellek süre sonu süresini veya yoklama aralığını 5 dakikaya nasıl değiştireceğini gösterir.

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

Özellik bayrağı bildirimi

Her özellik bayrağı bildiriminin iki bölümü vardır: bir ad ve bir özelliğin durumunun açık olup olmadığını değerlendirmek için kullanılan bir veya daha fazla filtrenin listesi (değeri olduğunda True). Filtre, bir özelliğin ne zaman açılması gerektiğine ilişkin bir ölçüt tanımlar.

Özellik bayrağında birden çok filtre olduğunda, filtrelerden biri özelliğin etkinleştirilmesi gerektiğini belirleyene kadar filtre listesinde sırayla geçiş yapılır. Bu noktada özellik bayrağı açık ve kalan tüm filtre sonuçları atlanır. Hiçbir filtre özelliğin etkinleştirilmesi gerektiğini belirtirse özellik bayrağı kapalıdır.

Özellik yöneticisi, özellik bayrakları için yapılandırma kaynağı olarak appsettings.json destekler. Aşağıdaki örnekte, bir JSON dosyasında özellik bayraklarının nasıl ayarlanacağı gösterilmektedir:

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

Kural gereği, FeatureManagement bu JSON belgesinin bölümü özellik bayrağı ayarları için kullanılır. Önceki örnekte, filtrelerinin özelliğinde tanımlandığı üç özellik bayrağı gösterilmektedir EnabledFor :

FeatureAaçık.
FeatureBkapalıdır.
FeatureC özelliğiyle adlı Percentage bir Parameters filtre belirtir. Percentage yapılandırılabilir bir filtredir. Bu örnekte bayrağın Percentage açık olması için FeatureC yüzde 50 olasılık belirtir. Özellik filtrelerini kullanma hakkında nasıl yapılır kılavuzu için bkz . Koşullu özellik bayraklarını etkinleştirmek için özellik filtrelerini kullanma.

IFeatureManager'a erişmek için bağımlılık ekleme özelliğini kullanma

Özellik bayrağı değerlerini el ile denetleme gibi bazı işlemler için bir IFeatureManager örneği almanız gerekir. ASP.NET Core MVC'de bağımlılık ekleme yoluyla özellik yöneticisine IFeatureManager erişebilirsiniz. Aşağıdaki örnekte, denetleyicinin oluşturucusunun imzasına tür IFeatureManager bağımsız değişkeni eklenir. Çalışma zamanı, başvuruyu otomatik olarak çözümler ve oluşturucuyu çağırırken arabirimin bir uygulamasını sağlar. Denetleyicinin oluşturucuda gibi bir veya daha fazla bağımlılık ekleme bağımsız değişkeninin bulunduğu bir uygulama şablonu kullanıyorsanız, ILoggerek bağımsız değişken olarak ekleyebilirsiniz IFeatureManager :

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

Özellik bayrağı başvuruları

Koddan başvurmak için özellik bayraklarını dize değişkenleri olarak tanımlayın:

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

Özellik bayrağı denetimleri

Özellik yönetiminin yaygın bir düzeni, özellik bayrağının açık olarak ayarlanıp ayarlanmadığını denetlemek ve ayarlıysa kodun bir bölümünü çalıştırmaktır. Örneğin:

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

Denetleyici eylemleri

MVC denetleyicileriyle, bir denetleyici sınıfının tamamının mı yoksa belirli bir eylemin FeatureGate mi etkinleştirildiğini denetlemek için özniteliğini kullanabilirsiniz. Denetleyici sınıfının içerdiği herhangi bir eylemin yürütülebilmesi için aşağıdaki HomeController denetleyicinin açık olması gerekirFeatureA:

using Microsoft.FeatureManagement.Mvc;

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

Aşağıdaki Index eylemin FeatureA çalıştırılabilmesi için önce açık olması gerekir:

using Microsoft.FeatureManagement.Mvc;

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

Denetim özelliği bayrağı kapalı olduğundan bir MVC denetleyicisi veya eylemi engellendiğinde, kayıtlı bir IDisabledFeaturesHandler arabirimi çağrılır. Varsayılan IDisabledFeaturesHandler arabirim, istemciye yanıt gövdesi olmayan bir 404 durum kodu döndürür.

MVC görünümleri

Views dizininde _ViewImports.cshtml dosyasını açın ve özellik yöneticisi etiketi yardımcısını ekleyin:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC görünümlerinde, özellik <feature> bayrağının etkinleştirilip etkinleştirilmediğine bağlı olarak içeriği işlemek için bir etiket kullanabilirsiniz:

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

Gereksinimler karşılanmadığında negate alternatif içerik görüntülemek için özniteliği kullanılabilir.

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

Özellik <feature> etiketi, listedeki özelliklerden herhangi biri veya tümü etkinse içeriği göstermek için de kullanılabilir.

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

Özellik bayrağının durumuna göre etkinleştirilmeleri için MVC filtreleri ayarlayabilirsiniz. Bu özellik, IAsyncActionFilter uygulayan filtrelerle sınırlıdır. Aşağıdaki kod adlı ThirdPartyActionFilterbir MVC filtresi ekler. Bu filtre MVC işlem hattı içinde yalnızca etkinse FeatureA tetikler.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

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

Ara yazılım

Uygulama dallarını ve ara yazılımları koşullu olarak eklemek için özellik bayraklarını da kullanabilirsiniz. Aşağıdaki kod, yalnızca etkinleştirildiğinde FeatureA istek işlem hattına bir ara yazılım bileşeni ekler:

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

Bu kod, bir özellik bayrağına dayalı olarak uygulamanın tamamını dallara ayırmak için daha genel bir özellik oluşturur:

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

Sonraki adımlar

Bu öğreticide, kitaplıkları kullanarak Microsoft.FeatureManagement ASP.NET Core uygulamanızda özellik bayrakları uygulamayı öğrendiniz. ASP.NET Core ve Uygulama Yapılandırması özellik yönetimi desteği hakkında daha fazla bilgi için aşağıdaki kaynaklara bakın: