.NET Özellik Yönetimi
.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
- Yerleşik
Ö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ı TimeWindow
bir ö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 All
iç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 schema
bildirilir. 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.TimeWindow
bir ö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 All
iç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 IFeatureManager
gerç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 AddFeatureManagement
alı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 FeatureGateAttribute
kullanı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 IAsyncActionFilter
zaman uyumsuz MVC Eylem filtrelerini destekler.
services.AddMvc(o =>
{
o.Filters.AddForFeature<SomeMvcFilter>("FeatureX");
});
Yukarıdaki kod adlı SomeMvcFilter
bir 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 FeatureGateAttribute
kullanı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ı EvaluateAsync
tek 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 MyCriteriaFilter
nasıl ekleneceği gösterilmektedir.
services.AddFeatureManagement()
.AddFeatureFilter<MyCriteriaFilter>();
Özellik filtreleri, öğesinden AddFeatureManagement
dö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.EvaluateAsync
aracı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ı Parameters
bir ö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 FilterAliasAttribute
geç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 IAccountContext
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
ile 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 ContextType
diğ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ı SharedFilterName
paylaşı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
TypeB
FilterB
kullanılır. Bağlam türü iseTypeC
FilterC
kullanılır. - IsEnabledAsync("MyFeature", context) çağrısı yaptığınızda bağlam türü ise
TypeF
FilterA
kullanılır.
Yerleşik Özellik Filtreleri
Paketiyle birlikte Microsoft.FeatureManagement
gelen birkaç özellik filtresi vardır: PercentageFilter
, TimeWindowFilter
ve ContextualTargetingFilter
TargetingFilter
. Özellik yönetimi yöntemiyle TargetingFilter
kaydedildiğ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 Recurrence
iç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 Range
de 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
Percentage
olan 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:
- Bireysel kullanıcılar Jeff ve Alicia'ya Beta erişimi verilir
- Başka bir kullanıcı, Mark, kabul etmek ister ve dahil edilir.
- "Ring1" olarak bilinen bir grubun yüzde yirmisi Beta'ya dahil edilir.
- Betaya dahil edilen "Ring1" kullanıcılarının sayısı yüzde 100'e kadar artırılır.
- Kullanıcı tabanının yüzde beşi betaya dahil edilir.
- 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
HttpContext
hedef 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 IFeatureManagementBuilder
kullanabilirsiniz.
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 TargetingContext
bilinir. 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.User
ayıklar. UserId
bilgi alanından Identity.Name
ayıklanır ve Groups
bilgi türündeki Role
taleplerden ayıklanır. Bu uygulama, burada ele alınan kullanımına IHttpContextAccessor
dayanı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 ContextualTargetingFilter
desteklenir. 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 Alicia
adlı Jeff
kullanıcılar için etkinleştirilmiştir. Ayrıca adlı Ring0
gruptaki 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 IVariantFeatureManager
bir 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 TargetingContext
alı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 user
group
bir değişken atamak için , ve percentile
ayırmalarını denetler. Bu belirli örnek için, değerlendirilen kullanıcı adlı Marsha
grupta Ring1
ise 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 ITargetingContextAccessor
gerekir. 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_override
kullanılarak yapılır. Varsayılan olarak, bu özellik olarak None
ayarlanı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 Disabled
olduğ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 VariantServiceAliasAttribute
dekore 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.json
tanı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 Activity
baş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, TargetingTelemetryInitializer
bunu 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 IFeatureManager
alınabilir. IFeatureManagerSnapshot
arabirimini IFeatureManager
uygular, 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ı IFeatureDefinitionProvider
kullanmak için, özellik yönetimi eklemeden önce hizmet koleksiyonuna eklenmelidir. Aşağıdaki örnek adlı InMemoryFeatureDefinitionProvider
uygulaması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.