.NET 機能管理

機能管理ライブラリは、.NET Core の IConfiguration システムのプロバイダーであるため、機能フラグ ソースとして appsettings.json をサポートしています。 以下は、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"
                    }
                }
            ]
        }
    }
}

JSON ドキュメントの FeatureManagement セクションが機能フラグ設定を読み込むための慣例によって使用されます。 上記のセクションでは、3 つの異なる機能が見られます。 機能は EnabledFor プロパティを使用して機能フィルターを定義します。 FeatureT 用の機能フィルターには、AlwaysOn があります。 この機能フィルターは組み込みであり、指定されると常にその機能が有効になります。 AlwaysOn 機能フィルターでは構成が必要ないため、Name プロパティしかありません。 FeatureU はその EnabledFor プロパティにフィルターがないため、有効になることはありません。 この機能が有効であることに依存する機能は、機能フィルターが空のままである限りアクセスできません。 ただし、機能を有効にする機能フィルターが追加されると、すぐに機能を開始します。 FeatureV は、TimeWindow という名前の機能フィルターを指定します。 これは構成可能な機能フィルターの例です。 フィルターに Parameters プロパティがある例で確認できます。 これは、フィルターの構成に使用されます。 この場合、機能がアクティブになる開始時間と終了時間が構成されます。

FeatureManagement セクションの詳細なスキーマはこちらで見つけることができます。

詳細設定: 機能フラグ名でのコロン ':' の使用は禁止されています。

宣言のオン/オフ

次のスニペットは、オン/オフ機能に使用できる機能を定義する別の方法を示しています。

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

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

RequirementType

機能フラグの RequirementType プロパティは、フィルターが機能の状態を評価する場合に Any または All ロジックを使用する必要があるかどうかを決定するために使用されます。 RequirementType を指定しない場合の既定値は Any です。

• Any は、1 つのフィルターだけが true と評価されると、その機能が有効になることを意味します。
• All は、機能を有効にするために、すべてのフィルターが true と評価される必要があることを意味します。

All の RequirementType は走査を変更します。 まず、フィルターがない場合、この機能は無効になります。 次に、フィルターのいずれかがその機能を無効にする必要があると判断するまで、機能フィルターが走査されます。 どのフィルターも機能を無効にすることを示していない場合は、有効とみなされます。

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

上記の例では、FeatureW は All の RequirementType を指定します。つまり、その機能を有効にするには、すべてのフィルターが true と評価される必要があります。 この場合、指定された時間枠に 50% のユーザーに対してこの機能が有効になります。

Microsoft 機能管理スキーマ

機能管理ライブラリは、機能フラグを宣言するための Microsoft Feature Management schema の使用もサポートしています。 このスキーマは言語を選ばず、すべての 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"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

機能管理ライブラリは、.NET Core の IConfiguration システムのプロバイダーであるため、機能フラグ ソースとして appsettings.json をサポートしています。 機能フラグは Microsoft Feature Management schema を使用して宣言されます。 このスキーマは言語を選ばず、すべての Microsoft 機能管理ライブラリでサポートされています。

以下は、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"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

JSON ドキュメントの feature_management セクションが機能フラグ設定を読み込むための慣例によって使用されます。 機能フラグ オブジェクトは、feature_management セクションの feature_flags 配列に一覧表示されている必要があります。 上記のセクションでは、3 つの異なる機能が提供されていることを確認できます。 機能フラグには id および enabled プロパティがあります。 id は、機能フラグを特定および参照するために使用される名前です。 enabled プロパティは、機能フラグの有効な状態を指定します。 enabled が false である場合、機能は [オフ] です。 enabled が true である場合は、機能の状態は conditions に依存します。 conditions がない場合は [オン] になります。 conditions があり、それが満たされている場合は、機能は [オン] です。 conditions があり、それが満たされていない場合は、機能は [オフ] です。 conditions プロパティは、機能を動的に有効にするための条件を宣言します。 機能は client_filters 配列で機能フィルターを定義します。 FeatureV は、Microsoft.TimeWindow という名前の機能フィルターを指定します。 これは構成可能な機能フィルターの例です。 フィルターに Parameters プロパティがある例で確認できます。 これは、フィルターの構成に使用されます。 この場合、機能がアクティブになる開始時間と終了時間が構成されます。

詳細設定: 機能フラグ名でのコロン ':' の使用は禁止されています。

RequirementType

conditions の requirement_type プロパティは、フィルターが機能の状態を評価する場合に Any または All ロジックを使用する必要があるかどうかを決定するために使用されます。 requirement_type を指定しない場合の既定値は Any です。

• Any は、1 つのフィルターだけが true と評価されると、その機能が有効になることを意味します。
• All は、機能を有効にするために、すべてのフィルターが true と評価される必要があることを意味します。

All の requirement_type は走査を変更します。 まず、フィルターがない場合、この機能は無効になります。 次に、フィルターがある場合は、フィルターのいずれかがその機能を無効にする必要があると判断するまで、機能フィルターが走査されます。 どのフィルターも機能を無効にすることを示していない場合は、有効とみなされます。

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

上記の例では、FeatureW は All の requirement_type を指定します。つまり、その機能を有効にするには、すべてのフィルターが true と評価される必要があります。 この場合、指定された時間枠に 50% のユーザーに対してこの機能が有効になります。

.NET 機能管理スキーマ

以前のバージョンでは、機能管理ライブラリのプライマリ スキーマは .NET feature management schema でした。 v4.0.0 以降は、バリアントとテレメトリを含む新しい機能は、.NET 機能管理スキーマではサポートされません。

MVC ビューでは、<feature> タグを使用して、機能フラグが有効か無効かに基づいてコンテンツを条件付きでレンダリングできます。

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

また、ある機能や機能のセットが無効になっている場合に、タグ ヘルパーの評価を無効にしてコンテンツを表示することもできます。 以下の例で negate="true" を設定することで、FeatureX が無効な場合にのみコンテンツがレンダリングされます。

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

<feature> タグは、name 属性でカンマ区切りの機能の一覧を指定することで、複数の機能を参照できます。

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

既定では、機能タグがレンダリングされるには、一覧表示されたすべての機能が有効になっている必要があります。 この動作は、以下の例のように requirement 属性を追加することでオーバーライドできます。

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

MVC ビューでは、<feature> タグを使用して、機能フラグが有効か無効か、または機能の特定のバリアントが割り当てられているかに基づいてコンテンツを条件付きでレンダリングできます。 詳しくは、「バリアント」セクションをご覧ください。

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

また、ある機能や機能のセットが無効になっている場合に、タグ ヘルパーの評価を無効にしてコンテンツを表示することもできます。 以下の例で negate="true" を設定することで、FeatureX が無効な場合にのみコンテンツがレンダリングされます。

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

<feature> タグは、name/variant 属性でカンマ区切りの機能またはバリアントの一覧を指定することで、複数の機能またはバリアントを参照できます。

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

既定では、機能タグがレンダリングされるには、一覧表示されたすべての機能が有効になっている必要があります。 この動作は、以下の例のように requirement 属性を追加することでオーバーライドできます。

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

時間枠は定期的に反復するように構成できます。 これは、トラフィックの少ない時間帯や多い時間帯、あるいは特定の曜日に機能をオンにする必要があるシナリオに役立ちます。 個別の時間枠を反復する時間枠に拡張するには、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"
                    }
                }
            }
        }
    ]
}

Recurrence 設定は、Pattern (時間枠を繰り返す頻度) と Range (繰り返しパターンを繰り返す期間) の 2 つの部分で構成されています。

定期的なパターン

繰り返しパターンには、Daily と Weekly の 2 種類があります。 たとえば、"毎日"、"3 日ごと"、"毎週月曜日"、"毎週金曜日以外" などの時間枠を繰り返すことができます。

種類によって、Pattern の特定のフィールドは必須、任意、または無視されます。

• Daily

  日単位の繰り返しパターンでは、それぞれ発生した日の日数に基づいて時間枠が繰り返されます。

  プロパティ	関連性	説明
  Type	必須	Daily に設定する必要があります。
  間隔	省略可能	それぞれ発生した日の日数で指定します。 既定値は 1 です。

• Weekly

  週単位の繰り返しパターンでは、それぞれ発生した週の週数に基づいて、時間枠が同じ日または曜日に繰り返されます。

  プロパティ	関連性	説明
  Type	必須	Weekly に設定する必要があります。
  DaysOfWeek	必須	イベントが発生する曜日を指定します。
  間隔	省略可能	それぞれ発生した週の週数で指定します。 既定値は 1 です。
  FirstDayOfWeek	省略可能	どの曜日を週の初日とみなすかを指定します。 既定値は Sunday。

  次の例は、隔週の月曜日と火曜日に時間枠を繰り返します。

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

定期実行範囲

使用可能な繰り返しの範囲の種類は、NoEnd、EndDate、Numbered の 3 つがあります。

• NoEnd

  NoEnd の範囲では、繰り返しが無期限に発生します。

  プロパティ	関連性	説明
  Type	必須	NoEnd に設定する必要があります。

• EndDate

  EndDate の範囲は、終了日まで該当するパターンに当てはまるすべての日に発生するように時間枠に影響します。

  プロパティ	関連性	説明
  Type	必須	EndDate に設定する必要があります。
  EndDate	必須	パターンの適用を停止する日付と時刻を指定します。 最後の発生日の開始時刻が終了日より前である限り、その発生日の終了時刻はその時間を超えて延長できます。

  次の例では、2024 年 4 月 1 日に最後に発生するまで、毎日時間枠を繰り返します。

  "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

  Numbered の範囲では、時間枠が (パターンに基づいて) 決まった回数発生します。

  プロパティ	関連性	説明
  Type	必須	Numbered に設定する必要があります。
  NumberOfOccurrences	必須	発生回数を指定します。

  次の例では、月曜日と火曜日に時間枠を繰り返し、4 月 1 日 (月)、4 月 2 日 (火)、4 月 8 日 (月) の 3 回発生します。

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

繰り返し規則を作成するには、Pattern と Range の両方を指定する必要があります。 どのパターンの種類でも、どの範囲の種類でも機能します。

詳細： Start プロパティのタイム ゾーン オフセットが繰り返し設定に適用されます。

バリアント

アプリケーションに新しい機能が追加される場合、その機能に複数の異なる設計オプションがある場合があります。 設計を決定するための一般的な解決策は、一種の A/B テストです。これは、ユーザー ベースの異なるセグメントに機能の異なるバージョンを提供し、ユーザー操作に基づいてバージョンを選択するものです。 このライブラリでは、機能のさまざまな構成をバリアントで表現することで、この機能が有効になります。

バリアントは、機能フラグを単なるオン/オフのフラグ以上のものにします。 バリアントは機能フラグの値を表し、文字列、数値、ブール値、あるいは構成オブジェクトである場合もあります。 バリアントを宣言する機能フラグは、それぞれのバリアントをどのような状況で使用する必要があるかを定義する必要があります。この詳細については、「バリアントの割り当て」セクションで扱っています。

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

バリアントの取得

各機能について、IVariantFeatureManager の 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

バリアントが取得されると、バリアントの設定はバリアントの Configuration プロパティから IConfigurationSection として直接使用できます。 もう 1 つのオプションは、.NET の構成バインド パターンを使用して、構成をオブジェクトにバインドすることです。

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

返されるバリアントは現在評価されているユーザーに依存し、その情報は TargetingContext のインスタンスから得られます。 このコンテキストは GetVariantAsync を呼び出すときに渡すか、ITargetingContextAccessor の実装が登録されている場合はそこから自動的に取得します。

バリアント機能フラグの宣言

通常の機能フラグと比較して、バリアント機能フラグには variants と allocation の 2 つの追加プロパティがあります。 variants プロパティは、この機能に対して定義されたバリアントを含む配列です。 allocation プロパティは、これらのバリアントを機能に割り当てる方法を定義します。 通常の機能フラグを宣言するのと同様に、バリアント機能フラグも json ファイルで設定できます。 こちらにバリアント機能フラグの例を示します。

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

バリアントの定義

各バリアントには名前と構成の 2 つのプロパティがあります。 名前は特定のバリアントを指すのに使われ、構成はそのバリアントの値です。 構成は、configuration_reference または configuration_value プロパティを使用して設定できます。 configuration_reference は、機能フラグの宣言を含む現在の構成のセクションを参照する文字列パスです。 configuration_value は、文字列、数値、論理値、構成オブジェクトのいずれかに設定できるインライン構成です。 両方が指定されている場合は、configuration_valueが使用されます。 どちらも指定されていない場合、返されるバリアントの Configuration プロパティは null になります。

variants プロパティの下で、各機能に対して利用可能なすべてのバリアントのリストが定義されます。

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

    "ShoppingCart": {
        "Big": {
            "Size": 600,
            "Color": "green"
        },
        "Small": {
            "Size": 300,
            "Color": "gray"
        }
    }
}

バリアントの割り当て

機能のバリアントを割り当てるプロセスは、機能の allocation プロパティによって決定されます。

"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_reference": "ShoppingCart:Big" 
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

機能の allocation 設定には次のプロパティがあります。

上記の例では、機能が有効になっていない場合は、機能マネージャーは default_when_disabled とマークされたバリアントを現在のユーザー (この場合は Small) に割り当てます。

この機能が有効になっている場合は、機能マネージャーは user、group、percentile の割り当てを順番に確認してバリアントを割り当てます。 この具体的な例では、評価されるユーザーが Marsha という名前で、Ring1 というグループに属する場合、またはユーザーが偶然 0 パーセンタイルと 10 パーセンタイルの間に存在する場合、指定されたバリアントがユーザーに割り当てられます。 この場合、これらはすべて Big バリアントを返します。 これらの割り当てがどれも一致しない場合、default_when_enabled のバリアントが割り当てられ、Small になります。

割り当てのロジックは Microsoft.Targeting 機能フィルターと似ていますが、パラメーターには、ターゲット設定に存在するが割り当てに存在しないものや、その逆があります。 対象設定と割り当ての結果は関係ありません。

バリアントを使用する有効な状態のオーバーライド

機能フラグの有効な状態をオーバーライドするためにバリアントを使用できます。 これにより、バリアントが機能フラグの評価を拡張する機会が付与されます。 呼び出し元がバリアントを持つフラグが有効かどうかを確認している場合、機能マネージャーは、現在のユーザーに割り当てられているバリアントが結果をオーバーライドするように設定されているかどうかを確認します。 これは省略可能なバリアント プロパティ status_override を使用して行われます。 既定では、このプロパティは None に設定されており、バリアントはフラグが有効か無効であるかに影響しないことを意味します。 status_override を Enabled に設定すると、バリアントが選択されたときにフラグをオーバーライドして有効にすることができます。 status_override を Disabled に設定すると逆の機能が提供され、バリアントが選択されたときにフラグが無効になります。 enabled 状態が false の機能はオーバーライドできません。

バイナリのバリアントで機能フラグを使用する場合、status_override プロパティが非常に役立ちます。 これにより、アプリケーションで IsEnabledAsync や FeatureGateAttribute のような API を使い続けながら、パーセンタイル割り当てやシードなどのバリアントに付属する新しい機能の恩恵を受けることができます。

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

上記の例では、機能が常に有効になっています。 現在のユーザーが計算されたパーセンタイルの 10 から 20 の範囲にある場合、On バリアントが返されます。 それ以外の場合は、Off バリアントが返され、status_override は Disabled と等しいため、その機能は無効とみなされます。

依存関係の挿入のバリアント

バリアント機能フラグは、依存関係の挿入と組み合わせて使用することで、ユーザーごとに異なるサービスの実装を表示できます。 これを行うには、IVariantServiceProvider<TService> インターフェイスを使用します。

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken); 

上記のスニペットでは、IVariantServiceProvider<IAlgorithm> は依存関係の挿入コンテナーから IAlgorithm の実装を取得します。 選択された実装は、以下に依存します。

• IAlgorithm サービスが登録された機能フラグ。
• その機能に割り当てられたバリアント。

IVariantServiceProvider<T> は IFeatureManagementBuilder.WithVariantService<T>(string featureName) を呼び出すことでアプリケーションに利用できるようになります。 例については、以下を参照してください。

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

上記の呼び出しは IVariantServiceProvider<IAlgorithm> をサービス コレクションで利用できるようにします。 IAlgorithm の実装は、services.AddSingleton<IAlgorithm, SomeImplementation>() のような add メソッドを介して個別に追加する必要があります。 IVariantServiceProvider で使用される IAlgorithm の実装は ForecastAlgorithm のバリアント機能フラグに依存します。 IAlgorithm の実装がサービス コレクションに追加されていない場合、IVariantServiceProvider<IAlgorithm>.GetServiceAsync() は null の結果を持つタスクを返します。

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

バリアント サービス Alias 属性

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

バリアント サービス プロバイダーは割り当てられたバリアントに一致する実装の型名を使用します。 バリアント サービスが VariantServiceAliasAttribute で装飾されている場合、この属性で宣言された名前は、このバリアント サービスを参照するために構成で使用する必要があります。

テレメトリ

機能フラグの変更がデプロイされると、多くの場合、アプリケーションへの影響の分析が重要です。 たとえば、可能性のある質問は次のとおりです。

• 私のフラグは期待どおりに有効または無効になっていますか?
• 対象ユーザーは、期待どおりに特定の機能にアクセスできていますか?
• どのバリアントが特定のユーザーに表示されていますか?

この種の質問には、機能フラグ評価イベントの生成と分析を通じて回答できます。 このライブラリでは、System.Diagnostics.Activity API を使用して、機能フラグの評価中にトレース テレメトリを生成します。

テレメトリの有効化

既定では、機能フラグにはテレメトリがありません。 指定された機能フラグに対してテレメトリを発行するには、フラグはテレメトリ生成のために有効であることを宣言する必要があります。

appsettings.json で定義された機能フラグの場合は、telemetry プロパティを使用して行われます。

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

上記の appsettings スニペットでは、テレメトリを有効にする MyFeatureFlag という名前の機能フラグを定義しています。 これは、enabled を true に設定する telemetry オブジェクトによって示されます。 フラグのテレメトリを発行するには、enabled プロパティの値を true にする必要があります。

機能フラグの telemetry セクションには次のプロパティがあります。

カスタム テレメトリの発行

機能マネージャーには、"Microsoft.FeatureManagement" という独自の ActivitySource があります。 機能フラグに対して telemetry が有効な場合、機能フラグの評価が開始されるたびに、機能マネージャーは Activity を開始します。 機能フラグの評価が完了すると、機能マネージャーは "FeatureFlag" という ActivityEvent を現在のアクティビティに追加します。 "FeatureFlag" イベントには、機能フラグの評価に関する情報を含むタグがあります。 具体的には、タグには次のフィールドが含まれます。

カスタム テレメトリの発行を有効にするには、ActivityListener を作成し、Microsoft.FeatureManagement アクティビティ ソースをリッスンします。 次の例は、機能管理アクティビティ ソースをリッスンし、機能の評価時にコールバックを追加する方法を示しています。

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

詳細については、「分散トレースを収集する」を参照してください。

Application Insights のテレメトリ パブリッシャー

Microsoft.FeatureManagement.Telemetry.ApplicationInsights パッケージには、Application Insights に機能フラグ評価データを送信する組み込みのテレメトリ パブリッシャーが用意されています。 これを活用するには、以下に示すようにパッケージに参照を追加し、Application Insights テレメトリ パブリッシャーを登録します。

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

Microsoft.FeatureManagement.Telemetry.ApplicationInsights パッケージには、イベントをフラグ評価にリンクできるように、すべてのイベントに自動的に TargetingId のタグを付けるテレメトリ初期化子が用意されています。 テレメトリ初期化子 TargetingTelemetryInitializer を使用するには、それをアプリケーションのサービス コレクションに追加します。

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

現在のアクティビティでターゲット設定コンテキストの永続化を有効にするには、TargetingHttpContextMiddleware を使用できます。

app.UseMiddleware<TargetingHttpContextMiddleware>();

その使用例は EvaluationDataToApplicationInsights の例にあります。

前提条件

このテレメトリ パブリッシャーは、Application Insights が既に設定され、アプリケーション サービスとして登録されていることに依存します。 たとえば、これはアプリケーションの例のこちらで行われています。