Zarządzanie funkcjami platformy .NET

Biblioteka zarządzania funkcjami obsługuje appsettings.json jako źródło flagi funkcji, ponieważ jest to dostawca systemu .NET Core IConfiguration . Poniżej przedstawiono przykład formatu używanego do konfigurowania flag funkcji w pliku json.

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

Sekcja FeatureManagement dokumentu JSON jest używana przez konwencję do ładowania ustawień flag funkcji. W powyższej sekcji przedstawiono trzy różne funkcje. Funkcje definiują filtry funkcji przy użyciu EnabledFor właściwości . W filtrach funkcji dla FeatureTelementu widzimy wartość AlwaysOn. Ten filtr funkcji jest wbudowany i jeśli zostanie określony, zawsze włączy tę funkcję. Filtr AlwaysOn funkcji nie wymaga żadnej konfiguracji, dlatego ma Name tylko właściwość . FeatureU nie ma filtrów we właściwości i w związku z tym EnabledFor nigdy nie zostanie włączony. Wszystkie funkcje, które opierają się na tej włączonej funkcji, nie będą dostępne tak długo, jak filtry funkcji pozostaną puste. Jednak po dodaniu filtru funkcji, który umożliwia rozpoczęcie pracy funkcji. FeatureV określa filtr funkcji o nazwie TimeWindow. Jest to przykład konfigurowalnego filtru funkcji. W przykładzie widać, że filtr ma Parameters właściwość . Służy do konfigurowania filtru. W takim przypadku konfigurowane są czasy rozpoczęcia i zakończenia dla funkcji, która ma być aktywna.

Szczegółowy schemat FeatureManagement sekcji można znaleźć tutaj.

Zaawansowane: użycie dwukropka ":" jest zabronione w nazwach flag funkcji.

Deklaracja wł./wył.

Poniższy fragment kodu przedstawia alternatywny sposób definiowania funkcji, która może służyć do włączania/wyłączania funkcji.

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

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

Typ wymagania

Właściwość RequirementType flagi funkcji służy do określania, czy filtry powinny być używane Any , czy All logika podczas oceniania stanu funkcji. Jeśli RequirementType nie zostanie określony, wartość domyślna to Any.

• Any oznacza, że tylko jeden filtr musi mieć wartość true, aby funkcja została włączona.
• All oznacza, że każdy filtr musi mieć wartość true, aby funkcja została włączona.

A RequirementType zmiany All przechodzenia. Po pierwsze, jeśli nie ma filtrów, funkcja jest wyłączona. Następnie filtry funkcji są przechodzine do momentu, aż jeden z filtrów zdecyduje, że funkcja powinna zostać wyłączona. Jeśli żaden filtr nie wskazuje, że funkcja powinna być wyłączona, jest uważana za włączoną.

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

W powyższym przykładzie określa wartość RequirementType All, co oznacza, FeatureW że wszystkie jego filtry muszą mieć wartość true, aby funkcja została włączona. W takim przypadku funkcja jest włączona dla 50% użytkowników w określonym przedziale czasu.

Schemat zarządzania funkcjami firmy Microsoft

Biblioteka zarządzania funkcjami obsługuje również użycie Microsoft Feature Management schema funkcji do deklarowania flag funkcji. Ten schemat jest niezależny od języka pochodzenia i jest obsługiwany przez wszystkie biblioteki zarządzania funkcjami firmy Microsoft.

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

Biblioteka zarządzania funkcjami obsługuje appsettings.json jako źródło flagi funkcji, ponieważ jest to dostawca systemu .NET Core IConfiguration . Flagi funkcji są deklarowane przy użyciu elementu Microsoft Feature Management schema. Ten schemat jest niezależny od języka pochodzenia i jest obsługiwany przez wszystkie biblioteki zarządzania funkcjami firmy Microsoft.

Poniżej przedstawiono przykład deklarowania flag funkcji w pliku json.

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

Sekcja feature_management dokumentu JSON jest używana przez konwencję do ładowania ustawień flag funkcji. Obiekty flag funkcji muszą być wymienione w tablicy feature_flags w feature_management sekcji . W powyższej sekcji widzimy, że udostępniliśmy trzy różne funkcje. Flaga funkcji ma id właściwości i enabled . To id nazwa używana do identyfikowania i odwołowania się do flagi funkcji. Właściwość enabled określa stan włączonej flagi funkcji. Funkcja jest wyłączona , jeśli enabled ma wartość false. Jeśli enabled wartość ma wartość true, stan funkcji zależy od conditionswartości . Jeśli nie ma conditions , funkcja jest włączona. Jeśli istnieją conditions i są one spełnione, funkcja jest włączona. Jeśli istnieją conditions i nie są one spełnione, funkcja jest wyłączona. Właściwość conditions deklaruje warunki używane do dynamicznego włączania funkcji. Funkcje definiują filtry funkcji w tablicy client_filters . FeatureV określa filtr funkcji o nazwie Microsoft.TimeWindow. Jest to przykład konfigurowalnego filtru funkcji. W przykładzie widać, że filtr ma Parameters właściwość . Służy do konfigurowania filtru. W takim przypadku konfigurowane są czasy rozpoczęcia i zakończenia dla funkcji, która ma być aktywna.

Zaawansowane: użycie dwukropka ":" jest zabronione w nazwach flag funkcji.

Typ wymagania

Właściwość requirement_type elementu conditions służy do określania, czy filtry powinny być używane Any , czy All logika podczas oceniania stanu funkcji. Jeśli requirement_type nie zostanie określony, wartość domyślna to Any.

• Any oznacza, że tylko jeden filtr musi mieć wartość true, aby funkcja została włączona.
• All oznacza, że każdy filtr musi mieć wartość true, aby funkcja została włączona.

A requirement_type zmiany All przechodzenia. Najpierw, jeśli nie ma filtru, funkcja zostanie wyłączona. Jeśli istnieją filtry, filtry funkcji są przechodzine do momentu, aż jeden z filtrów zdecyduje, że funkcja powinna zostać wyłączona. Jeśli żaden filtr nie wskazuje, że funkcja powinna być wyłączona, zostanie ona uznana za włączoną.

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

W powyższym przykładzie określa wartość requirement_type All, co oznacza, FeatureW że wszystkie jego filtry muszą mieć wartość true, aby funkcja została włączona. W takim przypadku funkcja zostanie włączona dla 50% użytkowników w określonym przedziale czasu.

Schemat zarządzania funkcjami platformy .NET

W poprzednich wersjach podstawowym schematem biblioteki zarządzania funkcjami była .NET feature management schema. Począwszy od wersji 4.0.0, nowe funkcje, w tym warianty i dane telemetryczne, nie będą obsługiwane dla schematu zarządzania funkcjami platformy .NET.

W widokach <feature> MVC tagi mogą służyć do warunkowego renderowania zawartości na podstawie tego, czy funkcja jest włączona, czy nie.

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

Możesz również negować ocenę pomocnika tagów, aby wyświetlić zawartość, gdy funkcja lub zestaw funkcji są wyłączone. negate="true" Ustawienie w poniższym przykładzie powoduje renderowanie zawartości tylko wtedy, gdy FeatureX jest wyłączona.

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

Tag <feature> może odwoływać się do wielu funkcji, określając rozdzielaną przecinkami listę funkcji w atrybucie name .

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

Domyślnie wszystkie wymienione funkcje muszą być włączone, aby tag funkcji był renderowany. To zachowanie można zastąpić, dodając requirement atrybut, jak pokazano w poniższym przykładzie.

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

W widokach <feature> MVC tagi mogą służyć do warunkowego renderowania zawartości na podstawie tego, czy funkcja jest włączona, czy też jest przypisany określony wariant funkcji. Aby uzyskać więcej informacji, zobacz sekcję wariantów .

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

Możesz również negować ocenę pomocnika tagów, aby wyświetlić zawartość, gdy funkcja lub zestaw funkcji są wyłączone. negate="true" Ustawienie w poniższym przykładzie powoduje renderowanie zawartości tylko wtedy, gdy FeatureX jest wyłączona.

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

Tag <feature> może odwoływać się do wielu funkcji/wariantów, określając rozdzielaną przecinkami listę funkcji/wariantów w atrybucie/namevariant.

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

Domyślnie wszystkie wymienione funkcje muszą być włączone, aby tag funkcji był renderowany. To zachowanie można zastąpić, dodając requirement atrybut, jak pokazano w poniższym przykładzie.

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

Przedział czasu można skonfigurować do okresowego powtarzania. Może to być przydatne w scenariuszach, w których może być konieczne włączenie funkcji w okresie niskiego lub dużego ruchu w ciągu dnia lub w określonych dniach tygodnia. Aby rozwinąć poszczególne przedziały czasu do okresów cyklicznych, reguła cyklu powinna być określona w parametrze Recurrence .

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

Ustawienia Recurrence składają się z dwóch części: Pattern (jak często powtarza się przedział czasu) i Range (jak długo powtarza się wzorzec cyklu).

Wzorzec cyklu

Istnieją dwa możliwe typy wzorców cyklu: Daily i Weekly. Na przykład przedział czasu może powtarzać "codziennie", "co trzy dni", "każdy poniedziałek" lub "co drugi piątek".

W zależności od typu niektóre pola Pattern są wymagane, opcjonalne lub ignorowane.

• Daily

  Wzorzec cyklu dziennego powoduje powtarzanie przedziału czasu na podstawie liczby dni między poszczególnymi wystąpieniami.

  Właściwości	Stopień zgodności	opis
  Type	Wymagania	Musi być ustawiona wartość Daily.
  Interwał	Opcjonalnie	Określa liczbę dni między poszczególnymi wystąpieniami. Wartość domyślna to 1.

• Weekly

  Wzorzec cyklu tygodniowego powoduje powtórzenie przedziału czasu w tym samym dniu lub dniach tygodnia na podstawie liczby tygodni między poszczególnymi zestawami wystąpień.

  Właściwości	Stopień zgodności	opis
  Type	Wymagania	Musi być ustawiona wartość Weekly.
  DaysOfWeek	Wymagania	Określa dni tygodnia, w których występuje zdarzenie.
  Interwał	Opcjonalnie	Określa liczbę tygodni między poszczególnymi zestawami wystąpień. Wartość domyślna to 1.
  FirstDayOfWeek	Opcjonalnie	Określa, który dzień jest uważany za pierwszy dzień tygodnia. Wartość domyślna to Sunday.

  Poniższy przykład powtarza przedział czasu co drugi poniedziałek i wtorek

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

Zakres cyklu

Istnieją trzy możliwe typy zakresów cykli: NoEnd, EndDate i Numbered.

• NoEnd

  Zakres NoEnd powoduje, że cykl występuje w nieskończoność.

  Właściwości	Stopień zgodności	opis
  Type	Wymagania	Musi być ustawiona wartość NoEnd.

• EndDate

  Zakres EndDate powoduje, że przedział czasu występuje we wszystkich dniach, które pasują do odpowiedniego wzorca do daty zakończenia.

  Właściwości	Stopień zgodności	opis
  Type	Wymagania	Musi być ustawiona wartość EndDate.
  EndDate	Wymagania	Określa datę zakończenia stosowania wzorca. O ile godzina rozpoczęcia ostatniego wystąpienia spadnie przed datą zakończenia, czas zakończenia tego wystąpienia może wykraczać poza nią.

  Poniższy przykład będzie powtarzał przedział czasu każdego dnia do czasu ostatniego wystąpienia 1 kwietnia 2024 r.

  "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

  Zakres Numbered powoduje, że przedział czasu występuje stałą liczbę razy (na podstawie wzorca).

  Właściwości	Stopień zgodności	opis
  Type	Wymagania	Musi być ustawiona wartość Numbered.
  NumberOfOccurrences	Wymagania	Określa liczbę wystąpień.

  Poniższy przykład powtórzy przedział czasu w poniedziałek i wtorek do trzech wystąpień, które mają miejsce odpowiednio 1 kwietnia (Mon), 2 kwietnia (wt) i 8 kwietnia (Mon).

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

Aby utworzyć regułę cyklu, należy określić wartości i Pattern Range. Dowolny typ wzorca może pracować z dowolnym typem zakresu.

Zaawansowane: przesunięcie strefy czasowej Start właściwości jest stosowane do ustawień cyklu.

Warianty

Po dodaniu nowych funkcji do aplikacji może dojść do czasu, gdy funkcja ma wiele różnych proponowanych opcji projektowania. Typowym rozwiązaniem do podejmowania decyzji o projekcie jest pewna forma testowania A/B, która polega na udostępnieniu innej wersji funkcji różnym segmentom bazy użytkowników i wybraniu wersji na podstawie interakcji użytkownika. W tej bibliotece ta funkcja jest włączona przez reprezentowanie różnych konfiguracji funkcji z wariantami.

Warianty umożliwiają flagę funkcji stać się bardziej niż prostą flagą włączania/wyłączania. Wariant reprezentuje wartość flagi funkcji, która może być ciągiem, liczbą, wartością logiczną, a nawet obiektem konfiguracji. Flaga funkcji, która deklaruje warianty, powinna określać, w jakich okolicznościach należy używać każdego wariantu, co zostało szczegółowo omówione w sekcji Przydzielanie wariantów .

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

Pobieranie wariantów

Dla każdej funkcji można pobrać wariant przy użyciu IVariantFeatureManagermetody "s GetVariantAsync ".

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

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration

Po pobraniu wariantu można użyć konfiguracji wariantu bezpośrednio jako IConfigurationSection właściwości wariantu Configuration . Inną opcją jest powiązanie konfiguracji z obiektem przy użyciu polecenia . Wzorzec powiązania konfiguracji platformy NET.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

Zwrócony wariant jest zależny od aktualnie ocenianego użytkownika, a informacje te są uzyskiwane z wystąpienia klasy TargetingContext. Ten kontekst można przekazać podczas wywoływania GetVariantAsync lub można go automatycznie pobrać z implementacji ITargetingContextAccessor , jeśli jest zarejestrowany.

Deklaracja flagi funkcji wariantu

W porównaniu z flagami funkcji normalnych flagi funkcji wariantu mają dwie dodatkowe właściwości: variants i allocation. Właściwość variants jest tablicą zawierającą warianty zdefiniowane dla tej funkcji. Właściwość allocation definiuje sposób przydzielania tych wariantów dla funkcji. Podobnie jak deklarowanie flag funkcji normalnych, można skonfigurować flagi funkcji wariantu w pliku json. Oto przykład flagi funkcji wariantu.

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

Definiowanie wariantów

Każdy wariant ma dwie właściwości: nazwę i konfigurację. Nazwa jest używana do odwoływania się do określonego wariantu, a konfiguracja jest wartością tego wariantu. Konfigurację można ustawić przy użyciu configuration_value właściwości . configuration_value jest konfiguracją śródliniową, która może być ciągiem, liczbą, wartością logiczną lub obiektem konfiguracji. Jeśli configuration_value nie zostanie określony, zwrócona właściwość wariantu Configuration będzie mieć wartość null.

Lista wszystkich możliwych wariantów jest zdefiniowana dla każdej funkcji w variants ramach właściwości .

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

Przydzielanie wariantów

Proces przydzielania wariantów funkcji zależy od allocation właściwości funkcji.

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

Ustawienie allocation funkcji ma następujące właściwości:

W powyższym przykładzie, jeśli funkcja nie jest włączona, menedżer funkcji przypisze wariant oznaczony jako default_when_disabled do bieżącego użytkownika, który jest Small w tym przypadku.

Jeśli funkcja jest włączona, menedżer funkcji sprawdzi userw tym celu alokacje , groupi percentile w celu przypisania wariantu. W tym konkretnym przykładzie, jeśli oceniany użytkownik ma nazwę Marsha, w grupie o nazwie Ring1lub użytkownik może spaść między 0 a 10. percentylem, określony wariant zostanie przypisany do użytkownika. W takim przypadku wszystkie te elementy zwróciłyby Big wariant. Jeśli żadna z tych alokacji nie jest zgodna default_when_enabled , użytkownik ma przypisany wariant , czyli Small.

Logika alokacji jest podobna do filtru funkcji Microsoft.Targeting, ale istnieją pewne parametry, które znajdują się w określaniu wartości docelowej, które nie znajdują się w alokacji i na odwrót. Wyniki określania wartości docelowej i alokacji nie są powiązane.

Zastępowanie stanu włączonego z wariantem

Można użyć wariantów, aby zastąpić włączony stan flagi funkcji. Daje to wariantom możliwość rozszerzenia oceny flagi funkcji. Jeśli obiekt wywołujący sprawdza, czy flaga zawierająca warianty jest włączona, menedżer funkcji sprawdzi, czy wariant przypisany do bieżącego użytkownika został skonfigurowany w celu zastąpienia wyniku. Odbywa się to przy użyciu opcjonalnej właściwości status_overridewariantu . Domyślnie ta właściwość jest ustawiona na None, co oznacza, że wariant nie ma wpływu na to, czy flaga jest uznawana za włączoną, czy wyłączoną. Ustawienie status_override zezwala na Enabled włączenie wariantu, po wybraniu, przesłonięcia flagi. Ustawienie status_override na Disabled wartość zapewnia przeciwną funkcjonalność, dlatego wyłączenie flagi po wybraniu wariantu. Nie można zastąpić funkcji ze stanem enabled false .

Jeśli używasz flagi funkcji z wariantami binarnymi, status_override właściwość może być bardzo pomocna. Umożliwia to kontynuowanie korzystania z interfejsów API, takich jak IsEnabledAsync i FeatureGateAttribute w aplikacji, a jednocześnie korzystanie z nowych funkcji, które są dostępne z wariantami, takimi jak alokacja percentylu i inicjowanie.

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

W powyższym przykładzie funkcja jest zawsze włączona. Jeśli bieżący użytkownik znajduje się w obliczonym zakresie percentylu od 10 do 20, On zwracany jest wariant. Off W przeciwnym razie zwracany jest wariant i ponieważ status_override jest równy Disabled, funkcja zostanie teraz uznana za wyłączoną.

Warianty iniekcji zależności

Flagi funkcji wariantu mogą być używane w połączeniu z iniekcją zależności, aby wyświetlić różne implementacje usługi dla różnych użytkowników. Jest to realizowane przy użyciu interfejsu IVariantServiceProvider<TService> .

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken); 

W powyższym IVariantServiceProvider<IAlgorithm> fragmencie kodu pobiera implementację IAlgorithm z kontenera wstrzykiwania zależności. Wybrana implementacja jest zależna od:

• Flaga funkcji zarejestrowana w IAlgorithm usłudze.
• Przydzielony wariant dla tej funkcji.

Element IVariantServiceProvider<T> jest udostępniany aplikacji przez wywołanie metody IFeatureManagementBuilder.WithVariantService<T>(string featureName). Zobacz przykład poniżej.

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

Powyższe wywołanie udostępnia IVariantServiceProvider<IAlgorithm> w kolekcji usług. Implementacje IAlgorithm programu muszą być dodawane oddzielnie za pomocą metody add, takiej jak services.AddSingleton<IAlgorithm, SomeImplementation>(). Implementacja IAlgorithm tej IVariantServiceProvider funkcji zależy od flagi funkcji wariantu ForecastAlgorithm . Jeśli do kolekcji usług nie zostanie dodana żadna IAlgorithm implementacja, IVariantServiceProvider<IAlgorithm>.GetServiceAsync() funkcja zwraca zadanie z wynikiem null .

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

Atrybut aliasu usługi wariantu

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

Dostawca usług wariantu będzie używać nazw typów implementacji do dopasowania przydzielonego wariantu. Jeśli usługa wariantu jest ozdobiona wartością , nazwa zadeklarowana w tym atrybucie VariantServiceAliasAttributepowinna być używana w konfiguracji do odwołowania się do tej usługi wariantu.

Telemetria

Po wdrożeniu zmiany flagi funkcji często ważne jest analizowanie jej wpływu na aplikację. Oto na przykład kilka pytań, które mogą wystąpić:

• Czy moje flagi są włączone/wyłączone zgodnie z oczekiwaniami?
• Czy docelowi użytkownicy uzyskują dostęp do określonej funkcji zgodnie z oczekiwaniami?
• Który wariant jest widoczny dla określonego użytkownika?

Odpowiedzi na te typy pytań można uzyskać za pośrednictwem emisji i analizy zdarzeń oceny flag funkcji. Ta biblioteka używa interfejsu System.Diagnostics.Activity API do tworzenia danych telemetrycznych śledzenia podczas oceny flagi funkcji.

Włączanie telemetrii

Domyślnie flagi funkcji nie mają emitowanych danych telemetrycznych. Aby opublikować dane telemetryczne dla danej flagi funkcji, flaga MUSI zadeklarować , że jest włączona dla emisji telemetrii.

W przypadku flag funkcji zdefiniowanych w appsettings.jsonprogramie jest to wykonywane przy użyciu telemetry właściwości .

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

Powyższy fragment kodu appsettings definiuje flagę funkcji o nazwie MyFeatureFlag , która jest włączona dla telemetrii. Jest to wskazywane przez telemetry obiekt, który ustawia wartość enabled true. Wartość enabled właściwości musi być true publikowania danych telemetrycznych dla flagi.

Sekcja telemetry flagi funkcji ma następujące właściwości:

Publikowanie niestandardowych danych telemetrycznych

Menedżer funkcji ma własną ActivitySource nazwę "Microsoft.FeatureManagement". Jeśli telemetry flaga funkcji jest włączona, za każdym razem, gdy zostanie uruchomiona ocena flagi funkcji, menedżer funkcji uruchomi element Activity. Po zakończeniu oceny flagi funkcji menedżer funkcji doda ActivityEvent nazwę "FeatureFlag" do bieżącego działania. Zdarzenie "FeatureFlag" będzie zawierać tagi zawierające informacje o ocenie flagi funkcji. W szczególności tagi będą zawierać następujące pola:

Aby włączyć publikowanie niestandardowych danych telemetrycznych, możesz utworzyć ActivityListener źródło działań i nasłuchiwać go Microsoft.FeatureManagement . Oto przykład pokazujący, jak nasłuchiwać źródła działań zarządzania funkcjami i dodawać wywołanie zwrotne po ocenie funkcji.

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

Aby uzyskać więcej informacji, zobacz Zbieranie rozproszonego śledzenia.

Wydawca telemetrii usługi Application Insights

Pakiet Microsoft.FeatureManagement.Telemetry.ApplicationInsights udostępnia wbudowanego wydawcę telemetrii, który wysyła dane oceny flag funkcji do usługi Application Insights. Aby skorzystać z tego celu, dodaj odwołanie do pakietu i zarejestruj wydawcę telemetrii usługi Application Insights, jak pokazano poniżej.

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

Pakiet Microsoft.FeatureManagement.Telemetry.ApplicationInsights udostępnia inicjator telemetrii, który automatycznie taguje wszystkie zdarzenia za pomocą TargetingId polecenia , aby zdarzenia mogły być połączone z ocenami flag. Aby użyć inicjatora telemetrii, TargetingTelemetryInitializerdodaj go do kolekcji usług aplikacji.

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

Aby włączyć trwałość kontekstu określania wartości docelowej w bieżącym działaniu, możesz użyć elementu TargetingHttpContextMiddleware.

app.UseMiddleware<TargetingHttpContextMiddleware>();

Przykład użycia można znaleźć w przykładzie EvaluationDataToApplicationInsights .

Warunek wstępny

Ten wydawca danych telemetrycznych zależy od tego, czy usługa Application Insights jest już skonfigurowana i zarejestrowana jako usługa aplikacji. Można to zrobić na przykład w przykładowej aplikacji.