ASP.NET の構成ビルダー

[アーティクル]
07/13/2023

構成ビルダーは、ASP.NET アプリが外部ソースから構成値を取得するための最新かつアジャイルなメカニズムを提供します。

構成ビルダー:

.NET Framework 4.7.1 以降で使用できます。
構成値を読み取るための柔軟なメカニズムを提供します。
コンテナーとクラウドに重点を置いた環境に移行する際に、アプリの基本的なニーズの一部に対処します。
.NET 構成システムで以前に使用できなかったソース (Azure Key Vaultや環境変数など) から描画することで、構成データの保護を強化するために使用できます。

キー/値構成ビルダー

構成ビルダーが処理できる一般的なシナリオは、キー/値パターンに従う構成セクションに基本的なキー/値の置換メカニズムを提供することです。 ConfigurationBuilders の.NET Framework概念は、特定の構成セクションまたはパターンに限定されません。ただし、(github、NuGet) のMicrosoft.Configuration.ConfigurationBuilders構成ビルダーの多くは、キー/値パターン内で動作します。

キー/値構成ビルダーの設定

次の設定は、のすべてのキー/値構成ビルダーに Microsoft.Configuration.ConfigurationBuilders適用されます。

モード

構成ビルダーは、キー/値情報の外部ソースを使用して、構成システムの選択したキー/値要素を設定します。具体的には、 <appSettings/> セクションと <connectionStrings/> セクションは、構成ビルダーから特別な処理を受けます。ビルダーは、次の 3 つのモードで動作します。

Strict - 既定のモード。このモードでは、構成ビルダーは既知のキー/値中心の構成セクションでのみ動作します。 Strict モードでは、セクション内の各キーが列挙されます。外部ソースで一致するキーが見つかった場合:
- 構成ビルダーは、結果の構成セクションの値を外部ソースの値に置き換えます。
Greedy - このモードはモードと密接に Strict 関連しています。元の構成に既に存在するキーに制限されるのではなく、
- 構成ビルダーは、外部ソースのすべてのキーと値のペアを、結果の構成セクションに追加します。
Expand - 構成セクションオブジェクトに解析される前に、生の XML を操作します。これは、文字列内のトークンの拡張と考えることができます。パターン ${token} に一致する生の XML 文字列の任意の部分が、トークン拡張の候補です。外部ソースに対応する値が見つからない場合、トークンは変更されません。このモードのビルダーは、セクションと <connectionStrings/> セクションに<appSettings/>限定されません。

web.config の次のマークアップにより、EnvironmentConfigBuilder がモードでStrict有効になります。

<configuration>

  <configSections>
    <section name="configBuilders" 
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="MyEnvironment"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="MyEnvironment">
    <add key="ServiceID" value="ServiceID value from web.config" />
    <add key="ServiceKey" value="ServiceKey value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="MyEnvironment">
    <add name="default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>

次のコードは、を <appSettings/> 読み取り、 <connectionStrings/> 前の web.config ファイルに示しています。

using System;
using System.Configuration;
using System.Web.UI;

namespace MyConfigBuilders
{
    public partial class About : Page
    {
        public string ServiceID { get; set; }
        public string ServiceKey { get; set; }
        public string ConString { get; set; }

        protected void Page_Load(object sender, EventArgs e)
        {
            ServiceID = ConfigurationManager.AppSettings["ServiceID"];
            ServiceKey = ConfigurationManager.AppSettings["ServiceKey"];
            ConString = ConfigurationManager.ConnectionStrings["default"]
                                            ?.ConnectionString;
        }
    }
}

上記のコードでは、プロパティ値が次の値に設定されます。

キーが環境変数に設定されていない場合は、 web.config ファイル内の値。
環境変数の値 (設定されている場合)。

たとえば、には次 ServiceID のものが含まれます。

環境変数 ServiceID が設定されていない場合は、「web.config からの ServiceID 値」。
環境変数の ServiceID 値 (設定されている場合)。

次の図は、環境エディターの <appSettings/> 前 のweb.config ファイルセットのキー/値を示しています。

ServiceID 変数と ServiceKey 変数が強調表示された環境変数エディターを示すスクリーンショット。

注: 環境変数の変更を確認するには、Visual Studio を終了して再起動する必要がある場合があります。

プレフィックスの処理

キープレフィックスを使用すると、次の理由でキーの設定を簡略化できます。

.NET Framework構成は複雑で入れ子になります。
外部キー/値ソースは、一般的に基本的でフラットです。たとえば、環境変数は入れ子になっていません。

環境変数を使用してとの両方<appSettings/><connectionStrings/>を構成に挿入するには、次のいずれかの方法を使用します。

EnvironmentConfigBuilderを既定Strictモードにし、構成ファイルに適切なキー名を指定します。上記のコードとマークアップでは、このアプローチを採用しています。この方法を使用すると、と <connectionStrings/>の両方<appSettings/>で同じ名前のキーを使用することはできません。
異なるプレフィックスと stripPrefixを持つモードで Greedy 2 つの EnvironmentConfigBuilderを使用します。この方法では、アプリは構成ファイルを更新しなくても読み取<appSettings/><connectionStrings/>ることができます。次のセクション stripPrefix では、これを行う方法を示します。
異なるプレフィックスを持つモードで Greedy 2 つの EnvironmentConfigBuilders を使用します。この方法では、キー名がプレフィックスによって異なる必要があり、重複するキー名を持つすることはできません。次に例を示します。

<configuration>

  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment" />
      <add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="AS_Environment">
    <add key="AppSetting_ServiceID" value="ServiceID value from web.config" />
    <add key="AppSetting_default" value="AppSetting_default value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="CS_Environment">
    <add name="ConnStr_default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>

上記のマークアップでは、同じフラットキー/値ソースを使用して、2 つの異なるセクションの構成を設定できます。

次の図は、環境エディターの<appSettings/>前の web.config ファイルセットのおよび <connectionStrings/> キー/値を示しています。

AppSetting_default、AppSetting_ServiceID、ConnStr_default変数が強調表示された環境変数エディターを示すスクリーンショット。

次のコードは、前の <appSettings/>web.config ファイルに含まれると <connectionStrings/> のキー/値を読み取ります。

public partial class Contact : Page
{
    public string ServiceID { get; set; }
    public string AppSetting_default { get; set; }
    public string ConString { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        ServiceID = ConfigurationManager.AppSettings["AppSetting_ServiceID"];
        AppSetting_default = ConfigurationManager.AppSettings["AppSetting_default"];
        ConString = ConfigurationManager.ConnectionStrings["ConnStr_default"]
                                     ?.ConnectionString;
    }
}

上記のコードでは、プロパティ値が次の値に設定されます。

キーが環境変数に設定されていない場合は、 web.config ファイル内の値。
環境変数の値 (設定されている場合)。

たとえば、前の web.config ファイル、前の環境エディターイメージのキー/値、および前のコードを使用すると、次の値が設定されます。

Key	値
AppSetting_ServiceID	env 変数からのAppSetting_ServiceID
AppSetting_default	env から値をAppSetting_defaultする
ConnStr_default	env から val をConnStr_defaultする

stripPrefix

stripPrefix: boolean、既定値は falseです。

上記の XML マークアップは、アプリ設定を接続文字列から分離しますが、指定したプレフィックスを使用するには 、web.config ファイル内のすべてのキーが必要です。たとえば、プレフィックス AppSetting をキー ("AppSetting_ServiceID") に追加する ServiceID 必要があります。では stripPrefix、プレフィックスは web.config ファイルでは使用されません。プレフィックスは、構成ビルダーソース (環境など) で必要です。ほとんどの開発者がを使用 stripPrefixすると予想されます。

通常、アプリケーションはプレフィックスを取り除きます。次の web.config はプレフィックスを取り除きます。

<configuration>

  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="AS_Environment" mode="Greedy" prefix="AppSetting_" 
           stripPrefix="true"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
      <add name="CS_Environment" mode="Greedy" prefix="ConnStr_" 
           stripPrefix="true"
            type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="AS_Environment">
    <add key="ServiceID" value="ServiceID value from web.config" />
    <add key="default" value="AppSetting_default value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="CS_Environment">
    <add name="default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>

前の web.config ファイルでは、defaultキーはと <connectionStrings/>の<appSettings/>両方にあります。

次の図は、環境エディターの<appSettings/>前の web.config ファイルセットのおよび <connectionStrings/> キー/値を示しています。

AppSetting_default、AppSetting_ServiceID、ConnStr_default変数が強調表示された環境変数エディターを示すスクリーンショット。

次のコードは、前の <appSettings/>web.config ファイルに含まれると <connectionStrings/> のキー/値を読み取ります。

public partial class About2 : Page
{
    public string ServiceID { get; set; }
    public string AppSetting_default { get; set; }
    public string ConString { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        ServiceID = ConfigurationManager.AppSettings["ServiceID"];
        AppSetting_default = ConfigurationManager.AppSettings["default"];
        ConString = ConfigurationManager.ConnectionStrings["default"]
                                        ?.ConnectionString;
    }
}

上記のコードでは、プロパティ値が次の値に設定されます。

キーが環境変数に設定されていない場合は、 web.config ファイル内の値。
環境変数の値 (設定されている場合)。

たとえば、前の web.config ファイル、前の環境エディターイメージのキー/値、および前のコードを使用すると、次の値が設定されます。

Key	値
ServiceID	env 変数からのAppSetting_ServiceID
default	env から値をAppSetting_defaultする
default	env から val をConnStr_defaultする

tokenPattern

tokenPattern: String、既定値は @"\$\{(\w+)\}"

ビルダーの動作では Expand 、生 XML でのような ${token}トークンが検索されます。検索は、既定の正規表現 @"\$\{(\w+)\}"で行われます。一致 \w する文字のセットは XML よりも厳密であり、多くの構成ソースで許可されています。トークン名に必要な文字数を超える@"\$\{(\w+)\}"場合はを使用tokenPatternします。

tokenPattern：文字列：

開発者がトークンの照合に使用される正規表現を変更できるようにします。
適切な形式の危険でない正規表現であることを確認するための検証は行われません。
キャプチャグループが含まれている必要があります。正規表現全体がトークン全体と一致している必要があります。最初のキャプチャは、構成ソースで検索するトークン名である必要があります。

Microsoft.Configuration.ConfigurationBuilders の構成ビルダー

EnvironmentConfigBuilder

<add name="Environment"
    [mode|prefix|stripPrefix|tokenPattern] 
    type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Environment" />

EnvironmentConfigBuilder:

構成ビルダーの中で最も簡単です。
環境から値を読み取ります。
追加の構成オプションはありません。
属性値は name 任意です。

メモ： Windows コンテナー環境では、実行時に設定された変数は EntryPoint プロセス環境にのみ挿入されます。サービスまたは EntryPoint 以外のプロセスとして実行されるアプリは、コンテナー内のメカニズムを介して挿入されない限り、これらの変数を取得しません。 IIS/ASP.NET ベースのコンテナーの場合、現在のバージョンの ServiceMonitor.exe はこれを DefaultAppPool でのみ処理します。他の Windows ベースのコンテナーバリアントでは、EntryPoint 以外のプロセス用に独自のインジェクションメカニズムを開発する必要がある場合があります。

UserSecretsConfigBuilder

警告

パスワード、機密性の高い接続文字列、またはその他の機密データをソースコードに保存しないでください。運用シークレットは、開発やテストには使用しないでください。

<add name="UserSecrets"
    [mode|prefix|stripPrefix|tokenPattern]
    (userSecretsId="{secret string, typically a GUID}" | userSecretsFile="~\secrets.file")
    [optional="true"]
    type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />

上記の XML では、パスで userSecretsFile または ~\を使用~/できます。たとえば、パスをとして userSecretsFile="~/secrets.file書き込む場合があります。詳細については、「 ConfigurationBuilders Utils クラス」を参照してください。

この構成ビルダーは、ASP.NET Core Secret Manager と同様の機能を提供します。

UserSecretsConfigBuilder は、.NET Framework プロジェクトで使用できますが、シークレットファイルを指定する必要があります。または、プロジェクトファイルでプロパティを UserSecretsId 定義し、読み取り用の正しい場所に生のシークレットファイルを作成することもできます。外部の依存関係をプロジェクトから除外するために、シークレットファイルは XML 形式です。 XML の書式設定は実装の詳細であり、形式は依存しないようにする必要があります。 secrets.json ファイルを .NET Core プロジェクトと共有する必要がある場合は、SimpleJsonConfigBuilder の使用を検討してください。 .NET Core の形式も SimpleJsonConfigBuilder 、変更される実装の詳細と見なす必要があります。

の UserSecretsConfigBuilder構成属性:

userSecretsId - これは、XML シークレットファイルを識別するための推奨される方法です。これは、プロジェクトプロパティを使用してこの識別子を UserSecretsId 格納する .NET Core と同様に機能します。文字列は一意である必要があります。GUID である必要はありません。この属性を UserSecretsConfigBuilder 使用すると、既知のローカルの場所 (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml) で、この識別子に属するシークレットファイルが検索されます。
userSecretsFile - シークレットを含むファイルを指定する省略可能な属性。文字は ~ 、開始時にアプリケーションルートを参照するために使用できます。この属性または属性が userSecretsId 必要です。両方を指定する場合は、 userSecretsFile が優先されます。
optional: boolean、既定値 true - シークレットファイルが見つからない場合に例外を回避します。
属性値は name 任意です。

シークレットファイルの形式は次のとおりです。

<?xml version="1.0" encoding="utf-8" ?>
<root>
  <secrets ver="1.0">
    <secret name="secret key name" value="secret value" />
  </secrets>
</root>

AzureKeyVaultConfigBuilder

<add name="AzureKeyVault"
    [mode|prefix|stripPrefix|tokenPattern]
    (vaultName="MyVaultName" |
     uri="https:/MyVaultName.vault.azure.net")
    [version="secrets version"]
    [preloadSecretNames="true"]
    type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Azure" />

AzureKeyVaultConfigBuilder は、Azure Key Vaultに格納されている値を読み取ります。

vaultName は必須です (コンテナーの名前またはコンテナーの URI)。他の属性を使用すると、接続先のコンテナーを制御できますが、アプリケーションがで Microsoft.Azure.Services.AppAuthentication動作する環境で実行されていない場合にのみ必要です。 Azure Services 認証ライブラリは、可能であれば、実行環境から接続情報を自動的に取得するために使用されます。接続文字列を指定することで、接続情報を自動的に取得することをオーバーライドできます。

vaultName - が指定されていない場合 uri は必須。キーと値のペアの読み取り元となる Azure サブスクリプション内のコンテナーの名前を指定します。
uri- 指定したuri値を持つ他のKey Vault プロバイダーに接続します。指定しない場合、Azure (vaultName) はコンテナープロバイダーです。
version- Azure Key Vault では、シークレットのバージョン管理機能が提供されます。が指定されている場合 version 、ビルダーは、このバージョンに一致するシークレットのみを取得します。
preloadSecretNames - 既定では、このビルダーは、初期化時にキーコンテナー 内のすべての キー名に対してクエリを実行します。すべてのキー値を読み取らないようにするには、この属性をに設定します false。これを設定すると、 false シークレットが一度に 1 つずつ読み取ります。シークレットを一度に 1 つずつ読み取ると、コンテナーで "取得" アクセスは許可されますが、"リスト" アクセスは許可されない場合に便利です。 メモ： モードを使用 Greedy する場合は、 preloadSecretNames である true 必要があります (既定値)。

KeyPerFileConfigBuilder

<add name="KeyPerFile"
    [mode|prefix|stripPrefix|tokenPattern]
    (directoryPath="PathToSourceDirectory")
    [ignorePrefix="ignore."]
    [keyDelimiter=":"]
    [optional="false"]
    type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />

KeyPerFileConfigBuilder は、ディレクトリのファイルを値のソースとして使用する基本的な構成ビルダーです。ファイルの名前がキーであり、内容が値です。この構成ビルダーは、調整されたコンテナー環境でを実行する場合に便利です。 Docker Swarm や Kubernetes などのシステムは、ファイルごとのキー方式で調整された Windows コンテナーに提供 secrets します。

属性の詳細:

directoryPath - 必須。値を検索するパスを指定します。 Docker for Windows シークレットは、既定で C:\ProgramData\Docker\secrets ディレクトリに格納されます。
ignorePrefix - このプレフィックスで始まるファイルは除外されます。既定値は "ignore" です。
keyDelimiter - 既定値はです null。指定した場合、構成ビルダーはディレクトリの複数のレベルを走査し、この区切り記号を使用してキー名を作成します。この値がの null場合、構成ビルダーはディレクトリの最上位レベルのみを参照します。
optional - 既定値はです false。ソースディレクトリが存在しない場合に構成ビルダーがエラーを発生させるかどうかを指定します。

SimpleJsonConfigBuilder

警告

<add name="SimpleJson"
    [mode|prefix|stripPrefix|tokenPattern]
    jsonFile="~\config.json"
    [optional="true"]
    [jsonMode="(Flat|Sectional)"]
    type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Json" />

.NET Core プロジェクトでは、構成に JSON ファイルが頻繁に使用されます。 SimpleJsonConfigBuilder ビルダーを使用すると、.NET Core JSON ファイルを.NET Frameworkで使用できます。この構成ビルダーは、フラットキー/値ソースから、.NET Framework構成の特定のキー/値領域への基本的なマッピングを提供します。この構成ビルダーでは、階層構成は提供 されません 。 JSON バッキングファイルは、複雑な階層オブジェクトではなく、ディクショナリに似ています。複数レベルの階層ファイルを使用できます。このプロバイダー flattenは、を区切り記号として使用 : して、各レベルでプロパティ名を追加することで深さを示します。

属性の詳細:

jsonFile - 必須。読み取り元の JSON ファイルを指定します。文字は ~ 、開始時にアプリルートを参照するために使用できます。
optional - ブール値、既定値はです true。 JSON ファイルが見つからない場合に例外をスローしないようにします。
jsonMode - [Flat|Sectional]. Flat は既定値です。が Flatの場合jsonMode、JSON ファイルは単一のフラットキー/値ソースです。 EnvironmentConfigBuilderと AzureKeyVaultConfigBuilder は、単一のフラットキー/値ソースでもあります。 SimpleJsonConfigBuilderがモードでSectional構成されている場合:
- JSON ファイルは概念的には最上位レベルだけで複数のディクショナリに分割されます。
- 各ディクショナリは、添付されている最上位のプロパティ名と一致する構成セクションにのみ適用されます。次に例を示します。

    {
        "appSettings" : {
            "setting1" : "value1",
            "setting2" : "value2",
            "complex" : {
                "setting1" : "complex:value1",
                "setting2" : "complex:value2",
            }
        }
    }

構成ビルダーの順序

aspnet/MicrosoftConfigurationBuilders GitHub リポジトリの「ConfigurationBuilders の実行順序」を参照してください。

カスタムキー/値構成ビルダーの実装

構成ビルダーがニーズを満たしていない場合は、カスタムビルダーを記述できます。基底クラスは KeyValueConfigBuilder 、置換モードとほとんどのプレフィックスの懸念事項を処理します。実装するプロジェクトでは、次のものが必要です。

基底クラスから継承し、とを介してキーと値のペアの基本的なソースをGetValueGetAllValues実装します。
Microsoft.Configuration.ConfigurationBuilders.Base をプロジェクトに追加します。

using Microsoft.Configuration.ConfigurationBuilders;
using System.Collections.Generic;

public class MyCustomConfigBuilder : KeyValueConfigBuilder
{
    public override string GetValue(string key)
    {
        // Key lookup should be case-insensitive, because most key/value collections in 
        // .NET Framework config sections are case-insensitive.
        return "Value for given key, or null.";
    }

    public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
    {
        // Populate the return collection.
        return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
    }
}

基本クラスは KeyValueConfigBuilder 、キー/値構成ビルダー間で動作と一貫性のある動作の多くを提供します。

Share via

ASP.NET の構成ビルダー

キー/値構成ビルダー

キー/値構成ビルダーの設定

モード

プレフィックスの処理

stripPrefix

tokenPattern

Microsoft.Configuration.ConfigurationBuilders の構成ビルダー

EnvironmentConfigBuilder

UserSecretsConfigBuilder

AzureKeyVaultConfigBuilder

KeyPerFileConfigBuilder

SimpleJsonConfigBuilder

構成ビルダーの順序

カスタムキー/値構成ビルダーの実装

その他のリソース

フィードバック

フィードバック

その他のリソース

Share via

ASP.NET の構成ビルダー

キー/値構成ビルダー

キー/値構成ビルダーの設定

モード

プレフィックスの処理

stripPrefix

tokenPattern

Microsoft.Configuration.ConfigurationBuilders の構成ビルダー

EnvironmentConfigBuilder

UserSecretsConfigBuilder

AzureKeyVaultConfigBuilder

KeyPerFileConfigBuilder

SimpleJsonConfigBuilder

構成ビルダーの順序

カスタム キー/値構成ビルダーの実装

その他のリソース

フィードバック

フィードバック

その他のリソース

カスタムキー/値構成ビルダーの実装