Aracılığıyla paylaş


.NET Özellik Yönetimi

Microsoft.FeatureManagement
Microsoft.FeatureManagement.AspNetCore

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

.NET özellik yönetimi kitaplığı, özellik bayraklarına göre uygulama işlevselliği geliştirmenin ve kullanıma sunmanın bir yolunu sağlar. Yeni bir özellik geliştirildikten sonra, 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 ve ayrıca bu özelliklerin kullanıma sunulmasını mümkün kılmak için ortak .NET kod desenleriyle tümleştirilir.

Özellik bayrakları, .NET ve ASP.NET Core uygulamalarının özellikleri dinamik olarak açması veya kapatması için bir yol sağlar. Geliştiriciler, koşullu olarak yol veya MVC filtreleri ekleme gibi daha gelişmiş senaryolar için koşullu deyimler gibi basit kullanım örneklerinde özellik bayraklarını kullanabilir. Ö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ığı kullanmanın avantajlarından bazıları şunlardır:

  • Özellik yönetimi için ortak bir kural

  • Düşük giriş engeli

    • Yerleşik IConfiguration
    • JSON dosya özelliği bayrağı kurulumunu destekler
  • Özellik Bayrağı yaşam süresi yönetimi

    • Yapılandırma değerleri gerçek zamanlı olarak değişebilir; özellik bayrakları isteğin tamamında tutarlı olabilir
  • Ele Alınan Basit ve Karmaşık Senaryolar

    • Bildirim temelli yapılandırma dosyası aracılığıyla özellikleri açma/kapatma
    • Sunucu çağrısına göre özelliğin durumunu dinamik olarak değerlendirme
  • ASP.NET Core ve MVC çerçevesi için API uzantıları

    • Yönlendirme
    • Filtreler
    • Eylem Öznitelikleri

    .NET özellik yönetimi kitaplığı açık kaynak. Daha fazla bilgi için GitHub deposunu ziyaret edin.

Özellik Bayrakları

Özellik bayrakları, özelliği açmak için kullanılan bir ad ve özellik filtreleri listesi olmak üzere iki bölümden oluşur.

Özellik Filtreleri

Özellik filtreleri, bir özelliğin ne zaman etkinleştirilmesi gerektiğine yönelik bir senaryo tanımlar. Özellik açık mı yoksa kapalı mı olduğu değerlendirildiğinde, filtrelerden biri özelliğin etkinleştirilmesi gerektiğine karar verene kadar özellik filtreleri listesinden geçilir. Bu noktada özellik etkin olarak kabul edilir ve özellik filtreleri durakları arasında geçiş yapılır. Özellik filtresi özelliğin etkinleştirilmesi gerektiğini belirtmiyorsa devre dışı olarak kabul edilir.

Örneğin, bir Microsoft Edge tarayıcı özellik filtresi tasarlanabilir. Bu özellik filtresi, Bir HTTP isteği Microsoft Edge'den geldiği sürece 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 şeklindedir 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'den Azure Uygulaması Yapılandırmasına ve daha fazlasına kadar çeşitli senaryolar sağlar.

Özellik Bayrağı Bildirimi

Özellik yönetim kitaplığı, .NET Core IConfiguration sisteminin sağlayıcısı olduğundan özellik bayrağı kaynağı olarak appsettings.json destekler. Aşağıda bir json dosyasında özellik bayraklarını ayarlamak için kullanılan biçime bir örnek verilmiştir.

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

FeatureManagement json belgesinin bölümü, özellik bayrağı ayarlarını yüklemek için kural tarafından kullanılır. Yukarıdaki bölümde üç farklı özellik görüyoruz. Özellikler, özelliğini kullanarak EnabledFor özellik filtrelerini tanımlar. için FeatureTözellik filtrelerinde öğesini görüyoruz AlwaysOn. Bu özellik filtresi yerleşiktir ve belirtilirse özelliği her zaman etkinleştirir. Özellik AlwaysOn filtresi herhangi bir yapılandırma gerektirmez, bu nedenle yalnızca özelliğine Name sahiptir. FeatureU özelliğinde EnabledFor filtre yoktur ve bu nedenle hiçbir zaman etkinleştirilmez. Özellik filtreleri boş kaldığı sürece, bu özelliğin etkinleştirilmesini gerektiren işlevlere erişilemez. Ancak, özelliği etkinleştiren bir özellik filtresi eklendiği anda çalışmaya başlayabilir. FeatureV adlı TimeWindowbir özellik filtresi belirtir. Bu, yapılandırılabilir özellik filtresi örneğidir. Örnekte filtrenin bir Parameters özelliği olduğunu görebiliriz. Bu, 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.

Bölümün FeatureManagement ayrıntılı şemasına buradan ulaşabilirsiniz.

Gelişmiş: Özellik bayrağı adlarında ':' iki nokta üst üste kullanımı yasaktır.

Açık/Kapalı Bildirimi

Aşağıdaki kod parçacığında, açık/kapalı özellikler için kullanılabilecek bir özelliği tanımlamanın alternatif bir yolu gösterilmektedir.

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

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

Gereksinim Türü

RequirementType Özellik bayrağının özelliği, bir özelliğin durumunu değerlendirirken filtrelerin mi yoksa All mantığın mı kullanılacağını Any belirlemek için kullanılır. Belirtilmezse RequirementType , varsayılan değer olur Any.

  • Any , özelliğin etkinleştirilmesi için yalnızca bir filtrenin true olarak hesaplanması gerektiği anlamına gelir.
  • All , özelliğin etkinleştirilmesi için her filtrenin true olarak hesaplanması gerektiği anlamına gelir.

Geçiş RequirementType değişikliklerinden biri All . İlk olarak, filtre yoksa özellik devre dışı bırakılır. Ardından, filtrelerden biri özelliğin devre dışı bırakılması gerektiğine karar verene kadar özellik filtreleri geçirilir. Hiçbir filtre özelliğin devre dışı bırakılması gerektiğini belirtmezse etkin olarak kabul edilir.

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

Yukarıdaki örnekte, FeatureW özelliğinin etkinleştirilmesi Alliçin tüm filtrelerinin true olarak hesaplanması gerektiği anlamına gelen öğesini RequirementType belirtir. Bu durumda özellik, belirtilen zaman penceresinde kullanıcıların %50'sinde etkinleştirilir.

Microsoft Özellik Yönetimi Şeması

Özellik yönetimi kitaplığı, özellik bayraklarını bildirmek için özelliğinin Microsoft Feature Management schema kullanımını da destekler. Bu şema, kaynak dilinden bağımsızdır ve tüm Microsoft özellik yönetimi kitaplıkları tarafından desteklenir.

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

Not

feature_management Bölüm yapılandırmada bulunabilirse bölüm FeatureManagement yoksayılır.

Özellik yönetim kitaplığı, .NET Core IConfiguration sisteminin sağlayıcısı olduğundan özellik bayrağı kaynağı olarak appsettings.json destekler. Özellik bayrakları kullanılarak Microsoft Feature Management schemabildirilir. Bu şema, kaynak dilinden bağımsızdır ve tüm Microsoft özellik yönetimi kitaplıkları tarafından desteklenir.

Aşağıda bir json dosyasında özellik bayrakları bildirme örneği verilmiştir.

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

feature_management json belgesinin bölümü, özellik bayrağı ayarlarını yüklemek için kural tarafından kullanılır. Özellik bayrağı nesneleri, bölümün feature_flags altındaki dizide feature_management listelenmelidir. Yukarıdaki bölümde üç farklı özellik sağladığımızı görüyoruz. Özellik bayrağının ve enabled özellikleri vardırid. id, özellik bayrağını tanımlamak ve bunlara başvurmak için kullanılan addır. özelliği özellik enabled bayrağının etkin durumunu belirtir. Bir özellik false ise enabled KAPALI olur. enabled True ise, özelliğin durumu öğesine bağlıdırconditions. conditions Yoksa özellik ON'dır. Varsa conditions ve karşılanıyorsa özellik ON'dır. Varsa conditions ve karşılanmazsa özellik KAPALI olur. özelliği, conditions özelliği dinamik olarak etkinleştirmek için kullanılan koşulları bildirir. Özellikler, dizideki client_filters özellik filtrelerini tanımlar. FeatureV adlı Microsoft.TimeWindowbir özellik filtresi belirtir. Bu, yapılandırılabilir özellik filtresi örneğidir. Örnekte filtrenin bir Parameters özelliği olduğunu görebiliriz. Bu, 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.

Gelişmiş: Özellik bayrağı adlarında ':' iki nokta üst üste kullanımı yasaktır.

Gereksinim Türü

requirement_type özelliği, bir özelliğin conditions durumunu değerlendirirken filtrelerin mi yoksa All mantığın mı kullanılacağını Any belirlemek için kullanılır. Belirtilmezse requirement_type , varsayılan değer olur Any.

  • Any , özelliğin etkinleştirilmesi için yalnızca bir filtrenin true olarak hesaplanması gerektiği anlamına gelir.
  • All , özelliğin etkinleştirilmesi için her filtrenin true olarak hesaplanması gerektiği anlamına gelir.

Geçiş requirement_type değişikliklerinden biri All . İlk olarak, filtre yoksa özellik devre dışı bırakılır. Filtreler varsa, filtrelerden biri özelliğin devre dışı bırakılması gerektiğine karar verene kadar özellik filtreleri 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": "Mon, 01 May 2023 13:59:59 GMT",
                    "End": "Sat, 01 Jul 2023 00:00:00 GMT"
                }
            },
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": "50"
                }
            }
        ]
    }
}

Yukarıdaki örnekte, FeatureW özelliğinin etkinleştirilmesi Alliçin tüm filtrelerinin true olarak hesaplanması gerektiği anlamına gelen öğesini requirement_type belirtir. Bu durumda özellik, belirtilen zaman penceresinde kullanıcıların %50'sinde etkinleştirilir.

.NET Özellik Yönetimi şeması

Önceki sürümlerde, özellik yönetimi kitaplığının birincil şeması şeklindeydi .NET feature management schema. v4.0.0 sürümünden başlayarak, .NET özellik yönetimi şeması için çeşitlemeler ve telemetri dahil olmak üzere yeni özellikler desteklenmez.

Not

hem hem FeatureManagement de feature_management bölümlerinde bulunabilen bir özellik bayrağı bildirimi varsa, bölümdeki feature_management bildirim benimsenecektir.

Tüketim

Özellik yönetiminin temel biçimi, özellik bayrağının etkinleştirilip etkinleştirilmediğini denetlemek ve ardından sonucta göre eylemler gerçekleştirmektir. Bu, 'nin IsEnabledAsync yöntemiyle IFeatureManagergerçekleştirilir.

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

Hizmet Kaydı

Özellik yönetimi .NET Core bağımlılık eklemeye dayanır. Özellik yönetim hizmetlerini standart kuralları kullanarak kaydedebiliriz.

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 "FeatureManagement" bölümünden özellik bayrağı yapılandırmasını alır. "FeatureManagement" bölümü yoksa, yapılandırma boş olarak kabul edilir.

Not

Ayrıca, özellik bayrağı yapılandırmasının bölümü'ne geçirilerek farklı bir yapılandırma bölümünden AddFeatureManagementalınması gerektiğini belirtebilirsiniz. Aşağıdaki örnek, özellik yöneticisine bunun yerine "MyFeatureFlags" adlı farklı bir bölümden okumasını söyler:

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

Bağımlılık Ekleme

MVC ile özellik yönetimi kitaplığı kullanılırken, IFeatureManager bağımlılık ekleme yoluyla elde edilebilir.

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

Kapsamlı Özellik Yönetim Hizmetleri

AddFeatureManagement yöntemi, özellik yönetimi hizmetlerini uygulama içinde tekil olarak ekler, ancak bunun yerine özellik yönetim hizmetlerinin kapsamlı hizmetler olarak eklenmesinin gerekli olabileceği senaryolar vardır. Örneğin, kullanıcılar bağlam bilgileri için kapsamlı hizmetleri kullanan özellik filtrelerini kullanmak isteyebilir. Bu durumda bunun AddScopedFeatureManagement yerine yöntemi kullanılmalıdır. Bu, özellik filtreleri de dahil olmak üzere özellik yönetimi hizmetlerinin kapsamlı hizmetler olarak eklenmesini sağlar.

services.AddScopedFeatureManagement();

ASP.NET Çekirdek 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 yürütmek için belirli bir özelliğin veya herhangi bir özellik listesinden birinin etkinleştirilmesini gerektirebilir. Bu, ad alanında Microsoft.FeatureManagement.Mvc bulunabilen bir FeatureGateAttributekullanılarak yapılabilir.

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

Yukarıdaki HomeController "FeatureX" tarafından geçitlenmiştir. İçeren herhangi bir eylemin HomeController yürütülebilmesi için önce "FeatureX" etkinleştirilmelidir.

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

Index Yukarıdaki MVC eylemi yürütülmeden önce "FeatureX" öğesinin etkinleştirilmesini gerektirir.

Devre Dışı Eylem İşleme

Bir MVC denetleyicisi veya eylemi, belirttiği özelliklerden hiçbiri etkinleştirilmediğinden engellendiğinde, kayıtlı IDisabledFeaturesHandler bir çağrılır. Varsayılan olarak, HTTP 404 döndüren minimalist bir işleyici kaydedilir. Bu, özellik bayraklarını kaydederken kullanılarak IFeatureManagementBuilder geçersiz kılınabilir.

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

Görünüm

MVC görünümlerinde <feature> etiketler, bir özelliğin etkinleştirilip etkinleştirilmediğine bağlı olarak içeriği koşullu olarak işlemek için kullanılabilir.

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

Ayrıca, bir özellik veya özellik kümesi devre dışı bırakıldığında içeriği görüntülemek için etiket yardımcısı değerlendirmesini olumsuzlayabilirsiniz. Aşağıdaki örnekteki ayara göre negate="true" içerik yalnızca devre dışı bırakıldığında FeatureX işlenir.

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

etiketi, <feature> özniteliğindeki name özelliklerin virgülle ayrılmış bir listesini belirterek birden çok özelliğe başvurabilir.

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

Özellik etiketinin işlenmesi için listelenen tüm özelliklerin varsayılan olarak etkinleştirilmesi gerekir. Bu davranış, aşağıdaki örnekte görüldüğü gibi özniteliği eklenerek requirement geçersiz kılınabilir.

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

MVC görünümlerinde <feature> etiketler, bir özelliğin etkinleştirilip etkinleştirilmediğine veya özelliğin belirli bir değişkeninin atanıp atanmadığına bağlı olarak içeriği koşullu olarak işlemek için kullanılabilir. Daha fazla bilgi için varyantlar bölümüne bakın.

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

Ayrıca, bir özellik veya özellik kümesi devre dışı bırakıldığında içeriği görüntülemek için etiket yardımcısı değerlendirmesini olumsuzlayabilirsiniz. Aşağıdaki örnekteki ayara göre negate="true" içerik yalnızca devre dışı bırakıldığında FeatureX işlenir.

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

etiketi, <feature> özniteliğinde özelliklerin/varyantların virgülle ayrılmış listesini belirterek birden çok özelliğe/değişkene name/variant başvurabilir.

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

Not

Belirtilirse variant , yalnızca bir özellik belirtilmelidir.

Özellik etiketinin işlenmesi için listelenen tüm özelliklerin varsayılan olarak etkinleştirilmesi gerekir. Bu davranış, aşağıdaki örnekte görüldüğü gibi özniteliği eklenerek requirement geçersiz kılınabilir.

Not

Bir requirement And değeri hatayla variant birlikte kullanılırsa, birden çok değişken hiçbir zaman atanamayacağından oluşturulur.

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

Etiketin <feature> çalışması için bir etiket yardımcısı gerekir. Bu, özellik yönetimi etiketi yardımcısını ViewImports.cshtml dosyasına ekleyerek yapılabilir.

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC Filtreleri

MVC eylem filtreleri, bir özelliğin durumuna göre koşullu olarak yürütülecek şekilde ayarlanabilir. Bu, MVC filtrelerini özellik farkında bir şekilde kaydederek yapılır. Özellik yönetimi işlem hattı, uygulayan IAsyncActionFilterzaman uyumsuz MVC Eylem filtrelerini destekler.

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

Yukarıdaki kod adlı SomeMvcFilterbir MVC filtresi ekler. Bu filtre yalnızca "FeatureX" etkinse MVC işlem hattı içinde tetikleniyor.

Razor Pages

MVC Razor sayfaları, yürütmek için belirli bir özelliğin veya herhangi bir özellik listesinden birinin etkinleştirilmesini gerektirebilir. Bu, ad alanında Microsoft.FeatureManagement.Mvc bulunabilen bir FeatureGateAttributekullanılarak yapılabilir.

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

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

Razor sayfalarında kullanıldığında, FeatureGateAttribute sayfa işleyici türüne yerleştirilmelidir. Tek tek işleyici yöntemlerine yerleştirilemiyor.

Uygulama oluşturma

Özellik yönetimi kitaplığı, özellik durumuna göre koşullu olarak yürütülen uygulama dalları ve ara yazılım eklemek için kullanılabilir.

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

Yukarıdaki çağrıyla, uygulama yalnızca "FeatureX" özelliği etkinse 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/devre dışı bırakılırsa ara yazılım işlem hattı dinamik olarak değiştirilebilir.

Bu, bir özelliği temel alarak 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. Özellik filtresi uygulamak için arabiriminin IFeatureFilter uygulanması 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. döndürürse EvaluateAsync true, özelliğin etkinleştirilmesi gerektiği anlamına gelir.

Aşağıdaki kod parçacığında özelleştirilmiş özellik filtresinin MyCriteriaFilternasıl ekleneceği gösterilmektedir.

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

Özellik filtreleri, öğesinden AddFeatureManagementdöndürülen üzerinde çağrılarak AddFeatureFilter<T> IFeatureManagementBuilder kaydedilir. Bu özellik filtreleri, özellik bayrakları eklemek için kullanılan hizmet koleksiyonu içinde bulunan hizmetlere erişebilir. Bağımlılık ekleme, bu hizmetleri almak için kullanılabilir.

Not

Özellik bayrağı ayarlarında filtrelere başvurulduğunda (örneğin, appsettings.json), tür adının Filtre bölümü atlanmalıdır. Daha fazla bilgi için bölümüne bakın Filter Alias Attribute .

Parametreli Özellik Filtreleri

Bazı özellik filtreleri, bir özelliğin açılıp açılmayacağı konusunda karar vermek için parametreler gerektirir. Örneğin, bir tarayıcı özellik filtresi belirli bir tarayıcı kümesi için bir özelliği açabilir. Edge ve Chrome tarayıcılarının bir özelliği etkinleştirmesi istenebilir ancak Firefox etkinleştirmez. Bunu yapmak için, bir özellik filtresi parametreleri beklenecek şekilde tasarlanabilir. Bu parametreler özellik yapılandırmasında belirtilecek ve kodda parametresi IFeatureFilter.EvaluateAsyncaracılığıyla FeatureFilterEvaluationContext erişilebilir olacaktır.

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 adlı Parametersbir özelliğe sahiptir. Bu parametreler özellik filtresinin özelliğin etkinleştirilip etkinleştirilmeyeceğine karar vermek için kullanabileceği ham yapılandırmayı temsil eder. Tarayıcı özellik filtresini bir kez daha örnek olarak kullanmak için, filtre özelliği için belirtilecek bir dizi izin verilen tarayıcıyı ayıklamak ve ardından isteğin bu tarayıcılardan birinden gönderilip gönderilmediğini denetlemek için kullanabilir Parameters .

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

Filtre Diğer Adı Özniteliği

Özellik bayrağı için bir özellik filtresi kaydedildiğinde, yapılandırmada kullanılan diğer ad, varsa Filtre soneki kaldırılmış özellik filtre türünün adıdır. Örneğin, MyCriteriaFilter yapılandırmada MyCriteria olarak adlandırılır.

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

Bu, kullanılarak FilterAliasAttributegeçersiz kılınabilir. Bir özellik filtresi, bir özellik bayrağı içinde bu özellik filtresine başvurmak üzere yapılandırmada kullanılması gereken adı bildirmek için bu öznitelikle donatılabilir.

Eksik Özellik Filtreleri

Bir özellik belirli bir özellik filtresi için etkinleştirilecek şekilde yapılandırılmışsa ve bu özellik filtresi kayıtlı değilse, özellik değerlendirildiğinde bir özel durum oluşur. Özel durum, özellik yönetimi seçenekleri kullanılarak devre dışı bırakılabilir.

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, HTTP Bağlamı incelenerek gerçekleştirilir. Özellik filtresi, bağımlılık ekleme yoluyla bir alarak HTTP Bağlamı'na başvuru IHttpContextAccessor alabilir.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

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

öğesinin IHttpContextAccessor kullanılabilir olması için başlangıçta bağımlılık ekleme kapsayıcısına eklenmesi gerekir. aşağıdaki yöntem kullanılarak içinde IServiceCollection kaydedilebilir.

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

Gelişmiş: IHttpContextAccessor/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ı için özellik AddScopedFeatureManagement yönetim hizmetlerini kaydetmek için kullanılmalıdır. Daha fazla bilgi için bölümüne bakın Scoped Feature Management Services .

Özellik Değerlendirmesi için Bağlam Sağlama

Konsol uygulamalarında, özellik filtrelerinin bir özelliğin açık veya kapalı olması gerekip gerekmediğini denetlemek için alıp kullanabildiği gibi HttpContext bir ortam bağlamı yoktur. Bu durumda, uygulamaların özellik filtreleri tarafından kullanılmak üzere özellik yönetim sisteminde bağlamı temsil eden bir nesne sağlaması gerekir. Bu işlem kullanılarak IFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext)yapılır. Özellik yöneticisine sağlanan appContext nesnesi, bir özelliğin durumunu değerlendirmek için özellik filtreleri tarafından kullanılabilir.

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 IFeatureManager.IsEnabledAsync<TContext> geçirilen bağlamdan yararlanabilir. içindeki TContext IContextualFeatureFilter<TContext> type parametresi, filtrenin işleyebilen bağlam türünü açıklar. Bu, bağlamsal özellik filtresi geliştiricisinin bunu kullanmak isteyenler için nelerin gerekli olduğunu tanımlamasını sağlar. Her tür nesnenin alt öğesi olduğundan, sağlanan herhangi bir bağlam için uygulayan IContextualFeatureFilter<object> bir filtre çağrılabilir. Daha belirli bir bağlamsal özellik filtresi örneğini göstermek için, bir hesap etkinleştirilmiş hesaplar listesindeyse etkinleştirilmiş bir özelliği göz önünde bulundurun.

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

bir özelliğin AccountIdFilter durumunu değerlendirebilmek için , uygulanan IAccountContext bir nesnenin sağlanmasını gerektirdiğini görebiliriz. Bu özellik filtresini kullanırken, çağıranın geçirilen nesnenin uyguladığından IAccountContextemin 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 ArgumentExceptionile sonuçlanmaya çalışılıyor.

Aynı Diğer Adla Bağlamsal ve Bağlamsal Olmayan Filtreleri Kullanma

IFeatureFilter ve IContextualFeatureFilter filtreleri aynı diğer adı paylaşabilir. Özellikle, için en fazla bir geçerli filtre olduğu sürece, 0 veya 1 IFeatureFilter ve 0 veya N IContextualFeatureFilter<ContextType>ile paylaşılan bir filtre ContextTypediğer adınız olabilir.

Aşağıdaki bölümde, bir uygulamada aynı ada sahip bağlamsal ve bağlamsal olmayan filtreler kaydedildiğinde filtre seçme işlemi açıklanmaktadır.

Adlı FilterA bağlamsal olmayan bir filtreniz ve sırasıyla ve bağlamlarını kabul TypeB eden iki bağlamsal filtreniz FilterB ve TypeC FilterC'niz olduğunu varsayalım. Üç filtre de aynı diğer adı SharedFilterNamepaylaşır.

Ayrıca, yapılandırmasında özellik filtresini SharedFilterName kullanan bir özellik bayrağınız MyFeature da vardır.

Üç filtrenin tümü de kayıtlıysa:

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

Yerleşik Özellik Filtreleri

Paketiyle birlikte Microsoft.FeatureManagement gelen birkaç özellik filtresi vardır: PercentageFilter, TimeWindowFilterve ContextualTargetingFilter TargetingFilter. Özellik yönetimi yöntemiyle TargetingFilterkaydedildiğindeAddFeatureManagement, dışında tüm filtreler otomatik olarak eklenir. TargetingFilter aşağıdaki bölümde ayrıntılı olarak belirtilen Targeting yöntemiyle WithTargeting eklenir.

Yerleşik özellik filtrelerinin her birinin kendi parametreleri vardır. Örneklerle birlikte özellik filtrelerinin listesi aşağıda verilmiştir.

Microsoft.Percentage

Bu filtre, belirli bir yüzdeye göre bir özelliği etkinleştirme özelliği sağlar.

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

Microsoft.TimeWindow

Bu filtre, bir özelliği bir zaman penceresine göre etkinleştirme özelliği sağlar. Yalnızca End belirtilirse, özellik o zamana kadar açık olarak kabul edilir. Yalnızca Start belirtilirse, özellik bu sürenin ardından tüm noktalarda açık olarak kabul edilir.

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

Zaman penceresi düzenli aralıklarla yinelenecek şekilde yapılandırılabilir. Bu, bir günün düşük veya yüksek trafikli bir döneminde veya haftanın belirli günlerinde bir özelliği açması gerekebilecek senaryolar için yararlı olabilir. Tek tek zaman penceresini yinelenen zaman pencerelerine genişletmek için yinelenme kuralı parametresinde Recurrence belirtilmelidir.

Not

Start ve End etkinleştirmek Recurrenceiçin her ikisi de belirtilmelidir.

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

Ayarlar Recurrence iki bölümden oluşur: Pattern (zaman penceresinin yineleme sıklığı) ve Range (yineleme düzeninin ne kadar süreyle yinelenme süresi için).

Yineleme Deseni

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

Türüne bağlı olarak, bazı alanları Pattern gereklidir, isteğe bağlıdır veya yoksayılır.

  • Daily

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

    Özellik İlgi Açıklama
    Tür Zorunlu olarak ayarlanmalıdır Daily.
    Aralık İsteğe bağlı Her oluşum arasındaki gün sayısını belirtir. Varsayılan değer 1'dir.
  • Weekly

    Haftalık yinelenme düzeni, her yineleme kümesi arasındaki hafta sayısına bağlı olarak zaman penceresinin haftanın aynı günü veya günlerinde yinelenmesine neden olur.

    Özellik İlgi Açıklama
    Tür Zorunlu olarak ayarlanmalıdır Weekly.
    DaysOfWeek Zorunlu Olayın haftanın hangi günlerinde gerçekleştiğini belirtir.
    Aralık İsteğe bağlı Her yineleme kümesi arasındaki hafta sayısını belirtir. Varsayılan değer 1'dir.
    FirstDayOfWeek İsteğe bağlı Hangi günün haftanın ilk günü olarak kabul edileceğini belirtir. Varsayılan değer Sunday olarak belirlenmiştir.

    Aşağıdaki örnek, zaman penceresini her pazartesi ve salı günü yineler

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

Not

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, her gün 25 saatlik bir zaman aralığı yinelemesi geçersizdir.

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
    Tür Zorunlu 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
    Tür Zorunlu olarak ayarlanmalıdır EndDate.
    EndDate Zorunlu Desenin uygulanmasının durdurulacağı tarih saatini belirtir. Son oluşumun başlangıç saati bitiş tarihinden önce olduğu sürece, bu oluşumun bitiş saatinin bunun ötesine geçmesine izin verilir.

    Aşağıdaki örnek, son oluşum 1 Nisan 2024'te gerçekleşene kadar zaman penceresini her gün yineleyecektir.

    "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

    Aralık, Numbered zaman penceresinin sabit sayıda gerçekleşmesine neden olur (desene göre).

    Özellik İlgi Açıklama
    Tür Zorunlu olarak ayarlanmalıdır Numbered.
    NumberOfOccurrences Zorunlu Oluşum sayısını belirtir.

    Aşağıdaki örnek, pazartesi ve salı günleri saat penceresini, sırasıyla 1 Nisan (Mon), 2 Nisan (Sal) ve 8 Nisan (Mon) tarihlerinde gerçekleşen üç oluşum olana kadar yineleyecektir.

    "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 Rangede Pattern 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

Bu filtre, bir özelliği hedef kitle için etkinleştirme özelliği sağlar. Hedeflemenin ayrıntılı açıklaması aşağıdaki hedefleme bölümünde açıklanmıştır. Filtre parametreleri, kullanıcıları, grupları, dışlanan kullanıcıları/grupları tanımlayan bir nesneyi ve özelliğe erişimi olması gereken kullanıcı tabanının varsayılan yüzdesini içerir Audience . Bölümünde listelenen Groups her grup nesnesi, grup üyelerinin yüzde kaçının erişimi olması gerektiğini de belirtmelidir. Doğrudan veya kullanıcı dışlanan bir grupta yer alırsa, bölümde bir kullanıcı belirtilirse Exclusion özellik devre dışı bırakılır. Aksi takdirde, bir kullanıcı doğrudan bölümde belirtilirse Users veya kullanıcı grup dağıtımlarından herhangi birinin dahil edilen yüzdesindeyse veya kullanıcı varsayılan dağıtım yüzdesine düşerse, bu kullanıcı özelliği etkinleştirmiş olur.

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

Özellik Filtresi Diğer Ad Alanları

Yerleşik özellik filtresi diğer adlarının tümü özellik filtresi ad alanındadır Microsoft . Bu, aynı diğer adı paylaşabilecek diğer özellik filtreleri ile çakışmaları önlemektir. Özellik filtresi ad alanının kesimleri '.' karakterine göre bölünür. Bir özellik filtresine, gibi Microsoft.Percentage tam diğer adıyla veya durumunda Microsoft.Percentage Percentageolan son kesim tarafından başvurulabilir.

Hedefleme

Hedefleme, geliştiricilerin yeni özellikleri kullanıcı tabanına aşamalı olarak dağıtmasını sağlayan 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/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 yeni bir 'Beta' özelliği için aşamalı dağıtım örneği gösterilmektedir:

  1. Bireysel kullanıcılar Jeff ve Alicia'ya Beta erişimi verilir
  2. Başka bir kullanıcı, Mark, kabul etmek ister ve dahil edilir.
  3. "Ring1" olarak bilinen bir grubun yüzde yirmisi Beta'ya dahil edilir.
  4. Betaya 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 betaya dahil edilir.
  6. Dağıtım yüzdesi yüzde 100'e kadar artırılır ve özellik tamamen kullanıma sunulmaktadır.

Bir özelliği dağıtmaya yönelik bu strateji, dahil edilen Microsoft.Targeting özellik filtresi aracılığıyla kitaplıkta yerleşik olarak bulunur.

Web Uygulamasında Hedefleme

Hedefleme özelliği filtresini kullanan örnek bir web uygulaması, FeatureFlagDemo örnek projesinde kullanılabilir.

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

Microsoft.FeatureManagement.AspNetCore, bir isteğin ITargetingContextAccessor HttpContexthedef bilgilerini ayıklayacak varsayılan uygulamasını sağlar. üzerinde genel WithTargeting olmayan aşırı yüklemeyi kullanarak hedeflemeyi ayarlarken varsayılan hedefleme bağlamı erişimcisini IFeatureManagementBuilderkullanabilirsiniz.

Varsayılan hedefleme bağlamı erişimcisi ve TargetingFilter üzerinde IFeatureManagementBuilderçağrılarak WithTargeting kaydedilir.

services.AddFeatureManagement()
        .WithTargeting();

ayrıca ve TargetingFilter çağrısı WithTargeting<T>yaparak ve için ITargetingContextAccessor özelleştirilmiş bir uygulama kaydedebilirsiniz. Aşağıda, adlı bir uygulamasıyla kullanmak TargetingFilter üzere bir web uygulamasında özellik yönetimini ayarlamaya yönelik bir örnek verilmiştır ITargetingContextAccessor ExampleTargetingContextAccessor.

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

ITargetingContextAccessor

uygulamasını bir web uygulamasında kullanmak TargetingFilter için uygulaması ITargetingContextAccessor gerekir. Bunun nedeni, bir hedefleme değerlendirmesi gerçekleştirilirken, şu anda değerlendirilmekte olan kullanıcı gibi bağlamsal bilgilerin gerekli olmasıdır. Bu bilgiler olarak TargetingContextbilinir. Farklı uygulamalar bu bilgileri farklı yerlerden ayıklayabilir. Bir uygulamanın hedefleme bağlamını çekebileceği bazı yaygın örnekler, isteğin HTTP bağlamı veya veritabanıdır.

Uygulamanın HTTP bağlamından hedefleme bağlamı bilgilerini ayıklayan bir örnek, paket tarafından Microsoft.FeatureManagement.AspNetCore sağlanan örnektirDefaultHttpTargetingContextAccessor. hedef bilgilerini adresinden HttpContext.Userayıklar. UserId bilgi alanından Identity.Name ayıklanır ve Groups bilgi türündeki Roletaleplerden ayıklanır. Bu uygulama, burada ele alınan kullanımına IHttpContextAccessordayanır.

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ı, şu anda değerlendirilmekte olan kullanıcı ve kullanıcıyı hangi gruplara ayırıyor gibi bilgileri içerir. Konsol uygulamalarında genellikle bu bilgileri hedefleme filtresine akışla aktarmak için kullanılabilir ortam bağlamı yoktur, bu nedenle çağrıldığında FeatureManager.IsEnabledAsync doğrudan geçirilmesi gerekir. Bu, kullanılarak ContextualTargetingFilterdesteklenir. Hedefleme bağlamını özellik yöneticisine kaydırması gereken uygulamalar, TargetingFilter.

bir ContextualTargetingFilter olduğundan, bir ITargetingContext özelliği değerlendirebilmesi ve açabilmesi için uygulamasına geçirilmelidir IFeatureManager.IsEnabledAsync IContextualTargetingFilter<ITargetingContext>.

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

await fm.IsEnabledAsync(featureName, targetingContext);

yine ContextualTargetingFilter microsoft.targeting özellik filtresi diğer adını kullanır, bu nedenle bu filtrenin yapılandırması bu bölümde belirtilenlerle tutarlıdır.

bir konsol uygulamasında kullanan ContextualTargetingFilter bir örnek, TargetingConsoleApp örnek projesinde kullanılabilir.

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önetimi ayarlanırken bu seçenekler yapılandırılabilir.

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

Hedefleme Dışlaması

Hedef Kitle tanımlarken, kullanıcılar ve gruplar hedef kitlenin dışında tutulabilir. Bu, bir özellik bir kullanıcı grubuna dağıtılırken yararlıdır, ancak birkaç kullanıcı veya grubun piyasaya sürülmesinin dışında tutulması gerekir. Dışlama, hedef kitlenin özelliğine Exclusion bir kullanıcı ve grup listesi eklenerek tanımlanır.

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

Yukarıdaki örnekte, özellik ve Aliciaadlı Jeff kullanıcılar için etkinleştirilmiştir. Ayrıca adlı Ring0gruptaki kullanıcılar için de etkinleştirilir. Ancak, kullanıcı olarak adlandırılırsa Mark, grupta Ring0 olup olmadığına bakılmaksızın özellik devre dışı bırakılır. Dışlamalar, hedefleme filtresinin geri kalanından önceliklidir.

Varyantlar

Bir uygulamaya yeni özellikler eklendiğinde, bir özelliğin birden çok farklı tasarım seçeneğinin olduğu bir zaman gelebilir. Tasarıma karar vermek için yaygın bir çözüm, kullanıcı tabanının farklı segmentlerine özelliğin farklı bir sürümünü sağlamayı ve kullanıcı etkileşimini temel alan bir sürüm seçmeyi içeren bir tür A/B testidir. Bu kitaplıkta bu işlev, bir özelliğin farklı yapılandırmalarını çeşitlemelerle temsil ederek etkinleştirilir.

Çeşitlemeler, özellik bayrağının basit bir açık/kapalı bayrağından daha fazlasına dönüşebilmesini sağlar. 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. Bu, Varyant Ayırma bölümünde daha ayrıntılı olarak ele alınmıştır.

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, 'nin GetVariantAsync yöntemi kullanılarak IVariantFeatureManagerbir değişken alınabilir.

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

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration

Bir değişken alındıktan sonra, bir değişkenin yapılandırması doğrudan varyantın Configuration özelliğinden bir IConfigurationSection olarak kullanılabilir. Bir diğer seçenek de kullanarak yapılandırmayı bir nesneye bağlamaktır. NET'in yapılandırma bağlama düzeni.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

Döndürülen değişken, şu anda değerlendirilmekte olan kullanıcıya bağlıdır ve bu bilgiler bir örneğinden TargetingContextalınır. Bu bağlam çağrılırken GetVariantAsync geçirilebilir veya kayıtlıysa uygulamasından ITargetingContextAccessor otomatik olarak alınabilir.

Değişken Özellik Bayrağı Bildirimi

Değişken özellik bayrakları, normal özellik bayraklarıyla karşılaştırıldığında iki ek özelliğe sahiptir: variants ve allocation. variants özelliği, bu ö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. Normal özellik bayraklarını bildirme gibi, bir json dosyasında da değişken özellik bayrakları ayarlayabilirsiniz. Burada bir değişken özellik bayrağı örneği verilmiştir.

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

ÇeşitlemeLer 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ırma özelliği kullanılarak configuration_value ayarlanabilir. configuration_value dize, sayı, boole veya yapılandırma nesnesi olabilecek bir satır içi yapılandırmadır. Belirtilmezse configuration_value , döndürülen değişkenin Configuration özelliği null olur.

Özelliğin altındaki her özellik için tüm olası değişkenlerin variants listesi tanımlanır.

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

Çeşitlemeler Ayırma

Bir özelliğin değişkenlerini ayırma işlemi, özelliğin allocation özelliği tarafından belirlenir.

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

Bir allocation özelliğin ayarı aşağıdaki özelliklere sahiptir:

Özellik Açıklama
default_when_disabled Özellik devre dışı olarak kabul edilirken bir değişken istendiğinde hangi değişkenin kullanılacağını belirtir.
default_when_enabled Özellik etkin olarak kabul edilirken ve kullanıcıya başka bir değişken atanmadığında bir değişken istendiğinde hangi değişkenin kullanılacağını belirtir.
user Bir değişken ve bu değişkenin atanması gereken kullanıcıların listesini belirtir.
group Bir değişken ve grup listesi belirtir. Kullanıcı gruplardan en az birindeyse değişken atanır.
percentile Kullanıcının hesaplanan yüzdesinin atanacağı değişken için uyması gereken bir değişken ve yüzde aralığı belirtir.
seed Yüzde hesaplamalarının percentile temel aldığı değer. Belirli bir kullanıcı için yüzde hesaplaması, aynı değer kullanılırsa tüm özelliklerde aynı seed olur. Belirtilmezse seed , özellik adına göre varsayılan bir tohum oluşturulur.

Yukarıdaki örnekte, özellik etkinleştirilmemişse özellik yöneticisi geçerli kullanıcıya olarak default_when_disabled işaretlenmiş değişkeni atar. Small Bu durumda bu durum geçerlidir.

Özellik etkinleştirilirse, özellik yöneticisi usergroupbir değişken atamak için , ve percentile ayırmalarını denetler. Bu belirli örnek için, değerlendirilen kullanıcı adlı Marshagrupta Ring1ise veya kullanıcı 0 ile 10. yüzdebirlik arasında kalırsa, belirtilen değişken kullanıcıya atanır. Bu durumda, bunların tümü değişkenini Big döndürür. Bu ayırmalardan hiçbiri eşleşmiyorsa, kullanıcıya değişken (olanSmall) atanırdefault_when_enabled.

Ayırma mantığı Microsoft.Targeting özellik filtresine benzer, ancak hedeflemede bulunan 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ırmaya izin vermek için kaydetmeniz ITargetingContextAccessorgerekir. Bu, yöntemini çağırarak WithTargeting<T> yapılabilir.

Değişkenle Etkin Durumu Geçersiz Kılma

Özellik bayrağının etkin durumunu geçersiz kılmak için varyantları kullanabilirsiniz. Bu, varyantlara özellik bayrağı değerlendirmesini genişletme fırsatı verir. Özellik yöneticisi, varyantları olan bir bayrak üzerinde çağrı IsEnabled yaparken, geçerli kullanıcıya atanan değişkenin sonucu geçersiz kılacak şekilde yapılandırılıp yapılandırılmamış olduğunu denetler. Bu, isteğe bağlı variant özelliği status_overridekullanılarak yapılır. Varsayılan olarak, bu özellik olarak Noneayarlanır. Bu, değişkenin bayrağın etkin veya devre dışı olarak kabul edilip edilmediğini etkilemediği anlamına gelir. ayarı status_override Enabled , seçildiğinde bir bayrağın etkinleştirilmesini geçersiz kılmak için değişkene izin verir. ayarı status_override Disabled tam tersi bir işlev sağlar, bu nedenle değişken seçildiğinde bayrağı devre dışı bırakır. Durumu false olan bir enabled özellik geçersiz kılınamaz.

İkili değişkenli bir özellik bayrağı kullanıyorsanız özelliği status_override çok yararlı olabilir. Uygulamanızda ve FeatureGateAttribute gibi IsEnabledAsync API'leri kullanmaya devam etmenizi sağlarken, yüzdebirlik ayırma ve tohum gibi çeşitlemelerle birlikte gelen yeni özelliklerden yararlanmanızı sağlar.

{
    "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üzdebirlik aralığındaysa On , değişken döndürülür. Aksi takdirde, Off değişken döndürülür ve status_override değerine eşit Disabledolduğundan özellik artık devre dışı olarak kabul edilir.

Bağımlılık Eklemedeki Varyantlar

Değişken özellik bayrakları, farklı kullanıcılar için hizmetin farklı uygulamalarını ortaya çıkarabilmek için bağımlılık ekleme ile birlikte kullanılabilir. Bu, arabirimi kullanılarak IVariantServiceProvider<TService> gerçekleştirilir.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken); 

Yukarıdaki kod parçacığında, IVariantServiceProvider<IAlgorithm> bağımlılık ekleme kapsayıcısından uygulamasını IAlgorithm alır. Seçilen uygulama aşağıdakilere bağlıdır:

  • Hizmetin kaydedilildiği IAlgorithm özellik bayrağı.
  • Bu özellik için ayrılan değişken.

IVariantServiceProvider<T> çağrısı IFeatureManagementBuilder.WithVariantService<T>(string featureName)yapılarak uygulamanın kullanımına sunulur. Aşağıdaki örneğe bakın.

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

Yukarıdaki çağrı hizmet koleksiyonunda kullanılabilir hale getirir IVariantServiceProvider<IAlgorithm> . uygulamaları IAlgorithm gibi services.AddSingleton<IAlgorithm, SomeImplementation>()bir ekleme yöntemi aracılığıyla ayrı olarak eklenmelidir. Bu kullanımların IAlgorithm IVariantServiceProvider uygulanması değişken özellik bayrağına ForecastAlgorithm bağlıdır. IAlgorithm uygulaması hizmet koleksiyonuna eklenmezse, IVariantServiceProvider<IAlgorithm>.GetServiceAsync() null sonuç 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 Diğer Adı Özniteliği

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

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.

Telemetri

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

  • Bayraklarım beklendiği gibi etkin/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?

Bu tür sorular, özellik bayrağı değerlendirme olaylarının emisyonu ve analizi aracılığıyla yanıtlanabilir. Bu kitaplık, özellik bayrağı değerlendirmesi sırasında izleme telemetrisi oluşturmak için API'yi kullanır System.Diagnostics.Activity .

Telemetriyi Etkinleştirme

Varsayılan olarak, özellik bayraklarında telemetri gösterilmez. Belirli bir özellik bayrağı için telemetri yayımlamak için bayrağı , telemetri emisyonu için etkinleştirildiğini BILDIRMESİ GEREKİR .

içinde appsettings.jsontanımlanan özellik bayrakları için bu, özelliği kullanılarak telemetry yapılır.

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

Yukarıdaki uygulamasettings kod parçacığı, telemetri için etkinleştirilmiş adlı MyFeatureFlag bir özellik bayrağı tanımlar. Bu, true olarak ayarlayan enabled nesne tarafından telemetry 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 telemetrinin yayımlanıp yayımlanmayacağını belirtir.
metadata Değerlendirme olaylarına özellik bayrağı hakkında özel meta veriler eklemek için kullanılabilen, sözlük olarak modellenen anahtar-değer çiftleri koleksiyonu.

Özel Telemetri Yayımlama

Özellik yöneticisinin "Microsoft.FeatureManagement" adlı kendi ActivitySource adı vardır. Özellik bayrağı için etkinleştirilirse telemetry , özellik bayrağının değerlendirmesi her başlatıldığında özellik yöneticisi bir Activitybaşlatır. Özellik bayrağı değerlendirmesi tamamlandığında, özellik yöneticisi geçerli etkinliğe bir ActivityEvent adlandırılmış FeatureFlag ekler. Olay, FeatureFlag FeatureEvaluationEvent şemasında tanımlanan alanları izleyerek özellik bayrağı değerlendirmesi hakkındaki bilgileri içeren etiketlere sahip olur.

Not

Özellik bayrağında telemetry.metadata belirtilen tüm anahtar değer çiftleri de etiketlere eklenir.

Özel telemetri yayımlamayı etkinleştirmek için bir ActivityListener oluşturabilir ve etkinlik kaynağını dinleyebilirsiniz Microsoft.FeatureManagement . Özellik yönetimi etkinlik kaynağını dinlemeyi ve bir özellik değerlendirildiğinde geri çağırma eklemeyi gösteren bir örnek aşağıda verilmiştir.

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 Telemetri Yayımcısı

Paket, Microsoft.FeatureManagement.Telemetry.ApplicationInsights Application Insights'a özellik bayrağı değerlendirme verileri gönderen yerleşik bir telemetri yayımcısı sağlar. Bundan yararlanmak için pakete bir başvuru ekleyin ve aşağıda gösterildiği gibi Application Insights telemetri yayımcısını kaydedin.

builder.services
    .AddFeatureManagement()
    .AddApplicationInsightsTelemetryPublisher();

Paket, Microsoft.FeatureManagement.Telemetry.ApplicationInsights tüm olayları TargetingId otomatik olarak etiketleyen bir telemetri başlatıcısı sağlar, böylece olaylar bayrak değerlendirmelerine bağlanabilir. Telemetri başlatıcısını kullanmak için, TargetingTelemetryInitializerbunu uygulamanın hizmet koleksiyonuna ekleyin.

builder.Services.AddSingleton<ITelemetryInitializer, TargetingTelemetryInitializer>();

Not

Beklendiği TargetingHttpContextMiddleware gibi çalıştığından TargetingTelemetryInitializer emin olmak için aşağıda açıklananlar kullanılmalıdır.

Geçerli etkinlikte hedefleme bağlamının kalıcı olmasını sağlamak için kullanabilirsiniz TargetingHttpContextMiddleware.

app.UseMiddleware<TargetingHttpContextMiddleware>();

Kullanım örneği VariantAndTelemetryDemo örneğinde bulunabilir.

Önkoşul

Bu telemetri yayımcısı, Application Insights'ın zaten bir uygulama hizmeti olarak kayıtlı olarak ayarlanmasına bağlıdır. Örneğin, bu işlem burada örnek uygulamada yapılır.

Bu telemetri yayımcısı, Application Insights'ın zaten ayarlanıp bir uygulama hizmeti olarak kaydedilmesine bağlıdır.

Önbelleğe Alma

Özellik durumu sistem tarafından IConfiguration sağlanır. Tüm önbelleğe alma ve dinamik güncelleştirmelerin yapılandırma sağlayıcıları tarafından işlenmesi beklenir. Özellik yöneticisi, bir özellik her etkinleştirildiğinde özelliğin durumunun en son değerini ister IConfiguration .

Anlık Görüntü

bir özelliğin durumunun isteğin ömrü boyunca tutarlı kalmasını gerektiren senaryolar vardır. Standarttan IFeatureManager döndürülen değerler, istek sırasında çekeceği kaynak güncelleştirilirse IConfiguration değişebilir. Bu, kullanılarak IFeatureManagerSnapshotönlenebilir. IFeatureManagerSnapshot ile aynı şekilde IFeatureManageralınabilir. IFeatureManagerSnapshot arabirimini IFeatureManageruygular, ancak istek sırasında bir özelliğin ilk değerlendirilen durumunu önbelleğe alır ve kullanım ömrü boyunca bir özelliğin aynı durumunu döndürür.

Özel Özellik Sağlayıcıları

Özel özellik sağlayıcısının uygulanması, geliştiricilerin veritabanı veya özellik yönetimi hizmeti gibi kaynaklardan özellik bayrakları çekmesine olanak tanır. Varsayılan olarak kullanılan dahil edilen özellik sağlayıcısı, .NET Core'un yapılandırma sisteminden özellik bayraklarını çeker. Bu, özelliklerin appsettings.json bir dosyada veya Azure Uygulaması Yapılandırması gibi yapılandırma sağlayıcılarında tanımlanmasını sağlar. Bu davranış, özellik tanımlarının nereden okunduğuna yönelik tam denetim sağlamak için değiştirilebilir.

Özellik tanımlarının yüklenmesini özelleştirmek için arabiriminin IFeatureDefinitionProvider uygulanması gerekir.

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

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

uygulamasını IFeatureDefinitionProviderkullanmak için, özellik yönetimi eklemeden önce hizmet koleksiyonuna eklenmelidir. Aşağıdaki örnek adlı InMemoryFeatureDefinitionProvideruygulamasını IFeatureDefinitionProvider ekler.

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

Sonraki adımlar

Uygulamalarınızda özellik bayraklarını kullanmayı öğrenmek için aşağıdaki hızlı başlangıçlara geçin.

Özellik filtrelerini kullanmayı öğrenmek için aşağıdaki öğreticilere geçin.