Aracılığıyla paylaş

.NET özellik yönetimi

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

.NET özellik yönetimi kitaplığı, özellik bayraklarını temel alarak uygulama işlevselliği geliştirmenin ve kullanıma sunmanın bir yolunu sağlar. Yeni bir özellik geliştirildiğinde, birçok uygulamanın özelliğin ne zaman etkinleştirilmesi gerektiği ve hangi koşullar altında olduğu gibi özel gereksinimleri vardır. Bu kitaplık, bu ilişkileri tanımlamak için bir yol sağlar. Bu özellikleri sunmak için ortak .NET kod desenleriyle entegrasyon sağlanır.

Özellik bayrakları, .NET ve ASP.NET Core uygulamalarının özellikleri dinamik olarak açması veya kapatması için bir yol sağlar. Koşullu deyimler gibi temel kullanım örneklerinde özellik bayraklarını kullanabilirsiniz. Ayrıca, koşullu yol veya model-görünüm-denetleyici (MVC) filtreleri ekleme gibi daha gelişmiş senaryolarda özellik bayraklarını da kullanabilirsiniz. Özellik bayrakları .NET Core yapılandırma sisteminin üzerinde oluşturulur. Tüm .NET Core yapılandırma sağlayıcıları özellik bayrakları için omurga görevi görür.

.NET özellik yönetimi kitaplığını kullanmanın avantajlarından bazıları şunlardır:

  • Özellik yönetimi için yaygın kuralları kullanır.
  • Giriş için düşük bir engel vardır:
    • Arayüz üzerine IConfiguration kurulmuştur.
    • JSON dosya özelliği bayrağı kurulumunu destekler.
  • Özellik bayraklarının yaşam süresi yönetimini sağlar.
    • Yapılandırma değerleri gerçek zamanlı olarak değişebilir.
    • Özellik bayrakları isteğin tamamında tutarlı olabilir.
  • Aşağıdaki özellikler için destek sunarak temel ve karmaşık senaryoları kapsar:
    • Bildirim temelli bir yapılandırma dosyası aracılığıyla özellikleri açma ve kapatma
    • Bir özelliğin farklı değişkenlerini farklı kullanıcılara sunma
    • Bir sunucu çağrısına göre bir özelliğin durumunu dinamik olarak değerlendirme
  • Aşağıdaki alanlarda ASP.NET Core ve MVC çerçevesi için API uzantıları sağlar:
    • Yönlendirme
    • Filtreler
    • Eylem öznitelikleri

.NET özellik yönetimi kitaplığı açık kaynak. Daha fazla bilgi için bkz . FeatureManagement-Dotnet GitHub deposu.

Özellik bayrakları

Özellik bayrakları etkinleştirilebilir veya devre dışı bırakılabilir. Özellik filtreleri kullanılarak bayrağın durumu koşullu hale getirilebilir.

Özellik filtreleri

Özellik filtreleri, bir özelliğin ne zaman etkinleştirilmesi gerektiğine yönelik bir senaryo tanımlar. Bir özelliğin durumunu değerlendirmek için, filtrelerden biri özelliğin etkinleştirildiğini belirleyene kadar özellik filtreleri listesinden geçilir. Bu noktada, özellik filtreleri arasında geçiş durdurulur. Özellik filtresi özelliğin etkinleştirilmesi gerektiğini belirtmiyorsa devre dışı olarak kabul edilir.

Örneğin, bir Microsoft Edge tarayıcı özellik filtresi tasarla istediğinizi varsayalım. Microsoft Edge'den bir HTTP isteği geliyorsa, özellik filtreniz eklendiği tüm özellikleri etkinleştirir.

Özellik bayrağı yapılandırması

Özellik bayraklarının durumunu belirlemek için .NET Core yapılandırma sistemi kullanılır. Bu sistemin temeli arabirimidir IConfiguration . için IConfiguration herhangi bir sağlayıcı, özellik bayrağı kitaplığı için özellik durumu sağlayıcısı olarak kullanılabilir. Bu sistem ,appsettings.json yapılandırma dosyasından Azure Uygulama Yapılandırması'na kadar değişen senaryoları destekler.

Özellik bayrağı tanımı

Özellik yönetim kitaplığı, .NET Core sistemi için bir sağlayıcı olduğundan, özellik bayrağı kaynağı olarak appsettings.json yapılandırma dosyasını destekler. Özellik bayrakları Microsoft Feature Management schema kullanılarak bildirilir. Bu şema, kaynak olarak dilden bağımsızdır ve tüm Microsoft özellik yönetimi kitaplıklarında desteklenir.

Aşağıdaki örnekteki kod, bir JSON dosyasında özellik bayrakları bildirir:

{
    "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": "Sun, 01 Jun 2025 13:59:59 GMT",
                                "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

feature_management JSON belgesinin bölümü, özellik işareti ayarlarını yüklemek için alışılmış olduğu üzere kullanılır. Bu bölümde dizideki feature_flags özellik bayrağı nesnelerini listelemeniz gerekir. Bu kodda üç özellik bayrağı listelenir. Her özellik bayrağı nesnesinin bir id ve enabled özelliği vardır.

  • Özellik bayrağını tanımlamak ve ona başvurmak için kullandığınız ad id değeridir.
  • özelliği özellik enabled bayrağının etkin durumunu belirtir.

Bir özellik, enabledfalse ise kapalıdır. Eğer enabledtrue ise, özelliğin durumu conditions özelliğine bağlıdır. özelliği, conditions özelliği dinamik olarak etkinleştirmek için kullanılan koşulları bildirir.

  • Özellik bayrağında conditions özelliği bulunmuyorsa, özellik açıktır.
  • Özellik bayrağının özelliği conditions varsa ve koşulları karşılanırsa özellik açık olur.
  • Özellik bayrağı bir conditions özel niteliğine sahipse ve koşullar karşılanmıyorsa, bayrak kapalıdır.

Özellik filtreleri dizide client_filters tanımlanır. Önceki kodda özellik bayrağının FeatureV adlı Microsoft.TimeWindowbir özellik filtresi vardır. Bu filtre, yapılandırılabilir özellik filtresi örneğidir. Bu kodda, bu filtrenin bir parameters özelliği vardır. Bu özellik, filtreyi yapılandırmak için kullanılır. Bu durumda, özelliğin etkin olması için başlangıç ve bitiş saatleri yapılandırılır.

İleri: Özellik bayrağı adlarında iki nokta üst üste karakteri (:) yasaktır.

Gereksinim türü

conditions özelliği içinde, filtrelerin bir özelliğin durumunu değerlendirirken requirement_type mantığını mı yoksa Any mantığını mı kullanacağını belirlemek için All özelliği kullanılır. Belirtilmezse requirement_type , varsayılan değer olur Any. requirement_type değerleri aşağıdaki davranışlara yol açar:

  • Any: Özelliğin etkinleştirilmesi için yalnızca bir filtrenin true olarak değerlendirilmesi yeterlidir.
  • All: Özelliğin etkinleştirilmesi için her filtrenin true sonucunu vermesi gerekir.

requirement_type All filtrelerin geçiş yöntemini değiştirir:

  • Listede filtre yoksa özellik devre dışı bırakılır.
  • Filtreler listeleniyorsa, birinin koşulları özelliğin devre dışı bırakılmasını gerektirene kadar gözden geçirilir. Hiçbir filtre özelliğin devre dışı bırakılması gerektiğini belirtmezse etkin olarak kabul edilir.
{
    "id": "FeatureW",
    "enabled": true,
    "conditions": {
        "requirement_type": "All",
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 00:00:00 GMT"
                }
            },
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": "50"
                }
            }
        ]
    }
}

Bu örnekte, FeatureW özellik bayrağının değeri requirement_typeAll olarak belirlenmiştir. Özelliğin etkinleştirilmesi için sonuç olarak tüm filtrelerinin true olarak değerlendirmesi gerekir. Bu durumda özellik, belirtilen zaman penceresinde kullanıcıların yüzde 50'si için etkinleştirilir.

Birden çok yapılandırma kaynağını işleme

v4.3.0'dan başlayarak, Microsoft şema özellik bayrakları için özel birleştirmeyi ( feature_management bölüm) kabul edebilirsiniz. Birden çok yapılandırma kaynağında aynı özellik bayrağı kimliği göründüğünde ConfigurationFeatureDefinitionProvider , yerleşik sınıfın bir örneği bu tanımları yapılandırma sağlayıcısı kayıt sırasına göre birleştirir. Çakışma varsa, son özellik bayrağı tanımı kullanılır. Bu davranış, .NET'te varsayılan dizi dizin tabanlı birleştirme işleminden farklıdır.

Aşağıdaki kod, bağımlılık enjeksiyonu yoluyla özel özellik bayrağı yapılandırmalarının birleştirilmesini etkinleştirir.

IConfiguration configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddJsonFile("appsettings.prod.json")
    .Build();

services.AddSingleton(configuration);
services.AddFeatureManagement();
services.Configure<ConfigurationFeatureDefinitionProviderOptions>(o =>
{
        o.CustomConfigurationMergingEnabled = true;
});

Örneğini oluştururken özel birleştirmeyi ConfigurationFeatureDefinitionProviderde etkinleştirebilirsiniz:

var featureManager = new FeatureManager(
    new ConfigurationFeatureDefinitionProvider(
            configuration,
            new ConfigurationFeatureDefinitionProviderOptions
            {
                    CustomConfigurationMergingEnabled = true
            }));

Örnek davranış:

// appsettings.json
{
    "feature_management": {
        "feature_flags": [
            { "id": "FeatureA", "enabled": true },
            { "id": "FeatureB", "enabled": false }
        ]
    }
}

// appsettings.prod.json (added later in ConfigurationBuilder)
{
    "feature_management": {
        "feature_flags": [
            { "id": "FeatureB", "enabled": true }
        ]
    }
}

Özel birleştirmeyi etkinleştirdiğinizde, son bildirim kullanıldığından FeatureA etkin kalır ve FeatureB etkin olarak ayarlanır. Özel birleştirmenin devre dışı bırakıldığı varsayılan .NET birleştirmeyi kullandığınızda, diziler dizine göre birleştirilir. Kaynaklar konuma göre hizalı değilse bu yaklaşım beklenmeyen sonuçlar verebilir.

.NET Özellik Yönetimi şeması

Özellik yönetimi kitaplığının önceki sürümlerinde birincil şema .NET özellik yönetimi şemasıydı.

Kitaplığın 4.0.0 sürümünden başlayarak, .NET özellik yönetimi şemasında çeşitlemeler ve telemetri dahil olmak üzere yeni özellikler desteklenmez.

Not

Özellik bayrağı yapılandırması hem feature_management hem de FeatureManagement bölümlerinde listelenen bir tanım içeriyorsa, feature_management bölümündeki tanım kullanılır.

Tüketim

Temel bir uygulamada, özellik yönetimi özellik bayrağının etkinleştirilip etkinleştirilmediğini denetler. Ardından sonucu temel alan eylemler gerçekleştirir. Bu denetim, IsEnabledAsync yönteminin IVariantFeatureManager aracılığıyla yapılır.

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

Hizmet kaydı

Özellik yönetimi .NET Core bağımlılık eklemeye dayanır. Aşağıdaki kodda gösterildiği gibi, özellik yönetim hizmetlerini kaydetmek için standart kuralları kullanabilirsiniz:

using Microsoft.FeatureManagement;

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

Varsayılan olarak, özellik yöneticisi .NET Core yapılandırma verilerinin feature_management veya FeatureManagement bölümünden özellik bayrağı yapılandırmasını alır. İki bölüm de yoksa, yapılandırma boş olarak kabul edilir.

Not

Ayrıca, özellik bayrağı yapılandırmasının farklı bir yapılandırma bölümünden alınması gerektiğini belirtmek için bölümü AddFeatureManagement öğesine geçirerek belirleyebilirsiniz. Aşağıdaki örnek, özellik yöneticisinin bunun yerine adlı MyFeatureFlags bir bölümden okuması gerektiğini belirtir:

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

Bağımlılık enjeksiyonu

Özellik yönetimi kitaplığını MVC ile kullandığınızda, bağımlılık ekleme kullanarak uygulayan IVariantFeatureManager nesneyi elde edebilirsiniz.

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

Kapsamlı özellik yönetim hizmetleri

yöntemi, AddFeatureManagement özellik yönetim hizmetlerini bir uygulama içinde tekil olarak ekler. Bazı senaryolar bunun yerine özellik yönetim hizmetlerinin kapsamlı hizmetler olarak eklenmesini gerektirir. Örneğin, bağlam bilgileri için kapsamlı hizmetleri kullanan özellik filtrelerini kullanmak isteyebilirsiniz. Bu durumda AddScopedFeatureManagement yöntemini kullanmanız gerekir. Bu yöntem, özellik filtreleri de dahil olmak üzere özellik yönetimi hizmetlerinin kapsamlı hizmetler olarak eklenmesini sağlar.

services.AddScopedFeatureManagement();

ASP.NET Core tümleştirmesi

Özellik yönetimi kitaplığı, web uygulamalarında ortak özellik bayrağı senaryolarını etkinleştirmek için ASP.NET Core ve MVC'de işlevsellik sağlar. Bu özellikler, Microsoft.FeatureManagement.AspNetCore NuGet paketine başvurarak kullanılabilir.

Denetleyiciler ve eylemler

MVC denetleyicisi ve eylemleri çalıştırmak için belirli bir özelliğin veya herhangi bir özellik listesinden birinin etkinleştirilmesini gerektirebilir. Bir nesne kullanarak FeatureGateAttribute bu gereksinimi karşılayabilirsiniz. FeatureGateAttribute sınıfı Microsoft.FeatureManagement.Mvc ad alanı içinde tanımlanır.

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

Yukarıdaki örnekte HomeController sınıfı FeatureX tarafından kontrol ediliyor. Özellik etkinse HomeController eylemleri yalnızca FeatureX çalıştırılabilir.

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

Yukarıdaki örnekte, MVC Index eylemi yalnızca FeatureX etkinleştirildiği zaman çalıştırılabilir.

Devre dışı bırakılmış eylem yönetimi

Bir MVC denetleyicisi veya eylemi, belirttiği özelliklerden hiçbiri etkinleştirilmediği için engellendiğinde, kayıtlı uygulaması IDisabledFeaturesHandler çağrılır. Varsayılan olarak, HTTP 404 hatası döndüren minimalist bir işleyici kaydedilir. Özellik bayraklarını kaydederken, IFeatureManagementBuilder kullanarak bu işleyiciyi geçersiz kılabilirsiniz.

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

Görünüm

MVC görünümlerinde, içeriği koşullu olarak işlemek için etiketleri kullanabilirsiniz <feature> . İşleme koşullarını, bir özelliğin etkinleştirilip etkinleştirilmediğine veya bir özelliğin belirli bir değişkeninin atanıp atanmadığına göre temel alabilirsiniz. Daha fazla bilgi için bu makalenin devamında yer alan Varyantlar bölümüne bakın.

<feature name="FeatureX">
  <p>This content appears only when 'FeatureX' is enabled.</p>
</feature>

<feature name="FeatureX" variant="Alpha">
  <p>This content appears only when variant 'Alpha' of 'FeatureX' is assigned.</p>
</feature>

Ayrıca, bir özellik veya özellik kümesi devre dışı bırakıldığında içerik görüntülemek istiyorsanız etiket yardımcısı değerlendirmesini de devre dışı bırakabilirsiniz. Aşağıdaki örneklerde olduğu gibi negate="true" öğesini belirtirseniz, FeatureX devre dışı bırakıldığında içerik işlenir.

<feature negate="true" name="FeatureX">
  <p>This content appears only when 'FeatureX' is disabled.</p>
</feature>

<feature negate="true" name="FeatureX" variant="Alpha">
  <p>This content appears only when variant 'Alpha' of 'FeatureX' isn't assigned.</p>
</feature>

Birden çok özelliğe başvurmak için etiketini kullanabilirsiniz <feature> . Bunu yapmak için özniteliğindeki name özelliklerin virgülle ayrılmış bir listesini belirtin.

<feature name="FeatureX,FeatureY">
  <p>This content appears only when 'FeatureX' and 'FeatureY' are enabled.</p>
</feature>

Özellik etiketinin işlenmesi için listelenen tüm özelliklerin varsayılan olarak etkinleştirilmesi gerekir. Aşağıdaki örnekte gösterildiği gibi özniteliğini requirement ekleyerek bu davranışı geçersiz kılabilirsiniz.

<feature name="FeatureX,FeatureY" requirement="Any">
  <p>This content appears only when 'FeatureX,' 'FeatureY,' or both are enabled.</p>
</feature>

Etiketi birden çok değişkene başvurmak için de kullanabilirsiniz <feature> . Bunu yapmak için requirement değeri olarak Any kullanın ve variant özniteliğinde virgülle ayrılmış bir varyant listesi belirtin.

<feature name="FeatureX" variant="Alpha,Beta" requirement="Any">
  <p>This content appears only when variant 'Alpha' or 'Beta' of 'FeatureX' is assigned.</p>
</feature>

Not

  • Bir değişken belirtirseniz, yalnızca bir özellik belirtmeniz gerekir.
  • Birden çok varyant belirtir ve requirement değerini And kullanırsanız, hata oluştur. Birden çok değişken atayamazsınız.

Etiketin <feature> çalışması için bir etiket yardımcısı gerekir. etiketini kullanmak için özellik yönetimi etiketi yardımcısını _ViewImports.cshtml dosyasına ekleyin.

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC filtreleri

Bir özelliğin durumuna bağlı olarak koşullu olarak uyguladığınız MVC eylem filtrelerini ayarlayabilirsiniz. Bu filtreleri ayarlamak için, bunları özelliklere duyarlı bir şekilde kaydedersiniz. Özellik yönetimi akışı, IAsyncActionFilter arabirimini uygulayan eşzamanlı olmayan MVC eylem filtrelerini destekler.

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

Yukarıdaki kod adlı SomeMvcFilterbir MVC filtresini kaydeder. Bu filtre, FeatureX etkinleştirildiğinde yalnızca MVC işlem hattı içinde tetiklenir.

Razor sayfaları

MVC Razor sayfaları, çalıştırmak için belirli bir özelliğin veya herhangi bir özellik listesinden birinin etkinleştirilmesini gerektirebilir. Bir nesne kullanarak FeatureGateAttribute bu gereksinimi ekleyebilirsiniz. FeatureGateAttribute sınıfı Microsoft.FeatureManagement.Mvc ad alanı içinde tanımlanır.

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

Yukarıdaki kod, etkinleştirilmesini gerektiren FeatureX bir Razor sayfası ayarlar. Özellik etkinleştirilmemişse, sayfa bir HTTP 404 (NotFound) sonucu oluşturur.

Razor sayfalarında bir FeatureGateAttribute nesnesi kullandığınızda, FeatureGateAttribute'i sayfa işleyici türüne yerleştirmeniz gerekir. Tek tek işleyici yöntemlerine yerleştiremezsiniz.

Uygulama oluşturma

Özellik yönetim kitaplığını, bir özelliğin durumuna bağlı olarak koşullu olarak çalışan uygulama dalları ve ara yazılım eklemek için kullanabilirsiniz.

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

Önceki kodda, uygulama yalnızca özellik etkinse FeatureX istek işlem hattında görünen bir ara yazılım bileşeni ekler. Özellik çalışma zamanı sırasında etkinleştirilir veya devre dışı bırakılırsa ara yazılım işlem hattı dinamik olarak değiştirilebilir.

Aşağıdaki kodda gösterildiği gibi, bu işlev bir özelliğe dayalı olarak uygulamanın tamamını dallara ayırmak için daha genel bir özellik oluşturur.

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

Özellik filtresi uygulama

Özellik filtresi oluşturmak, tanımladığınız ölçütlere göre özellikleri etkinleştirmenin bir yolunu sağlar. Bir özellik filtresi oluşturmak için IFeatureFilter arabirimini uygulamanız gerekir. IFeatureFilter adlı EvaluateAsynctek bir yöntemi vardır. Özellik, özellik filtresi için etkinleştirilebileceğini belirttiğinde EvaluateAsync yöntemi çağrılır. Eğer EvaluateAsynctrue döndürürse, özellik etkinleştirilmelidir.

Aşağıdaki kod, adlı MyCriteriaFilterözelleştirilmiş bir özellik filtresinin nasıl ekleneceğini gösterir.

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

Bir özellik filtresini kaydetmek için, AddFeatureFilter<T>, döndürdüğü IFeatureManagementBuilder uygulamayı AddFeatureManagement çağırmalısınız. Özellik filtresi, özellik bayrakları eklemek için kullandığınız hizmet koleksiyonundaki hizmetlere erişebilir. Bu hizmetleri almak için bağımlılık ekleme özelliğini kullanabilirsiniz.

Not

Özellik bayrağı ayarlarında (örneğin, appsettings.json) filtrelere başvururken, tür adının Filter bölümünü atlamalısınız. Daha fazla bilgi için bu makalenin devamında yer alan Diğer ad özniteliğini filtreleme bölümüne bakın.

Parametreli özellik filtreleri

Bazı özellik filtreleri, bir özelliğin açık olup olmadığını değerlendirmek için parametreler gerektirir. Örneğin, bir tarayıcı özellik filtresi belirli bir tarayıcı kümesi için bir özelliği açabilir. Microsoft Edge ve Chrome tarayıcılarında bir özelliği açmak isteyebilirsiniz ancak Firefox'ta açamayabilirsiniz.

Bu filtrelemeyi uygulamak için, parametreleri bekleyebileceğiniz bir özellik filtresi tasarlayabilirsiniz. Bu parametreleri özellik yapılandırmasında belirtirsiniz. Kodda FeatureFilterEvaluationContextIFeatureFilter.EvaluateAsync parametresini kullanarak bunlara erişebilirsiniz.

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

Söz konusu FeatureFilterEvaluationContext sınıfının Parameters adlı bir özelliği vardır. Bu özelliğin parametreleri, özelliğin etkinleştirilip etkinleştirilmemesi gerektiğini değerlendirirken özellik filtresinin kullanabileceği ham bir yapılandırmayı temsil eder. Tarayıcı özellik filtresi örneğinde, filtre özelliğini kullanarak Parameters özellik için belirtilen bir izin verilen tarayıcı kümesini ayıklayabilir. Filtre daha sonra isteğin bu tarayıcılardan birinden olup olmadığını denetleyebilir.

[FilterAlias("Browser")]
public class BrowserFilter : IFeatureFilter
{
    …

    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        BrowserFilterSettings settings = context.Parameters.Get<BrowserFilterSettings>() ?? new BrowserFilterSettings();

        //
        // Use the settings to check whether the request is from a browser in BrowserFilterSettings.AllowedBrowsers.
    }
}

Diğer ad filtre özniteliği

Özellik bayrağı için bir özellik filtresi kaydettiğinizde, yapılandırmada kullandığınız takma ad, varsa son eki Filter kaldırılmış olarak özellik filtre türünün adıdır. Örneğin, yapılandırmada MyCriteriaFilter öğesine MyCriteria olarak başvurmanız gerekir.

{
    "id": "MyFeature",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "MyCriteria"
            }
        ]
    }
}

sınıfını FilterAliasAttribute kullanarak bu adı geçersiz kılabilirsiniz. Bir özellik bayrağı içindeki bir özellik filtresine başvurmak üzere yapılandırmada kullanılacak bir ad bildirmek için özellik filtresini bu öznitelikle süsleyebilirsiniz.

Eksik özellik filtreleri

Bir özelliği belirli bir özellik filtresi için etkinleştirilecek şekilde yapılandırdığınız varsayılır. Bu özellik filtresi kayıtlı değilse, özellik değerlendirildiğinde bir istisna atılır. Aşağıdaki kodda gösterildiği gibi, özellik yönetimi seçeneklerini kullanarak özel durumu devre dışı bırakabilirsiniz.

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

HttpContext kullanma

Özellik filtreleri, http isteğinin özelliklerine göre bir özelliğin etkinleştirilip etkinleştirilmeyebileceğini değerlendirebilir. Bu denetim HTTP bağlamı incelenerek gerçekleştirilir. Aşağıdaki kodda gösterildiği gibi, bağımlılık enjeksiyonu kullanılarak IHttpContextAccessor uygulaması elde edilerek, bir özellik filtresi HTTP bağlamına başvuru alabilir.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

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

Kullanılabilir olması için uygulamayı başlangıçtaki bağımlılık ekleme kapsayıcısına eklemeniz IHttpContextAccessor gerekir. Uygulamayı IServiceCollection hizmetlere kaydetmek için aşağıdaki yöntemi kullanabilirsiniz.

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

İleri:IHttpContextAccessor ve HttpContext sunucu tarafı Blazor uygulamalarının Razor bileşenlerinde kullanılmamalıdır. Blazor uygulamalarında HTTP bağlamı geçirmek için önerilen yaklaşım , verileri kapsamlı bir hizmete kopyalamaktır. Blazor uygulamalarında, özellik yönetimi hizmetlerini kaydetmek için kullanmalısınız AddScopedFeatureManagement . Daha fazla bilgi için bu makalenin önceki bölümlerinde yer alan Kapsamlı özellik yönetimi hizmetleri bölümüne bakın.

Özellik değerlendirmesi için bağlam sağlama

Konsol uygulamalarında, özellik filtrelerinin bir özelliğin açık olup olmadığını denetlemek için kullanabileceği ortam HttpContext bağlamı yoktur. Bu durumda, uygulamaların özellik filtreleri tarafından kullanılmak üzere özellik yönetim sisteminin bağlamını temsil eden bir nesne sağlaması gerekir. Bu bağlamı sağlamak için kullanabilirsiniz IVariantFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext) . Bir özelliğin durumunu değerlendirmek için özellik filtreleri özellik yöneticisine appContext sağladığınız nesneyi kullanabilir.

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

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

Bağlamsal özellik filtreleri

Bağlamsal özellik filtreleri arabirimi uygular IContextualFeatureFilter<TContext> . Bu özel özellik filtreleri çağrıldığında IVariantFeatureManager.IsEnabledAsync<TContext> geçirilen bağlamdan yararlanabilir. TContext içindeki IContextualFeatureFilter<TContext> type parametresi, filtrenin işleyebileceği bağlam türünü açıklar. Bağlamsal özellik filtresi geliştirirken, bir bağlam türü belirterek filtreyi kullanma gereksinimlerini belirleyebilirsiniz.

Her türün Object sınıfının alt öğesi olması nedeniyle, herhangi bir sağlanan bağlam için IContextualFeatureFilter<object> uygulayan bir filtre çağrılabilir. Aşağıdaki kod belirli bir bağlamsal özellik filtresi örneği sağlar. Bu kodda, bir hesap etkinleştirilmiş hesapların yapılandırılmış listesindeyse bir özellik etkinleştirilir.

public interface IAccountContext
{
    string AccountId { get; set; }
}

[FilterAlias("AccountId")]
class AccountIdFilter : IContextualFeatureFilter<IAccountContext>
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext featureEvaluationContext, IAccountContext accountId)
    {
        //
        // Evaluate whether the feature should be on by using the IAccountContext that's provided.
    }
}

AccountIdFilter sınıfı, bir özelliğin durumunu değerlendirebilmek için IAccountContext uygulayan bir nesne sağlanmasını gerektirir. Bu özellik filtresini kullandığınızda, çağıranın geçirilen nesnenin IAccountContext uyguladığından emin olması gerekir.

Not

Tek bir tür tarafından yalnızca tek bir özellik filtresi arabirimi uygulanabilir. Tek bir özellik filtresi arabiriminden daha fazlasını uygulayan bir özellik filtresi eklemeye çalışmak bir ArgumentException özel durumla sonuçlanmaya neden olur.

Bağlamsal ve bağlamsal olmayan filtreleri aynı takma adla kullanma

IFeatureFilter ve IContextualFeatureFilter uygulayan filtreler aynı diğer adı paylaşabilir. Özellikle, en fazla bir geçerli filtrenin bulunduğu durumlarda bir filtre diğer adı, sıfır veya bir IFeatureFilter uygulama ve sıfır veya NIContextualFeatureFilter<ContextType> uygulama tarafından paylaşılabilir.

Bir uygulamada aynı ada sahip bağlamsal ve bağlamsal olmayan filtreler kaydedildiğinde filtre seçme işlemini anlamak için aşağıdaki örneği göz önünde bulundurun.

Üç filtre SharedFilterName diğer adını paylaşır.

  • Bağlamsal olmayan bir filtre olan FilterA
  • Bağlamı kabul eden bir FilterB bağlamı olarak adlandırılan TypeB bağlamsal filtre
  • Bağlamı kabul eden bir FilterC bağlamı olarak adlandırılan TypeC bağlamsal filtre

adlı MyFeature bir özellik bayrağı, yapılandırmasında SharedFilterName özellik filtresini kullanır.

Üç filtre de kayıtlıysa:

  • Çağrı yaptığınızda IsEnabledAsync("MyFeature") filtresi, özellik bayrağını değerlendirmek için kullanılır.
  • Çağrı yaptığınızda IsEnabledAsync("MyFeature", context):
    • türü context ise TypeBFilterB kullanılır.
    • türü context ise TypeCFilterC kullanılır.
    • türü context ise TypeFFilterA kullanılır.

Yerleşik özellik filtreleri

Paketiyle birlikte Microsoft.FeatureManagement gelen birkaç özellik filtresi vardır: PercentageFilter, TimeWindowFilter, ContextualTargetingFilterve TargetingFilter. Özellik yönetimini kaydetmek için TargetingFilter yöntemini kullandığınızda, dışındaki tüm filtreler AddFeatureManagement eklenir. TargetingFilter yöntemi kullanılarak WithTargeting eklenir. Daha fazla bilgi için bu makalenin devamında yer alan Hedefleme bölümüne bakın.

Yerleşik özellik filtrelerinin her birinin kendi parametreleri vardır. Aşağıdaki bölümlerde bu özellik filtreleri açıklanır ve örnekler sağlanır.

Microsoft.Percentage

Filtre, Microsoft.Percentage belirli bir yüzdeye göre bir özelliği etkinleştirmenin bir yolunu sağlar.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": 50
                }
            }
        ]
    }
}

Microsoft.TimeWindow

Filtre, Microsoft.TimeWindow bir özelliği bir zaman penceresine göre etkinleştirmenin bir yolunu sağlar.

  • Yalnızca bir End değer belirtirseniz, özellik o zamana kadar açık olarak kabul edilir.
  • Yalnızca bir Start değer belirtirseniz, bu özellik bu sürenin ardından tüm noktalarda açık kabul edilir.
{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                }
            }
        ]
    }
}

Filtreyi, yinelenen olarak bir zaman penceresi uygulayacak şekilde yapılandırabilirsiniz. Bu özellik, bir günün düşük trafikli veya yüksek trafikli bir döneminde veya haftanın belirli günlerinde bir özelliği açmanız gerektiğinde yararlı olabilir. Tek bir zaman penceresini yinelenen bir zaman penceresine genişletmek için, yinelenme kuralı belirtmek için bir Recurrence parametre kullanırsınız.

Not

Yinelenmeyi kullanmak için Start ve End değerlerini belirtmeniz gerekir. Bazı durumlarda, değerin tarih bölümü, filtreyi aktif olarak değerlendirmek için bir bitiş tarihi belirtmez. Bunun yerine filtre, yinelenen zaman penceresinin süresini tanımlamak için başlangıç tarihine göre bitiş tarihini kullanır.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "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"
                        }
                    }
                }
            }
        ]
    }
}

Ayarlar Recurrence iki bölümden oluşur:

  • Ayarlar Pattern , zaman penceresinin ne sıklıkta yineleneceğini belirtir.
  • Ayarlar, Range yineleme düzeninin ne kadar süreyle yineleneceğini belirtir.

Yinelenme düzeni

İki olası yinelenme deseni türü vardır: Daily ve Weekly. Örneğin, bir zaman penceresi her gün, her üç günde, her Pazartesi veya her cuma yinelenebilir.

Türüne bağlı olarak, ayarların Pattern belirli alanları zorunludur, isteğe bağlıdır veya yoksayılır.

  • Daily

    Günlük yinelenme düzeni, zaman penceresinin her oluşum arasındaki belirtilen gün sayısına göre yinelenmesine neden olur.

    Özellik İlgi Açıklama
    Type Zorunlu Yinelenme desen türü. olarak ayarlanmalıdır Daily.
    Interval İsteğe bağlı Her oluşum arasındaki gün sayısı. Varsayılan değer şudur: 1.

  • Weekly

    Haftalık yinelenme düzeni, zaman penceresinin haftanın aynı günü veya günlerinde tekrarlanmalarına neden olur. Ancak her yineleme kümesi arasındaki hafta sayısını belirtebilirsiniz.

    Özellik İlgi Açıklama
    Type Zorunlu Yinelenme desen türü. olarak ayarlanmalıdır Weekly.
    DaysOfWeek Zorunlu Olayın gerçekleştiği haftanın günleri.
    Interval İsteğe bağlı Her yineleme kümesi arasındaki hafta sayısı. Varsayılan değer şudur: 1.
    FirstDayOfWeek İsteğe bağlı Haftanın ilk günü olarak kullanılacak gün. Varsayılan değer şudur: Sunday.

    Aşağıdaki örnek, zaman penceresini her Pazartesi ve Salı günü yineler:

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

Not

Değer, Start yinelenme düzenine uyan geçerli bir ilk oluşum olmalıdır. Ayrıca, zaman penceresinin süresi ne sıklıkta oluştuğundan daha uzun olamaz. Örneğin, 25 saatlik bir zaman penceresi her gün yinelenemez.

Yinelenme aralığı

Üç olası yineleme aralığı türü vardır: NoEnd, EndDate, ve Numbered.

  • NoEnd

    Aralık NoEnd , yinelenmenin süresiz olarak gerçekleşmesine neden olur.

    Özellik İlgi Açıklama
    Type Zorunlu Yinelenme aralığı türü. olarak ayarlanmalıdır NoEnd.

  • EndDate

    Aralık, EndDate zaman penceresinin bitiş tarihine kadar geçerli desene uyan tüm günlerde gerçekleşmesine neden olur.

    Özellik İlgi Açıklama
    Type Zorunlu Yinelenme aralığı türü. olarak ayarlanmalıdır EndDate.
    EndDate Zorunlu Desenin uygulanmasının durdurulacağı tarih ve saat. Son oluşumun başlangıç saati bitiş tarihinden önceyse, bu oluşumun bitiş saati bunun ötesine uzanabilir.

    Aşağıdaki örnekte, zaman penceresi 1 Nisan 2024'teki son oluşuma kadar her gün yineler.

    "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

    Belirlenen Numbered aralığı, zaman penceresinin belirtilen sayıda tekrarlanmasına neden olur.

    Özellik İlgi Açıklama
    Type Zorunlu Yinelenme aralığı türü. olarak ayarlanmalıdır Numbered.
    NumberOfOccurrences Zorunlu Oluşum sayısı.

    Aşağıdaki örnekte, zaman penceresi Pazartesi ve Salı günleri toplam üç kez yinelenerek aşağıdaki tarihlerde gerçekleşir:

    • 1 Nisan Pazartesi
    • 2 Nisan Salı
    • 8 Nisan Pazartesi
    "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
    }
}

Yinelenme kuralı oluşturmak için hem hem de PatternRange ayarlarını belirtmeniz gerekir. Herhangi bir desen türü herhangi bir aralık türüyle çalışabilir.

Gelişmiş: Özelliğin Start saat dilimi uzaklığı yinelenme ayarlarına uygulanır.

Microsoft.Targeting

Filtre, Microsoft.Targeting bir özelliği hedef kitle için etkinleştirmenin bir yolunu sağlar. Hedeflemenin ayrıntılı açıklaması için bu makalenin devamında yer alan Hedefleme bölümüne bakın.

Filtre parametreleri, özelliğe kimlerin erişimi olduğunu açıklayan bir Audience nesne içerir. nesnesinde Audience kullanıcıları, grupları, dışlanan kullanıcıları ve grupları ve kullanıcı tabanının varsayılan yüzdesini belirtebilirsiniz.

Bölümünde listelediğiniz Groups her grup nesnesi için, grup üyelerinin yüzde kaçının erişime sahip olması gerektiğini de belirtmeniz gerekir.

Her kullanıcı için özellik aşağıdaki şekilde değerlendirilir:

  • Kullanıcı dışlanırsa, özellik kullanıcı için devre dışı bırakılır. Kullanıcıyı şu şekilde dışlayabilirsiniz:

    • Users bölümünde Exclusion altında adlarını listeleyin.
    • Groups bölümünde, ait oldukları Exclusion grubunu listeleme

  • Kullanıcı dışlanmazsa, aşağıdaki koşullardan herhangi biri karşılanırsa özellik etkinleştirilir:

    • Users bölümünde kullanıcı listelenir.
    • Kullanıcı, herhangi bir grup dağıtımının dahil olduğu yüzdeye dahildir.
    • Kullanıcı varsayılan dağıtım yüzdesine girer.

  • Önceki servis taleplerinin hiçbiri geçerli değilse, özellik kullanıcı için devre dışı bırakılır. Örneğin, kullanıcı dahil edilen bir yüzdede değilse özellik devre dışı bırakılır.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.Targeting",
                "parameters": {
                    "Audience": {
                        "Users": [
                            "Jeff",
                            "Alicia"
                        ],
                        "Groups": [
                            {
                                "Name": "Ring0",
                                "RolloutPercentage": 100
                            },
                            {
                                "Name": "Ring1",
                                "RolloutPercentage": 50
                            }
                        ],
                        "DefaultRolloutPercentage": 20,
                        "Exclusion": {
                            "Users": [
                                "Ross"
                            ],
                            "Groups": [
                                "Ring2"
                            ]
                        }
                    }
                }
            }
        ]
    }
}

Özellik filtresi takma ad alanları

Tüm yerleşik özellik filtresi diğer adları, Microsoft özellik filtresi ad alanında bulunmaktadır. Bu ad alanında olmak, aynı takma adı paylaşan diğer özellik filtreleriyle çakışmaları önler. Özellik filtresi ad alanının kesimleri karaktere . göre bölünür. Bir özellik filtresine, Microsoft.Percentage gibi, tamamen nitelikli takma adıyla başvurabilirsiniz. Veya son segment gibi Percentage başvurabilirsiniz.

Hedefleme

Hedefleme, yeni özellikleri kullanıcı tabanınıza aşamalı olarak kullanıma sunma amacıyla kullanabileceğiniz bir özellik yönetimi stratejisidir. Strateji, hedef kitle olarak bilinen bir kullanıcı kümesini hedefleme kavramını temel alır. Hedef kitle belirli kullanıcılardan, gruplardan, dışlanan kullanıcılardan ve gruplardan ve tüm kullanıcı tabanının belirlenmiş yüzdelerinden oluşur. Hedef kitleye dahil edilen gruplar, toplam üyelerinin yüzdelerine ayrılabilir.

Aşağıdaki adımlarda Beta adlı yeni bir özellik için aşamalı dağıtım örneği gösterilmektedir:

  1. Bireysel kullanıcılar Jeff ve Alicia'ya Beta özelliğine erişim verilir.
  2. Başka bir kullanıcı, Mark, kabul etmek ister ve dahil edilir.
  3. Ring1 grubundaki kullanıcıların yüzde yirmisi Beta özelliğine dahil edilir.
  4. Dahil edilen Ring1 kullanıcılarının sayısı yüzde 100'e kadar artırılır.
  5. Kullanıcı tabanının yüzde beşi Beta özelliğine dahil edilir.
  6. Kullanıma sunma yüzdesi, özelliği tamamen kullanıma sunma amacıyla yüzde 100'e kadar artırılır.

Kitaplık, yerleşik Microsoft.Targeting özellik filtresi aracılığıyla bir özelliğin dağıtılması için bu stratejiyi destekler.

Web uygulamasında hedefleme

Hedefleme özelliği filtresini kullanan bir web uygulaması örneği için bkz. FeatureFlagDemo örnek projesi.

Uygulamada kullanmaya TargetingFilter başlamak için, bunu diğer özellik filtrelerinde olduğu gibi uygulamanın hizmet koleksiyonuna eklemeniz gerekir. Diğer yerleşik filtrelerin aksine, TargetingFilter uygulamanın hizmet koleksiyonuna eklenecek başka bir hizmete dayanır. Bu hizmet bir ITargetingContextAccessor uygulamadır.

Kitaplık, Microsoft.FeatureManagement.AspNetCore bir isteğin değerinden ITargetingContextAccessor hedef bilgilerini ayıklayan HttpContext uygulamasını sağlar. WithTargeting üzerinde genel IFeatureManagementBuilder olmayan yüklemeyi kullanarak hedeflemeyi ayarlarken varsayılan hedefleme bağlamı erişimcisini kullanabilirsiniz.

Varsayılan hedefleme bağlamı erişimcisini ve TargetingFilter'yi kaydetmek için WithTargeting üzerinde IFeatureManagementBuilder öğesini çağırırsınız.

services.AddFeatureManagement()
        .WithTargeting();

ayrıca ve ITargetingContextAccessor çağrısı TargetingFilteryaparak ve için WithTargeting<T> özelleştirilmiş bir uygulama kaydedebilirsiniz. Aşağıdaki kod, web uygulamasında özellik yönetiminin, TargetingFilter adlı ITargetingContextAccessor uygulamasıyla ExampleTargetingContextAccessor kullanılarak ayarlanmasını sağlar.

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

ITargetingContextAccessor

Bir web uygulamasında TargetingFilter kullanmak için bir ITargetingContextAccessor uygulaması gerekir. Bu gereksinimin ardındaki neden, değerlendirmeleri hedeflemek için kullanıcı hakkındaki bilgiler gibi bağlamsal bilgilerin gerekli olmasıdır. Bu bilgiler sınıfın TargetingContext örneklerinde depolanır. Farklı uygulamalar bu bilgileri isteğin HTTP bağlamı veya veritabanı gibi farklı yerlerden ayıklar.

Bir uygulamanın HTTP bağlamından hedefleme bağlam bilgilerini ayıklayan bir örnek için pakete DefaultHttpTargetingContextAccessor bakınMicrosoft.FeatureManagement.AspNetCore. Aşağıdaki bilgileri ayıklar:

  • HttpContext.User özelliğinden bilgilerini hedefleme
  • UserId Identity.Name alandaki bilgiler
  • Groups tür iddialardan veya beyanlardan gelen bilgiler Role

Bu uygulama, IHttpContextAccessor kullanımına dayanır. hakkında IHttpContextAccessordaha fazla bilgi için bu makalenin önceki bölümlerinde yer alan HttpContext kullanma bölümüne bakın.

Konsol uygulamasında hedefleme

Hedefleme filtresi, bir özelliğin açık olup olmadığını değerlendirmek için bir hedefleme bağlamını kullanır. Bu hedefleme bağlamı, değerlendirilen kullanıcı ve kullanıcının ait olduğu gruplar gibi bilgileri içerir. Konsol uygulamalarında genellikle bu bilgileri hedefleme filtresine geçirmek için kullanılabilir ortam bağlamı yoktur. Sonuç olarak, FeatureManager.IsEnabledAsync çağırdığınızda onu doğrudan geçirmeniz gerekir. Bu bağlam türü ContextualTargetingFilter kullanılarak desteklenir. Hedefleme bağlamını özellik yöneticisine göndermesi gereken uygulamalar, ContextualTargetingFilter yerine TargetingFilter. kullanmalıdır.

ContextualTargetingFilter IContextualTargetingFilter<ITargetingContext> uyguladığından, bir ITargetingContext özelliğini değerlendirebilmesi ve açabilmesi için IVariantFeatureManager.IsEnabledAsync'a uygulamasını geçirmeniz gerekmektedir.

IVariantFeatureManager fm;
…
// The userId and groups variables are defined earlier in the application.
TargetingContext targetingContext = new TargetingContext
{
   UserId = userId,
   Groups = groups
};

await fm.IsEnabledAsync(featureName, targetingContext);

ContextualTargetingFilter özellik filtresi diğer adını Microsoft.Targetingkullanır, bu nedenle bu filtrenin yapılandırması bu makalenin önceki bölümlerinde yer alan Microsoft.Targeting'deki bilgilerle tutarlıdır.

Konsol uygulamasında kullanan ContextualTargetingFilter bir örnek için Bkz. TargetingConsoleApp örnek projesi.

Değerlendirme seçeneklerini hedefleme

Tüm özelliklerde hedefleme değerlendirmesinin nasıl gerçekleştirildiğini özelleştirmek için seçenekler sağlanır. Özellik yönetimini ayarlarken bu seçenekleri yapılandırabilirsiniz.

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

Hedef dışlama

Bir hedef kitle tanımladığınızda, kullanıcıları ve grupları hedef kitlenin dışında tutabilirsiniz. Bu işlev, bir özelliği bir kullanıcı grubuna dağıttığınızda faydalıdır. Ancak, birkaç kullanıcıyı veya grubu hariç tutmanız gerektiğinde de bu işlevi kullanabilirsiniz. Dışlanması gereken kullanıcıları ve grupları belirtmek için hedef kitlenin Exclusion özelliğini kullanırsınız.

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

Yukarıdaki kod, Jeff ve Alicia adlı kullanıcılar için bir özelliği etkinleştirir. Özellik, adlı Ring0gruptaki kullanıcılar için de etkinleştirilir. Ancak, Mark grubunda olsa bile, Ring0 adlı kullanıcı için özellik devre dışı bırakılır. Dışlamalar, hedefleme filtresinin geri kalanından önceliklidir.

Varyantlar

Bazen uygulamaya yeni bir özellik eklediğinizde, özelliğin birden çok tasarım seçeneği vardır. A/B testi, tasarıma karar vermek için ortak bir çözüm sağlar. A/B testi, özelliğin farklı bir sürümünü kullanıcı tabanının farklı segmentlerine sağlamayı ve ardından kullanıcı etkileşimini temel alan bir sürüm seçmeyi içerir. .NET özellik yönetimi kitaplığında, bir özelliğin çeşitli yapılandırmalarını temsil eden varyantları kullanarak A/B testi uygulayabilirsiniz.

Varyantlar, bir özellik bayrağının işlevini basit bir açık/kapalı bayraktan daha fazlasına dönüştürmek için bir yöntem sunar. Değişken, bir özellik bayrağının dize, sayı, Boole, hatta yapılandırma nesnesi olabilecek bir değerini temsil eder. Varyantları bildiren bir özellik bayrağı, her bir değişkenin hangi koşullarda kullanılması gerektiğini tanımlamalıdır. Daha fazla bilgi için bu makalenin devamında yer alan Çeşitleme ayırma bölümüne bakın.

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

Varyantları alma

Her özellik için, GetVariantAsync arabiriminin IVariantFeatureManager yöntemini kullanarak bir varyant alabilirsiniz.

…
IVariantFeatureManager featureManager;
…
Variant variant = await featureManager.GetVariantAsync("MyVariantFeatureFlag", CancellationToken.None);

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration.

Bir değişkeni aldıktan sonra, bu değişkenin yapılandırmasını, değişkenin IConfigurationSection özelliğinden alınan Configuration uygulaması olarak doğrudan kullanabilirsiniz. Bir diğer seçenek de .NET yapılandırma bağlama desenini kullanarak yapılandırmayı bir nesneye bağlamaktır.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

Döndürülen değişken, değerlendirilen kullanıcıya bağlıdır. TargetingContext örneğinden kullanıcı hakkında bilgi edinebilirsiniz. GetVariantAsync çağırdığınızda bu bağlamı iletebilirsiniz. Ya da bir ITargetingContextAccessor uygulaması kayıtlıysa, otomatik olarak alınabilir.

Değişken özellik bayrağı bildirimi

Standart özellik bayraklarıyla karşılaştırıldığında, değişken özellik bayrakları iki ek özelliğe sahiptir: variants ve allocation. variants özelliği, özellik için tanımlanan değişkenleri içeren bir dizidir. özelliği, allocation bu varyantların özellik için nasıl ayrılacaklarını tanımlar. Standart özellik bayraklarını bildirme gibi, bir JSON dosyasında da değişken özellik bayrakları ayarlayabilirsiniz. Aşağıdaki kod, değişken özellik bayrağı örneğidir:

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

Varyantları tanımlama

Her değişken iki özelliğe sahiptir: ad ve yapılandırma. Ad, belirli bir değişkene başvurmak için kullanılır ve yapılandırma bu değişkenin değeridir. Yapılandırmasını belirtmek için özelliğini kullanabilirsiniz configuration_value . configuration_value özelliği dize, sayı, Boole veya yapılandırma nesnesi olabilecek satır içi bir yapılandırmadır. configuration_value özelliğini yapılandırmazsanız, döndürülen değişkenin Configuration özelliği null olur.

Bir özelliğin tüm olası değişkenlerini belirtmek için bunları özelliği altında variants listelersiniz.

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

Çeşitlemeleri ayırmak

Bir özelliğin değişkenlerini ayırmak için özelliğin allocation özelliğini kullanırsınız.

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

Ayar allocation aşağıdaki özelliklere sahiptir:

Özellik Açıklama
default_when_disabled Özellik devre dışı olarak kabul edilirken bir değişken istendiğinde kullanılacak değişken.
default_when_enabled Özellik etkin kabul edildiğinde ve kullanıcıya başka bir değişken atanmadığında, bir değişken istendiğinde kullanılacak değişken.
user Değişken ve değişken atanacak kullanıcıların listesi.
group Bir değişken ve grupların listesi. Kullanıcı gruplardan en az birindeyse değişken atanır.
percentile Atanacak varyant için, kullanıcının hesaplanan yüzdesinin uyması gereken bir varyant ve yüzde aralığı vardır.
seed percentile için yüzde hesaplamalarının temel alındığı değer. Belirli bir kullanıcı için yüzde hesaplaması, aynı değer kullanılıyorsa tüm özelliklerde aynıdır seed . Değer seed belirtilmezse, özellik adına göre varsayılan bir tohum oluşturulur.

Özellik etkinleştirilmemişse, özellik yöneticisi için belirtilen default_when_disabled değişkeni geçerli kullanıcıya atar. Yukarıdaki örnekte bu özellik olarak adlandırılır Small.

Özellik etkinleştirilirse, özellik yöneticisi bir varyant atamak için user, group, ve percentile ayırmalarını bu sırayla denetler. Yukarıdaki örnekte, belirtilen değişken, Bigaşağıdaki durumlarda kullanıcıya atanır:

  • Değerlendirilen kullanıcının adı Marsha.
  • Kullanıcı Ring1 grubundadır.
  • Kullanıcı, sıfır ile onuncu yüzdebirlik arasında yer alır.

Bu ayırmaların hiçbiri eşleşmiyorsa, default_when_enabled değişken kullanıcıya atanır. Örnekte bu değişken şeklindedir Small.

Ayırma mantığı, Microsoft.Targeting özellik filtresi için kullandığınız mantığa benzer. Ancak, hedeflemede var olan ve ayırmada olmayan bazı parametreler vardır ve tam tersi de geçerlidir. Hedefleme ve ayırmanın sonuçları ilişkili değildir.

Not

Özellik değişkenlerini ayırmak için ITargetingContextAccessor kaydını, WithTargeting<T> metodunu çağırarak yapmanız gerekir.

Değişken kullanarak etkin durumu geçersiz kılma

Özellik bayrağının etkin durumunu geçersiz kılmak için varyantları kullanabilirsiniz. Bu işlevden yararlandığınızda, özellik bayrağı değerlendirmesini genişletebilirsiniz. Değişkenli bir bayrak için IsEnabledAsync çağrısı sırasında, özellik yöneticisi, geçerli kullanıcıya atanan değişkenin sonucu geçersiz kılmak üzere yapılandırılmış olup olmadığını denetler.

İsteğe bağlı variant özelliği status_override kullanarak geçersiz kılma uygulayabilirsiniz. Bu özellik aşağıdaki değerlere sahip olabilir:

  • None: Değişken, bayrağın etkin veya devre dışı olarak kabul edilip edilmediğini etkilemez. None varsayılan değerdir.
  • Enabled: Değişken seçildiğinde özellik bayrağı etkin olarak değerlendirilir.
  • Disabled: Değişken seçildiğinde özellik bayrağı devre dışı olarak değerlendirilir.

enabled durumundaki bir false özelliği geçersiz kılamazsınız.

İkili değişkenlerle bir özellik bayrağı kullanırsanız özellik status_override yararlı olabilir. Uygulamanızda IsEnabledAsync ve FeatureGateAttribute gibi API'leri kullanmaya devam edebilirsiniz. Ancak, değişkenlerle birlikte gelen özellikler olan yüzdelik dilim tahsisi ve yüzde hesaplamaları için tohum değeri kullanımı gibi avantajlardan da yararlanabilirsiniz.

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

Yukarıdaki örnekte özellik her zaman etkindir. Geçerli kullanıcı 10 ile 20 arasında hesaplanan yüzde birlik aralığındaysa, On varyantı döndürülür. Aksi takdirde Off varyantı döndürülür ve status_override değeri Disabled olduğundan, özellik devre dışı olarak kabul edilir.

Bağımlılık enjeksiyonundaki varyantlar

Bir hizmetin farklı uygulamalarını farklı kullanıcılara göstermek için bağımlılık ekleme ile birlikte değişken özellik bayraklarını kullanabilirsiniz. Bu birleşimi gerçekleştirmek için IVariantServiceProvider<TService> arabirimi bir yol sağlar.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken);

Önceki kodda IVariantServiceProvider<IAlgorithm>, bağımlılık enjeksiyonu kapsayıcısından IAlgorithm uygulamasını alır. Seçilen uygulama aşağıdakilere bağlıdır:

  • Hizmetin kayıtlı olduğu özellik bayrağı IAlgorithm .
  • Bu özellik için ayrılan değişken.

Uygulama IVariantServiceProvider<T> , aşağıdaki örnekte gösterildiği gibi çağrısı IFeatureManagementBuilder.WithVariantService<T>(string featureName)yapılarak uygulamanın kullanımına sunulur. Bu koddaki çağrı, hizmet koleksiyonunda kullanılabilir hale getirir IVariantServiceProvider<IAlgorithm> .

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

Her uygulamayı IAlgorithm gibi services.AddSingleton<IAlgorithm, SomeImplementation>() bir ekleme yöntemiyle ayrı ayrı eklemeniz gerekir. IAlgorithm kullanan IVariantServiceProvider uygulaması, ForecastAlgorithm varyant özellik bayrağına bağlıdır. Hizmet koleksiyonuna IAlgorithm uygulanması eklenmediği takdirde, IVariantServiceProvider<IAlgorithm>.GetServiceAsync(), null sonucunu içeren bir görev döndürür.

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

Değişken hizmet takma adı özniteliği

Değişken hizmet sağlayıcısı, ayrılan değişkenle eşleştirmek için uygulamaların tür adlarını kullanır. Bir değişken hizmeti ile VariantServiceAliasAttributedekore edilmişse, bu öznitelikte bildirilen ad, bu değişken hizmete başvurmak için yapılandırmada kullanılmalıdır.

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

Telemetri

Özellik bayrağı değişikliğini dağıttığınızda, bunun uygulama üzerindeki etkisini analiz etmek genellikle önemlidir. Örneğin, ortaya çıkabilecek birkaç soru şunlardır:

  • Bayraklar beklendiği gibi etkin ve devre dışı mı?
  • Hedeflenen kullanıcılar beklendiği gibi belirli bir özelliğe erişiyor mu?
  • Belirli bir kullanıcı hangi çeşitle görüşüyor?

Özellik bayrağı değerlendirme olaylarının emisyonu ve analizi bu tür soruları yanıtlamanıza yardımcı olabilir. .NET özellik yönetim kütüphanesi, özellik bayrağı değerlendirmesi esnasında izleme telemetrisini oluşturmak için System.Diagnostics.Activity API'sini kullanır.

Telemetriyi etkinleştirme

Varsayılan olarak, özellik bayraklarında telemetri gösterilmez. Belirli bir özellik bayrağı için telemetri yayımlamak için bayrağın telemetri emisyonu için etkinleştirildiğini bildirmesi gerekir .

appsettings.jsoniçinde tanımlanan özellik bayrakları için özelliğini kullanarak telemetriyi telemetry etkinleştirebilirsiniz.

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

Bir appsettings.json dosyasındaki yukarıdaki kod, telemetri için etkinleştirilmiş bir özellik bayrağını tanımlar. Telemetri durumu, telemetry tarafından enabled nesnesinin true olarak ayarlanmasıyla belirtilir. özelliğinin enabled değeri, bayrak için telemetri yayımlamak için olmalıdır true .

Özellik telemetry bayrağının bölümü aşağıdaki özelliklere sahiptir:

Özellik Açıklama
enabled Özellik bayrağı için telemetri verisinin yayınlanıp yayınlanmayacağını belirten Boolean değeri.
metadata Değerlendirme olaylarına özellik bayrağıyla ilgili özel meta verileri eklemek için kullanabileceğiniz, sözlük olarak modellenmiş anahtar-değer çiftleri koleksiyonu.

Not

.NET yapılandırma sağlayıcısını Azure Uygulama Yapılandırması ile kullandığınızda, telemetri etkinleştirildiğinde özellik bayrağı değerlendirmesine ek telemetri meta verileri eklenir.

Özel telemetri yayımlama

Özellik yöneticisinin ActivitySource adlı kendi Microsoft.FeatureManagement örneği vardır. Telemetri özellik bayrağı için etkinleştirildiyse:

  • Özellik bayrağı değerlendirmesi başladığında, özellik yöneticisi bir Activity örneği başlatır.
  • Özellik bayrağı değerlendirmesi tamamlandığında, özellik yöneticisi geçerli etkinliğe adlı ActivityEvent bir FeatureFlag örnek ekler.

Olay, FeatureFlag özellik bayrağı değerlendirmesi hakkındaki bilgileri içeren etiketlere sahiptir. Etiketler , FeatureEvaluationEvent şemasında tanımlanan alanları kullanır.

Not

Özellik bayrağının telemetry.metadata özelliğinde belirtilen tüm anahtar-değer çiftleri de etiketlere eklenir.

Özel telemetri yayımlamayı etkinleştirmek için bir ActivityListener örneği oluşturabilir ve Microsoft.FeatureManagement etkinlik kaynağını dinleyebilirsiniz. Aşağıdaki kod, özellik yönetimi etkinlik kaynağını dinlemeyi ve bir özellik değerlendirildiğinde geri çağırma eklemeyi gösterir.

ActivitySource.AddActivityListener(new ActivityListener()
{
    ShouldListenTo = (activitySource) => activitySource.Name == "Microsoft.FeatureManagement",
    Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllData,
    ActivityStopped = (activity) =>
    {
        ActivityEvent? evaluationEvent = activity.Events.FirstOrDefault((activityEvent) => activityEvent.Name == "FeatureFlag");

        if (evaluationEvent.HasValue && evaluationEvent.Value.Tags.Any())
        {
            // Do something.
        }
    }
});

Daha fazla bilgi için bkz. Dağıtılmış izleme toplama.

Application Insights telemetrisi

Paket, Microsoft.FeatureManagement.Telemetry.ApplicationInsights Application Insights'a özellik bayrağı değerlendirme verileri gönderen yerleşik bir telemetri yayımcısı sağlar. Paket Microsoft.FeatureManagement.Telemetry.ApplicationInsights ayrıca, olayların bayrak değerlendirmelerine bağlanabilmesi için tüm olayları TargetingId ile otomatik olarak etiketleyen bir telemetri başlatıcısı sağlar. Bu işlevden yararlanmak için pakete bir bağımlılık ekleyin ve Application Insights telemetrisini kaydedin. Aşağıdaki kod bir örnek sağlar:

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

Not

Application Insights telemetrisinin beklendiği gibi çalıştığından emin olmak için sınıfını TargetingHttpContextMiddleware kullanmanız gerekir.

Geçerli etkinlikte hedefleme bağlamının kalıcılığını etkinleştirmek için sınıfını TargetingHttpContextMiddleware kullanabilirsiniz.

app.UseMiddleware<TargetingHttpContextMiddleware>();

Kullanım örneği için VariantAndTelemetryDemo örneğine bakın.

Önkoşul

Paketin sağladığı telemetri yayımcısı Microsoft.FeatureManagement.Telemetry.ApplicationInsights , Application Insights'ın bir uygulama hizmeti olarak ayarlanmasını ve kaydedilmesini gerektirir. Örnek kod için VariantAndTelemetryDemo örnek uygulamasına bakın.

Önbelleğe Alma

Özellik durumu sistem tarafından IConfiguration sağlanır. Yapılandırma sağlayıcılarının önbelleğe alma ve dinamik güncelleştirme işlemlerini işlemesi beklenir. Özellik yöneticisi, bir özelliğin etkinleştirilip etkinleştirilmediğini değerlendirdiği her durumda özelliğin durumunun en son değerini ister IConfiguration .

Anlık Görüntü

Bazı senaryolar, bir özelliğin durumunun isteğin ömrü boyunca tutarlı kalmasını gerektirir. Standart IVariantFeatureManager bir uygulamadan döndürülen değerler, istek sırasında çekeceği kaynak güncelleştirilirse IConfiguration değişebilir.

kullanarak IVariantFeatureManagerSnapshotbu davranışı önleyebilirsiniz. IVariantFeatureManagerSnapshot ile aynı şekilde IVariantFeatureManager alabilirsiniz. IVariantFeatureManagerSnapshot arabirimini IVariantFeatureManager uygular, ancak IVariantFeatureManagerSnapshot istek sırasında bir özelliğin ilk değerlendirilen durumunu önbelleğe alır. Özelliğin kullanım ömrü boyunca bu durumu döndürür.

Özel özellik sağlayıcıları

Özel bir özellik sağlayıcısı uyguladığınızda, veritabanı veya özellik yönetimi hizmeti gibi kaynaklardan özellik bayrakları çekebilirsiniz. Varsayılan özellik sağlayıcısı özellik bayraklarını .NET Core yapılandırma sisteminden çeker. Bu sistem, birappsettings.json dosyasında veya Azure Uygulama Yapılandırması gibi yapılandırma sağlayıcılarında özellikleri tanımlama desteği sağlar. Özellik tanımlarının nereden okunabileceğini denetlemek için bu davranışı özelleştirebilirsiniz.

Özellik tanımlarının yüklenmesini özelleştirmek için arabirimini IFeatureDefinitionProvider uygulamanız gerekir.

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

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

IFeatureDefinitionProvider uygulamasını kullanmak için, bunu özellik yönetimini eklemeden önce hizmet koleksiyonuna eklemeniz gerekir. Aşağıdaki örnek adlı IFeatureDefinitionProvideruygulamasını InMemoryFeatureDefinitionProvider ekler.

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

Sonraki adımlar

Uygulamalarınızda özellik bayraklarının nasıl kullanılacağını öğrenmek için aşağıdaki hızlı başlangıçlara bakın:

ASP.NET Core

.NET/.NET Framework konsol uygulaması

.NET arka plan hizmeti

Özellik filtrelerini kullanmayı öğrenmek için aşağıdaki öğreticilere bakın:

Özellik filtreleri ile koşullu özellikleri etkinleştirme

Zamanlamaya göre özellikleri etkinleştirme

Özellikleri hedeflenen hedef kitlelere sunma

  • Last updated on