ASP.NET Core の構成Configuration in ASP.NET Core

作成者: Luke LathamBy Luke Latham

ASP.NET Core でのアプリの構成は、"構成プロバイダー" によって設定するキーと値のペアに基づいています。App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. 構成プロバイダーは、さまざまな構成のソースから構成データを読み取り、キーと値のペアを作成します。Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • コマンド ライン引数Command-line arguments
  • カスタム プロバイダー (インストール済みまたは作成済み)Custom providers (installed or created)
  • ディレクトリ ファイルDirectory files
  • 環境変数Environment variables
  • メモリ内 .NET オブジェクトIn-memory .NET objects
  • 設定ファイルSettings files

一般的な構成プロバイダーのシナリオに向けた構成パッケージは、Microsoft.AspNetCore.App メタパッケージに含まれます。Configuration packages for common configuration provider scenarios are included in the Microsoft.AspNetCore.App metapackage. 以下とサンプル アプリのコード例では、Microsoft.Extensions.Configuration 名前空間を使います。Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

"オプション パターン" は、このトピックで説明する構成の概念を拡張したものです。The options pattern is an extension of the configuration concepts described in this topic. オプションでは、クラスを使用して関連する設定のグループを表します。Options uses classes to represent groups of related settings. オプション パターンの使用について詳しくは、「ASP.NET Core のオプション パターン」をご覧ください。For more information on using the options pattern, see ASP.NET Core のオプション パターン.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

ホストとアプリの構成Host vs. app configuration

アプリを構成して起動する前に、"ホスト" を構成して起動します。Before the app is configured and started, a host is configured and launched. ホストはアプリの起動と有効期間の管理を担当します。The host is responsible for app startup and lifetime management. アプリとホストは、両方ともこのトピックで説明する構成プロバイダーを使用して構成します。Both the app and the host are configured using the configuration providers described in this topic. ホストの構成のキーと値のペアは、アプリのグローバル構成の一部となります。Host configuration key-value pairs become part of the app's global configuration. ホストをビルドするときの構成プロバイダーの使用方法、およびホストの構成に対する構成ソースの影響について詳しくは、ホストに関する説明を参照してください。For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see The host.

既定の構成Default configuration

ASP.NET Core の dotnet new テンプレートに基づく Web アプリは、ホストの構築時に CreateDefaultBuilder を呼び出します。Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder により、次の順序でアプリの既定の構成が提供されます。CreateDefaultBuilder provides default configuration for the app in the following order:

これらの構成プロバイダーについては、このトピックの後半で説明します。The configuration providers are explained later in this topic. ホストと CreateDefaultBuilder の詳細については、ASP.NET Core の Web ホスト を参照してください。For more information on the host and CreateDefaultBuilder, see ASP.NET Core の Web ホスト.

セキュリティSecurity

次のベスト プラクティスを採用します。Adopt the following best practices:

  • 構成プロバイダーのコードやプレーンテキストの構成ファイルには、パスワードなどの機密データを格納しないでください。Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • 開発環境やテスト環境では運用シークレットを使用しないでください。Don't use production secrets in development or test environments.
  • プロジェクトの外部にシークレットを指定してください。そうすれば、誤ってリソース コード リポジトリにコミットされることはありません。Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

複数の環境を使用する方法や、シークレット マネージャーでの開発中のアプリ シークレットの安全な格納の管理 (機密データを格納するための環境変数の使用に関するアドバイスを含む) について、さらに学習することができます。Learn more about how to use multiple environments and managing the safe storage of app secrets in development with the Secret Manager (includes advice on using environment variables to store sensitive data). シークレット マネージャーは、ファイル構成プロバイダーを使用して、ユーザーの機密情報をローカル システム上の JSON ファイルに格納します。The Secret Manager uses the File Configuration Provider to store user secrets in a JSON file on the local system. ファイル構成プロバイダーについては、このトピックの後半で説明します。The File Configuration Provider is described later in this topic.

Azure Key Vault は、アプリのシークレットを安全に格納するための 1 つのオプションです。Azure Key Vault is one option for the safe storage of app secrets. 詳細については、「ASP.NET Core での azure Key Vault 構成プロバイダー」を参照してください。For more information, see ASP.NET Core での azure Key Vault 構成プロバイダー.

階層的な構成データHierarchical configuration data

構成 API は、構成キー内の区切り記号を使用して階層データをフラット化することにより、階層的な構成データを管理することができます。The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

次の JSON ファイルでは、2 つのセクションの構造化階層に 4 つのキーが存在します。In the following JSON file, four keys exist in a structured hierarchy of two sections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

ファイルが構成に読み込まれると、構成ソースの元の階層データ構造を維持するために、一意なキーが作成されます。When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. セクションとキーは、元の構造を維持するために、コロン (:) を使用してフラット化されます。The sections and keys are flattened with the use of a colon (:) to maintain the original structure:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

GetSection メソッドと GetChildren メソッドを使用して、構成データ内のセクションとセクションの子を分離することができます。GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. これらのメソッドについては、後ほど「GetSection、GetChildren、Exists」で説明します。These methods are described later in GetSection, GetChildren, and Exists. GetSectionMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration パッケージにあります。GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

規約Conventions

アプリの起動時に、各構成プロバイダーが指定されている順序で構成ソースが読み取られます。At app startup, configuration sources are read in the order that their configuration providers are specified.

変更の検出を実装する構成プロバイダーは、基になる設定が変更された場合に構成を再読み込みする機能を備えています。Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. たとえば、ファイル構成プロバイダー (このトピックで後から説明します) とAzure Key Vault 構成プロバイダーでは、変更の検出を実装します。For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

IConfiguration は、アプリの依存関係の挿入 (DI) コンテナーで使用できます。IConfiguration is available in the app's dependency injection (DI) container. IConfiguration を Razor Pages PageModel を挿入して、クラスの構成を取得することができます。IConfiguration can be injected into a Razor Pages PageModel to obtain configuration for the class:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    // The _config local variable is used to obtain configuration 
    // throughout the class.
}

構成プロバイダーでは DI を使用できません。ホストによって構成プロバイダーが設定されている場合、DI を使用できないためです。Configuration providers can't utilize DI, as it's not available when they're set up by the host.

構成キーでは、次の規則が採用されます。Configuration keys adopt the following conventions:

  • キーでは、大文字と小文字は区別されません。Keys are case-insensitive. たとえば、ConnectionStringconnectionstring は同等のキーとして扱われます。For example, ConnectionString and connectionstring are treated as equivalent keys.
  • 同じキーに対する値が、同じまたは別の構成プロバイダーによって設定された場合、最後にキーに設定された値が使用される値となります。If a value for the same key is set by the same or different configuration providers, the last value set on the key is the value used.
  • 階層キーHierarchical keys
    • 構成 API 内では、すべてのプラットフォームでコロン (:) の区切りが機能します。Within the Configuration API, a colon separator (:) works on all platforms.
    • 環境変数内では、コロン区切りがすべてのプラットフォームでは機能しない場合があります。In environment variables, a colon separator may not work on all platforms. 二重のアンダースコア (__) はすべてのプラットフォームでサポートされ、コロンに変換されます。A double underscore (__) is supported by all platforms and is converted to a colon.
    • Azure Key Vault では、階層キーは区切り記号として -- (2 つのダッシュ) を使用します。In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. コードを指定して、アプリの構成にシークレットが読み込まれるときにダッシュをコロンで置き換える必要があります。You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • ConfigurationBinder は、構成キーで配列インデックスを使用して、オブジェクトに対する配列のバインドをサポートしています。The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. 配列のバインドについては、「配列をクラスにバインドする」セクションで説明します。Array binding is described in the Bind an array to a class section.

構成値では、次の規則が採用されます。Configuration values adopt the following conventions:

  • 値は文字列です。Values are strings.
  • Null 値を構成に格納したり、オブジェクトにバインドしたりすることはできません。Null values can't be stored in configuration or bound to objects.

プロバイダーProviders

ASP.NET Core アプリで使用できる構成プロバイダーを次の表に示します。The following table shows the configuration providers available to ASP.NET Core apps.

プロバイダーProvider … から構成を提供します。Provides configuration from…
Azure Key Vault 構成プロバイダー ("セキュリティ" トピック)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
コマンド ライン構成プロバイダーCommand-line Configuration Provider コマンド ライン パラメーターCommand-line parameters
カスタム構成プロバイダーCustom configuration provider カスタム ソースCustom source
環境変数構成プロバイダーEnvironment Variables Configuration Provider 環境変数Environment variables
ファイル構成プロバイダーFile Configuration Provider ファイル (INI、JSON、XML)Files (INI, JSON, XML)
ファイルごとのキーの構成プロバイダーKey-per-file Configuration Provider ディレクトリ ファイルDirectory files
メモリ構成プロバイダーMemory Configuration Provider メモリ内コレクションIn-memory collections
ユーザー シークレット (Secret Manager) ("セキュリティ" トピック)User secrets (Secret Manager) (Security topics) ユーザー プロファイル ディレクトリ内のファイルFile in the user profile directory

アプリの起動時に各構成プロバイダーが指定されている順序で構成ソースが読み取られます。Configuration sources are read in the order that their configuration providers are specified at startup. このトピックで説明する構成プロバイダーは、それらをコードで配置する順ではなく、アルファベット順で説明します。The configuration providers described in this topic are described in alphabetical order, not in the order that your code may arrange them. 基になる構成ソースの優先順位に合わせるために、コード内で構成プロバイダーを並べ替えます。Order configuration providers in your code to suit your priorities for the underlying configuration sources.

一般的な一連の構成プロバイダーは次のとおりです。A typical sequence of configuration providers is:

  1. ファイル (appsettings.jsonappsettings.{Environment}.json{Environment} はアプリの現在のホスト環境です)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure Key VaultAzure Key Vault
  3. ユーザー シークレット (Secret Manager) (開発環境の場合のみ)User secrets (Secret Manager) (in the Development environment only)
  4. 環境変数Environment variables
  5. コマンド ライン引数Command-line arguments

コマンド ライン引数が他のプロバイダーによって設定された構成をオーバーライドできるようにするために、コマンド ラインの構成プロバイダーを一連のプロバイダーの最後に配置するのは、一般的な方法です。It's a common practice to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

この一連のプロバイダーは、CreateDefaultBuilder を使用して新しい WebHostBuilder を初期化するときに配置されます。This sequence of providers is put into place when you initialize a new WebHostBuilder with CreateDefaultBuilder. 詳細については、「Web ホスト: ホストを設定する」を参照してください。For more information, see Web Host: Set up a host.

ConfigureAppConfigurationConfigureAppConfiguration

ホストをビルドするときに ConfigureAppConfiguration を呼び出し、CreateDefaultBuilder によって自動的に追加されるものに加え、アプリの構成プロバイダーを指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

ConfigureAppConfiguration のアプリに指定した構成は、Startup.ConfigureServices などのアプリの起動中に使用できます。Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. 詳細については、「起動中に構成にアクセスする」のセクションを参照してください。For more information, see the Access configuration during startup section.

コマンド ライン構成プロバイダーCommand-line Configuration Provider

CommandLineConfigurationProvider では、実行時にコマンドライン引数のキーと値のペアから構成が読み込まれます。The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

コマンド ライン構成をアクティブにするために、AddCommandLine 拡張メソッドが ConfigurationBuilder のインスタンスで呼び出されます。To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

CreateDefaultBuilder で新しい WebHostBuilder を初期化すると、自動的に AddCommandLine が呼び出されます。AddCommandLine is automatically called when you initialize a new WebHostBuilder with CreateDefaultBuilder. 詳細については、「Web ホスト: ホストを設定する」を参照してください。For more information, see Web Host: Set up a host.

CreateDefaultBuilder では次のものも読み込まれます。CreateDefaultBuilder also loads:

CreateDefaultBuilder はコマンド ライン構成プロバイダーを最後に追加します。CreateDefaultBuilder adds the Command-line Configuration Provider last. 実行時に渡されるコマンド ライン引数によって、他のプロバイダーによって設定された構成がオーバーライドされます。Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder は、ホストが作成されるときに機能します。CreateDefaultBuilder acts when the host is constructed. そのため、CreateDefaultBuilder によってアクティブ化されるコマンド ライン構成によって、ホストの構成方法に影響を与えることができます。Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration.

AddCommandLine は既に CreateDefaultBuilder によって呼び出されています。AddCommandLine has already been called by CreateDefaultBuilder. アプリの構成を指定して、引き続きコマンドラインの引数でその構成をオーバーライドできるようにする必要がある場合、ConfigureAppConfiguration でアプリの追加のプロバイダーを呼び出し、最後に AddCommandLine を呼び出します。If you need to provide app configuration and still be able to override that configuration with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                // Call other providers here and call AddCommandLine last.
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    // Call additional providers here as needed.
    // Call AddCommandLine last to allow arguments to override other configuration.
    .AddCommandLine(args)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

Example

サンプル アプリでは、静的な簡易メソッド CreateDefaultBuilder を利用してホストをビルドします。これには AddCommandLine の呼び出しが含まれます。The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. プロジェクトのディレクトリでコマンド プロンプトを開きます。Open a command prompt in the project's directory.
  2. dotnet run コマンドにコマンドライン引数を指定します (dotnet run CommandLineKey=CommandLineValue)。Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. アプリを実行したら、アプリに対して http://localhost:5000 でブラウザーを開きます。After the app is running, open a browser to the app at http://localhost:5000.
  4. 出力に、dotnet run に提供される構成のコマンド ライン引数のキーと値のペアが含まれていることを観察します。Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

引数Arguments

値は等号 (=) の後に続ける必要があります。または、値をスペースの後に続ける場合は、キーにプレフィックス (--または/) を付ける必要があります。The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. 等号を使用する場合は、値に null を指定できます (例: CommandLineKey=)。The value can be null if an equals sign is used (for example, CommandLineKey=).

キーのプレフィックスKey prefix Example
プレフィックスなしNo prefix CommandLineKey1=value1
2 つのダッシュ (--)Two dashes (--) --CommandLineKey2=value2--CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
スラッシュ (/)Forward slash (/) /CommandLineKey3=value3/CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

同じコマンド内のコマンド ライン引数で、等号を使用するキーと値のペアと、スペースを使用するキーと値のペアを混在させないでください。Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-value pairs that use a space.

コマンドの例:Example commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

スイッチ マッピングSwitch mappings

スイッチ マッピングでは、キー名の交換ロジックが許可されます。Switch mappings allow key name replacement logic. ConfigurationBuilder で構成を手動でビルドするときに、AddCommandLine メソッドにスイッチ置換のディクショナリを指定することができます。When you manually build configuration with a ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.

スイッチ マッピング ディクショナリが使用されている場合、そのディレクトリで、コマンドライン引数によって指定されたキーと一致するキーが確認されます。When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. コマンド ライン キーがディクショナリで見つかった場合は、アプリの構成にキーと値のペアを設定するためにディクショナリの値 (キー交換) が返されます。If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the key-value pair into the app's configuration. スイッチ マッピングは、単一のダッシュ (-) が前に付いたすべてのコマンドライン キーに必要です。A switch mapping is required for any command-line key prefixed with a single dash (-).

スイッチ マッピング ディクショナリ キーの規則:Switch mappings dictionary key rules:

  • スイッチはダッシュ (-) または二重ダッシュ (--) で開始する必要があります。Switches must start with a dash (-) or double-dash (--).
  • スイッチ マッピング ディクショナリに重複キーを含めることはできません。The switch mappings dictionary must not contain duplicate keys.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static readonly Dictionary<string, string> _switchMappings = 
        new Dictionary<string, string>
        {
            { "-CLKey1", "CommandLineKey1" },
            { "-CLKey2", "CommandLineKey2" }
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    // Do not pass the args to CreateDefaultBuilder
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, _switchMappings);
            })
            .UseStartup<Startup>();
}

前の例で示したように、スイッチ マッピングを使用する場合は CreateDefaultBuilder への呼び出しが引数を渡すことはできません。As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch mappings are used. CreateDefaultBuilder メソッドの AddCommandLine の呼び出しにはマップされたスイッチが含まれないため、スイッチ マッピング ディクショナリを CreateDefaultBuilder に渡す方法はありません。CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. 引数にマップされたスイッチが含まれており、それが CreateDefaultBuilder に渡される場合は、その AddCommandLine プロバイダーは FormatException で初期化に失敗します。If the arguments include a mapped switch and are passed to CreateDefaultBuilder, its AddCommandLine provider fails to initialize with a FormatException. ソリューションでは CreateDefaultBuilder に引数を渡す代わりに、ConfigurationBuilder メソッドの AddCommandLine メソッドに、引数とスイッチ マッピング ディクショナリの両方を処理させることができます。The solution isn't to pass the arguments to CreateDefaultBuilder but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch mapping dictionary.

スイッチ マッピング ディクショナリが作成されると、以下の表に示すデータが含まれます。After the switch mappings dictionary is created, it contains the data shown in the following table.

キーKey [値]Value
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

アプリの起動時にスイッチ マッピングされたキーを使用する場合、構成は、ディクショナリによって指定されたキーでの構成値を受け取ります。If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the key supplied by the dictionary:

dotnet run -CLKey1=value1 -CLKey2=value2

上記のコマンドを実行すると、次の表に示す値が構成に含まれます。After running the preceding command, configuration contains the values shown in the following table.

キーKey [値]Value
CommandLineKey1 value1
CommandLineKey2 value2

環境変数構成プロバイダーEnvironment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider では、実行時に環境変数のキーと値のペアから構成が読み込まれます。The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

環境変数の構成をアクティブにするには、ConfigurationBuilder のインスタンスの AddEnvironmentVariables 拡張メソッドを呼び出します。To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

環境変数内で階層キーを操作する場合、コロン区切り (:) がすべてのプラットフォームでは機能しない場合があります (Bash など)。When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). 二重のアンダースコア (__) はすべてのプラットフォームでサポートされ、コロンに置換されます。A double underscore (__) is supported by all platforms and is replaced by a colon.

Azure App Service を使用すると、環境変数構成プロバイダーを使用してアプリの構成をオーバーライドすることができる環境変数を、Azure Portal で設定できます。Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. 詳細については、「Azure アプリ: Azure Portal を使用してアプリの構成をオーバーライドする」を参照してください。For more information, see Azure Apps: Override app configuration using the Azure Portal.

新しい WebHostBuilder が初期化されるときに、ホスト構成ASPNETCORE_ でプレフィックスされている環境変数を読み込むために AddEnvironmentVariables が使用されます。AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new WebHostBuilder is initialized. 詳細については、「Web ホスト: ホストを設定する」を参照してください。For more information, see Web Host: Set up a host.

CreateDefaultBuilder では次のものも読み込まれます。CreateDefaultBuilder also loads:

  • プレフィックスなしの AddEnvironmentVariables 呼び出しによる、プレフィックスの付いていない環境変数からのアプリの構成。App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • appsettings.json および appsettings.{Environment}.json からのオプションの構成。Optional configuration from appsettings.json and appsettings.{Environment}.json.
  • ユーザー シークレット (Secret Manager) (開発環境の場合)。User secrets (Secret Manager) (in the Development environment).
  • コマンド ライン引数。Command-line arguments.

ユーザー シークレットと appsettings ファイルから構成が設定された後に、環境変数構成プロバイダーが呼び出されます。The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. この位置でプロバイダーを呼び出すことにより、実行時に読み込まれた環境変数が、ユーザー シークレットと appsettings ファイルによって設定された構成をオーバーライドすることができます。Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration.

追加の環境変数からアプリの構成を指定する必要がある場合は、ConfigureAppConfiguration のアプリの追加プロバイダーを呼び出し、そのプレフィックスを含む AddEnvironmentVariables を呼び出します。If you need to provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                // Call additional providers here as needed.
                // Call AddEnvironmentVariables last if you need to allow
                // environment variables to override values from other 
                // providers.
                config.AddEnvironmentVariables(prefix: "PREFIX_");
            })
            .UseStartup<Startup>();
}

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables()
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

Example

サンプル アプリでは、静的な簡易メソッド CreateDefaultBuilder を利用してホストをビルドします。これには AddEnvironmentVariables の呼び出しが含まれます。The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. サンプル アプリを実行します。Run the sample app. アプリに対して http://localhost:5000 でブラウザーを開きます。Open a browser to the app at http://localhost:5000.
  2. 出力に、環境変数 ENVIRONMENT のキーと値のペアが含まれていることを観察します。Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. 値には、アプリを実行している環境が反映されます (ローカルで実行している場合は通常 Development)。The value reflects the environment in which the app is running, typically Development when running locally.

アプリによって表示される環境変数のリストを短くするために、アプリでは次で始まる環境変数がフィルター処理されます。To keep the list of environment variables rendered by the app short, the app filters environment variables to those that start with the following:

  • ASPNETCORE_ASPNETCORE_
  • urlsurls
  • ログの記録Logging
  • ENVIRONMENTENVIRONMENT
  • contentRootcontentRoot
  • AllowedHostsAllowedHosts
  • applicationNameapplicationName
  • CommandLineCommandLine

アプリで使用できるすべての環境変数を公開する場合は、Pages/Index.cshtml.csFilteredConfiguration を次のように変更します。If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

プレフィックスPrefixes

アプリの構成に読み込まれる環境変数は、AddEnvironmentVariables メソッドにプレフィックスを指定すると、フィルター処理されます。Environment variables loaded into the app's configuration are filtered when you supply a prefix to the AddEnvironmentVariables method. たとえば、プレフィックス CUSTOM_ で環境変数をフィルター処理するには、構成プロバイダーにプレフィックスを指定します。For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables("CUSTOM_")
    .Build();

構成のキーと値のペアが作成されるときに、プレフィックスは削除されます。The prefix is stripped off when the configuration key-value pairs are created.

静的な簡易メソッド CreateDefaultBuilder によって WebHostBuilder が作成され、アプリのホストが確立されます。The static convenience method CreateDefaultBuilder creates a WebHostBuilder to establish the app's host. WebHostBuilder は、作成されるときに、ASPNETCORE_ というプレフィックスが付いた環境変数からホストの構成を見つけます。When WebHostBuilder is created, it finds its host configuration in environment variables prefixed with ASPNETCORE_.

接続文字列のプレフィックスConnection string prefixes

構成 API には、アプリの環境に向けた Azure の接続文字列の構成に関係する、4 つの接続文字列環境変数のための特別な処理規則があります。The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. 表に示されるプレフィックスを含む環境変数は、AddEnvironmentVariables にプレフィックスが指定されていない場合、アプリに読み込まれます。Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

接続文字列のプレフィックスConnection string prefix プロバイダーProvider
CUSTOMCONNSTR_ カスタム プロバイダーCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL DatabaseAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

表に示す 4 つのプレフィックスのいずれかを使用して、環境変数が検出され構成に読み込まれた場合:When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • 環境変数のプレフィックスを削除し、構成キーのセクション (ConnectionStrings) を追加することによって、構成キーが作成されます。The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • データベースの接続プロバイダーを表す新しい構成のキーと値のペアが作成されます (示されたプロバイダーを含まない CUSTOMCONNSTR_ を除く)。A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
環境変数キーEnvironment variable key 変換された構成キーConverted configuration key プロバイダーの構成エントリProvider configuration entry
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> 構成エントリは作成されません。Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> キー: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
値: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> キー: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
値: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> キー: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
値: System.Data.SqlClientValue: System.Data.SqlClient

ファイル構成プロバイダーFile Configuration Provider

FileConfigurationProvider は、ファイル システムから構成を読み込むための基本クラスです。FileConfigurationProvider is the base class for loading configuration from the file system. 次の構成プロバイダーは、特定のファイルの種類専用です。The following configuration providers are dedicated to specific file types:

INI 構成プロバイダーINI Configuration Provider

IniConfigurationProvider では、実行時に INI ファイルのキーと値のペアから構成が読み込まれます。The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

INI ファイルの構成をアクティブにするには、ConfigurationBuilder のインスタンスの AddIniFile 拡張メソッドを呼び出します。To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

INI ファイルの構成では、セクションの区切り記号としてコロンを使用できます。The colon can be used to as a section delimiter in INI file configuration.

オーバーロードによって次のものを指定できます。Overloads permit specifying:

  • ファイルを省略可能かどうか。Whether the file is optional.
  • ファイルが変更された場合に構成を再度読み込むかどうか。Whether the configuration is reloaded if the file changes.
  • ファイルにアクセスするために IFileProvider が使用されます。The IFileProvider used to access the file.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddIniFile(
                    "config.ini", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddIniFile("config.ini", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

INI 構成ファイルの汎用的な例:A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

前の構成ファイルでは、value を使用して次のキーが読み込まれます。The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:subsection:keysection1:subsection:key
  • section2:subsection0:keysection2:subsection0:key
  • section2:subsection1:keysection2:subsection1:key

JSON 構成プロバイダーJSON Configuration Provider

JsonConfigurationProvider では、実行時に JSON ファイルのキーと値のペアから構成が読み込まれます。The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

JSON ファイルの構成をアクティブにするには、ConfigurationBuilder のインスタンスの AddJsonFile 拡張メソッドを呼び出します。To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

オーバーロードによって次のものを指定できます。Overloads permit specifying:

  • ファイルを省略可能かどうか。Whether the file is optional.
  • ファイルが変更された場合に構成を再度読み込むかどうか。Whether the configuration is reloaded if the file changes.
  • ファイルにアクセスするために IFileProvider が使用されます。The IFileProvider used to access the file.

CreateDefaultBuilder で新しい WebHostBuilder を初期化すると、自動的に AddJsonFile が 2 回呼び出されます。AddJsonFile is automatically called twice when you initialize a new WebHostBuilder with CreateDefaultBuilder. このメソッドは、次から構成を読み込むために呼び出されます。The method is called to load configuration from:

  • appsettings.json – このファイルが最初に読み取られます。appsettings.json – This file is read first. ファイルの環境バージョンは、appsettings.json ファイルによって指定される値をオーバーライドできます。The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json – ファイルの環境バージョンは、IHostingEnvironment.EnvironmentName に基づいて読み込まれます。appsettings.{Environment}.json – The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

詳細については、「Web ホスト: ホストを設定する」を参照してください。For more information, see Web Host: Set up a host.

CreateDefaultBuilder では次のものも読み込まれます。CreateDefaultBuilder also loads:

JSON 構成プロバイダーが最初に確立されます。The JSON Configuration Provider is established first. このため、ユーザー シークレット、環境変数、およびコマンド ライン引数によって、appsettings ファイルによって設定された構成がオーバーライドされます。Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

ホストのビルド時に ConfigureAppConfiguration を呼び出して、appsettings.jsonappsettings.{Environment}.json 以外のファイルにアプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddJsonFile(
                    "config.json", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("config.json", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

Example

サンプル アプリでは、静的な簡易メソッド CreateDefaultBuilder を利用してホストをビルドします。これには AddJsonFile の 2 回の呼び出しが含まれます。The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile. 構成は、appsettings.json および appsettings.{Environment}.json から読み込まれます。Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. サンプル アプリを実行します。Run the sample app. アプリに対して http://localhost:5000 でブラウザーを開きます。Open a browser to the app at http://localhost:5000.
  2. 出力に、環境に応じて、表に示す構成のキーと値のペアが含まれていることを観察します。Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. ログの構成キーでは、階層の区切り文字としてコロン (:) が使用されます。Logging configuration keys use the colon (:) as a hierarchical separator.
キーKey 開発時の値Development Value 運用時の値Production Value
Logging:LogLevel:SystemLogging:LogLevel:System 情報Information 情報Information
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft 情報Information 情報Information
Logging:LogLevel:DefaultLogging:LogLevel:Default デバッグDebug ErrorError
AllowedHostsAllowedHosts * *

XML 構成プロバイダーXML Configuration Provider

XmlConfigurationProvider では、実行時に XML ファイルのキーと値のペアから構成が読み込まれます。The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

XML ファイルの構成をアクティブにするには、ConfigurationBuilder のインスタンスの AddXmlFile 拡張メソッドを呼び出します。To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

オーバーロードによって次のものを指定できます。Overloads permit specifying:

  • ファイルを省略可能かどうか。Whether the file is optional.
  • ファイルが変更された場合に構成を再度読み込むかどうか。Whether the configuration is reloaded if the file changes.
  • ファイルにアクセスするために IFileProvider が使用されます。The IFileProvider used to access the file.

構成ファイルのルート ノードは、構成のキーと値のペアを作成するときには無視されます。The root node of the configuration file is ignored when the configuration key-value pairs are created. ファイル内でドキュメント型定義 (DTD) または名前空間を指定しないでください。Don't specify a Document Type Definition (DTD) or namespace in the file.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddXmlFile(
                    "config.xml", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddXmlFile("config.xml", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

XML 構成ファイルでは、繰り返しのセクション用に個別の要素名を使用できます。XML configuration files can use distinct element names for repeating sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section0>
    <key0>value</key0>
    <key1>value</key1>
  </section0>
  <section1>
    <key0>value</key0>
    <key1>value</key1>
  </section1>
</configuration>

前の構成ファイルでは、value を使用して次のキーが読み込まれます。The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

同じ要素名を使用する要素の繰り返しは、要素を区別するために name 属性を使用する場合に機能します。Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value</key>
    <key name="key1">value</key>
  </section>
  <section name="section1">
    <key name="key0">value</key>
    <key name="key1">value</key>
  </section>
</configuration>

前の構成ファイルでは、value を使用して次のキーが読み込まれます。The previous configuration file loads the following keys with value:

  • section:section0:key:key0section:section0:key:key0
  • section:section0:key:key1section:section0:key:key1
  • section:section1:key:key0section:section1:key:key0
  • section:section1:key:key1section:section1:key:key1

値を指定するために属性を使用できます。Attributes can be used to supply values:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

前の構成ファイルでは、value を使用して次のキーが読み込まれます。The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

ファイルごとのキーの構成プロバイダーKey-per-file Configuration Provider

KeyPerFileConfigurationProvider では、構成のキーと値のペアとしてディレクトリのファイルが使用されます。The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. キーはファイル名です。The key is the file name. 値にはファイルのコンテンツが含まれます。The value contains the file's contents. ファイルごとのキーの構成プロバイダーは、Docker ホスティングのシナリオで使用されます。The Key-per-file Configuration Provider is used in Docker hosting scenarios.

ファイルごとのキーの構成をアクティブにするには、ConfigurationBuilder のインスタンスの AddKeyPerFile 拡張メソッドを呼び出します。To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. ファイルに対する directoryPath は、絶対パスである必要があります。The directoryPath to the files must be an absolute path.

オーバーロードによって次のものを指定できます。Overloads permit specifying:

  • ソースを構成する Action<KeyPerFileConfigurationSource> デリゲート。An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • ディレクトリを省略可能かどうか、またディレクトリへのパス。Whether the directory is optional and the path to the directory.

アンダースコア 2 つ (__) は、ファイル名で構成キーの区切り記号として使用されます。The double-underscore (__) is used as a configuration key delimiter in file names. たとえば、ファイル名 Logging__LogLevel__System では、構成キー Logging:LogLevel:System が生成されます。For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                var path = Path.Combine(
                    Directory.GetCurrentDirectory(), "path/to/files");
                config.AddKeyPerFile(directoryPath: path, optional: true);
            })
            .UseStartup<Startup>();
}

基本パスは SetBasePath に設定されています。The base path is set with SetBasePath. SetBasePathMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.FileExtensions パッケージにあります。SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
var config = new ConfigurationBuilder()
    .AddKeyPerFile(directoryPath: path, optional: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

メモリ構成プロバイダーMemory Configuration Provider

MemoryConfigurationProvider では、構成のキーと値のペアとして、メモリ内コレクションが使用されます。The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

メモリ内コレクションの構成をアクティブにするには、ConfigurationBuilder のインスタンスの AddInMemoryCollection 拡張メソッドを呼び出します。To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

構成プロバイダーは、IEnumerable<KeyValuePair<String,String>> を使用して初期化できます。The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

ホストをビルドするときに ConfigureAppConfiguration を呼び出して、アプリの構成を指定します。Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static readonly Dictionary<string, string> _dict = 
        new Dictionary<string, string>
        {
            {"MemoryCollectionKey1", "value1"},
            {"MemoryCollectionKey2", "value2"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(_dict);
            })
            .UseStartup<Startup>();
}

WebHostBuilder を直接作成する場合、次の構成で UseConfiguration を呼び出します。When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

var config = new ConfigurationBuilder()
    .AddInMemoryCollection(dict)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

GetValueGetValue

ConfigurationBinder.GetValue<T> によって、指定したキーで構成から値が抽出され、それが指定した型に変換されます。ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the specified type. オーバーロードを使用すると、キーが見つからない場合に既定値を指定することができます。An overload permits you to provide a default value if the key isn't found.

次のような例です。The following example:

  • キー NumberKey の文字列値を構成から抽出します。Extracts the string value from configuration with the key NumberKey. NumberKey が構成キーに見つからない場合、既定値の 99 が使用されます。If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • 値の型は int です。Types the value as an int.
  • NumberConfig プロパティの値をページで使用するために格納します。Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

    public void OnGet()
    {
        NumberConfig = _config.GetValue<int>("NumberKey", 99);
    }
}

GetSection、GetChildren、ExistsGetSection, GetChildren, and Exists

以下の例では、次の JSON ファイルについて考えます。For the examples that follow, consider the following JSON file. 4 つのキーが 2 つのセクションに含まれています。そのうちの 1 つには、一組のサブセクションが含まれています。Four keys are found across two sections, one of which includes a pair of subsections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  },
  "section2": {
    "subsection0" : {
      "key0": "value",
      "key1": "value"
    },
    "subsection1" : {
      "key0": "value",
      "key1": "value"
    }
  }
}

ファイルが構成に読み取られると、次の一意の階層キーが作成され、構成値が保持されます。When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration values:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1
  • section2:subsection0:key0section2:subsection0:key0
  • section2:subsection0:key1section2:subsection0:key1
  • section2:subsection1:key0section2:subsection1:key0
  • section2:subsection1:key1section2:subsection1:key1

GetSectionGetSection

IConfiguration.GetSection では、指定したサブセクションのキーを持つ構成のサブセクションが抽出されます。IConfiguration.GetSection extracts a configuration subsection with the specified subsection key. GetSectionMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration パッケージにあります。GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

section1 のキーと値のペアのみを含む IConfigurationSection を返すには、GetSection を呼び出してセクション名を指定します。To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

var configSection = _config.GetSection("section1");

configSection には値はなく、キーとパスのみが含まれます。The configSection doesn't have a value, only a key and a path.

同様に、section2:subsection0 のキーの値を取得するには、GetSection を呼び出してセクションのパスを指定します。Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

var configSection = _config.GetSection("section2:subsection0");

GetSectionnull を返すことはありません。GetSection never returns null. 一致するセクションが見つからない場合は、空の IConfigurationSection が返されます。If a matching section isn't found, an empty IConfigurationSection is returned.

GetSection で一致するセクションが返されると、Value は設定されません。When GetSection returns a matching section, Value isn't populated. KeyPath はセクションが存在する場合に返されます。A Key and Path are returned when the section exists.

GetChildrenGetChildren

section2 での IConfiguration.GetChildren の呼び出しでは、次を含む IEnumerable<IConfigurationSection> が取得されます。A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

  • subsection0
  • subsection1
var configSection = _config.GetSection("section2");

var children = configSection.GetChildren();

既存Exists

ConfigurationExtensions.Exists を使用して、構成セクションが存在するかどうかを判断します。Use ConfigurationExtensions.Exists to determine if a configuration section exists:

var sectionExists = _config.GetSection("section2:subsection2").Exists();

例のデータの場合、構成データに section2:subsection2 セクションが存在しないため、sectionExistsfalse となります。Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

クラスにバインドするBind to a class

"オプション パターン" を使用して、関連する設定のグループを表すクラスに構成をバインドすることができます。Configuration can be bound to classes that represent groups of related settings using the options pattern. 詳細については、「ASP.NET Core のオプション パターン」を参照してください。For more information, see ASP.NET Core のオプション パターン.

構成値は文字列として返されますが、Bind を呼び出すことで POCO オブジェクトを構築できます。Configuration values are returned as strings, but calling Bind enables the construction of POCO objects. BindMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.Binder パッケージにあります。Bind is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage.

サンプル アプリには Starship モデル (Models/Starship.cs) が含まれます。The sample app contains a Starship model (Models/Starship.cs):

public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}

サンプル アプリが JSON 構成プロバイダーを使用して構成を読み込むときに、starship.json ファイルの starship セクションで構成が作成されます。The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

次の構成のキーと値のペアが作成されます。The following configuration key-value pairs are created:

キーKey [値]Value
starship:namestarship:name USS EnterpriseUSS Enterprise
starship:registrystarship:registry NCC-1701NCC-1701
starship:classstarship:class ConstitutionConstitution
starship:lengthstarship:length 304.8304.8
starship:commissionedstarship:commissioned FalseFalse
trademarktrademark Paramount Pictures Corp. http://www.paramount.comParamount Pictures Corp. http://www.paramount.com

サンプル アプリは starship キーを使用して GetSection を呼び出します。The sample app calls GetSection with the starship key. starship のキーと値のペアは分離されます。The starship key-value pairs are isolated. Starship クラスのインスタンスを渡すサブセクションで、Bind メソッドが呼び出されます。The Bind method is called on the subsection passing in an instance of the Starship class. インスタンスの値をバインドした後、インスタンスがレンダリング用のプロパティに割り当てられます。After binding the instance values, the instance is assigned to a property for rendering:

var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

GetSectionMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration パッケージにあります。GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

オブジェクト グラフにバインドするBind to an object graph

Bind では、POCO オブジェクト グラフ全体をバインドすることができます。Bind is capable of binding an entire POCO object graph. BindMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.Binder パッケージにあります。Bind is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage.

サンプルには、オブジェクト グラフに Metadata クラスと Actors クラスが含まれる TvShow モデルが含まれます (Models/TvShow.cs)。The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}

サンプル アプリには、構成データを含む tvshow.xml ファイルが含まれます。The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>

構成は、Bind メソッドを使用して、TvShow オブジェクト グラフ全体にバインドされます。Configuration is bound to the entire TvShow object graph with the Bind method. バインドされたインスタンスは、表示のためにプロパティに割り当てられます。The bound instance is assigned to a property for rendering:

var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

ConfigurationBinder.Get<T> によってバインドされ、指定した型が返されます。ConfigurationBinder.Get<T> binds and returns the specified type. Get<T>Bind を使用するよりも便利です。Get<T> is more convenient than using Bind. 次のコードは、前の例と共に Get<T> を使用する方法を示しています。これにより、バインドされたインスタンスを、表示用に使用するプロパティに直接割り当てることができます。The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be directly assigned to the property used for rendering:

TvShow = _config.GetSection("tvshow").Get<TvShow>();

GetMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.Binder パッケージにあります。Get is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage. Get<T> は、ASP.NET Core 1.1 以降で使用できます。Get<T> is available in ASP.NET Core 1.1 or later. GetSectionMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration パッケージにあります。GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

配列をクラスにバインドするBind an array to a class

サンプル アプリは、このセクションで説明する概念を示しています。The sample app demonstrates the concepts explained in this section.

Bind は、構成キーで配列インデックスを使用して、オブジェクトに対する配列のバインドをサポートしています。The Bind supports binding arrays to objects using array indices in configuration keys. 数値のキー セグメント (:0::1:、… :{n}:) を公開する配列形式は、すべて POCO クラスの配列にバインドできます。Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array. BindMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration.Binder パッケージにあります。`Bind`` is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage.

注意

バインドは慣例に従って指定されます。Binding is provided by convention. カスタム構成プロバイダーが配列のバインドを実装する必要はありません。Custom configuration providers aren't required to implement array binding.

メモリ内配列の処理In-memory array processing

次の表に示す構成のキーと値について考えます。Consider the configuration keys and values shown in the following table.

キーKey [値]Value
配列:エントリ:0array:entries:0 value0value0
配列:エントリ:1array:entries:1 value1value1
配列:エントリ:2array:entries:2 value2value2
配列:エントリ:4array:entries:4 value4value4
配列:エントリ:5array:entries:5 value5value5

これらのキーと値は、メモリ構成プロバイダーを使用してサンプル アプリに読み込まれます。These keys and values are loaded in the sample app using the Memory Configuration Provider:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

配列は、インデックス #3 の値をスキップします。The array skips a value for index #3. 構成バインダーは、null 値をバインドしたり、バインドされたオブジェクトに null エントリを作成したりすることはできません。このことは、この配列をオブジェクトにバインドした結果によって明らかになります。The configuration binder isn't capable of binding null values or creating null entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is demonstrated.

サンプル アプリでは、バインドされた構成データを保持するために POCO クラスを使用できます。In the sample app, a POCO class is available to hold the bound configuration data:

public class ArrayExample
{
    public string[] Entries { get; set; }
}

構成データはオブジェクトにバインドされます。The configuration data is bound to the object:

var arrayExample = new ArrayExample();
_config.GetSection("array").Bind(arrayExample);

GetSectionMicrosoft.AspNetCore.App メタパッケージ内の Microsoft.Extensions.Configuration パッケージにあります。GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

また、ConfigurationBinder.Get<T> 構文を使用して、コードをよりコンパクトにすることもできます。ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

ArrayExample = _config.GetSection("array").Get<ArrayExample>();

バインドされたオブジェクト (ArrayExample のインスタンス) は、構成から配列データを受け取ります。The bound object, an instance of ArrayExample, receives the array data from configuration.

ArrayExample.Entries インデックスArrayExample.Entries Index ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

バインドされたオブジェクトのインデックス #3 によって、array:4 構成キーの構成データと、その値 value4 が保持されます。Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. 配列を含む構成データがバインドされると、構成キーの配列のインデックスは、オブジェクトを作成するときに構成データを反復処理するためだけに使用されます。When configuration data containing an array is bound, the array indices in the configuration keys are merely used to iterate the configuration data when creating the object. 構成データに null 値を保持することはできません。また、構成キーの配列が 1 つまたは複数のインデックスをスキップしても、バインドされたオブジェクトに null 値のエントリは作成されません。A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.

インデックス #3 の不足している構成項目は、ArrayExample インスタンスにバインドする前に、構成で適切なキーと値のペアを生成する構成プロバイダーによって指定できます。The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that produces the correct key-value pair in configuration. 不足しているキーと値のペアを含む JSON 構成プロバイダーがサンプルに含まれる場合、ArrayExample.Entries は完全な構成の配列と一致します。If the sample included an additional JSON Configuration Provider with the missing key-value pair, the ArrayExample.Entries matches the complete configuration array:

missing_value.json:missing_value.json:

{
  "array:entries:3": "value3"
}

ConfigureAppConfigurationの場合:In ConfigureAppConfiguration:

config.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);

表に示すキーと値のペアが構成に読み込まれます。The key-value pair shown in the table is loaded into configuration.

キーKey [値]Value
array:entries:3array:entries:3 value3value3

JSON 構成プロバイダーにインデックス #3 のエントリが含まれた後に ArrayExample クラスのインスタンスがバインドされる場合、ArrayExample.Entries 配列に値が含まれます。If the ArrayExample class instance is bound after the JSON Configuration Provider includes the entry for index #3, the ArrayExample.Entries array includes the value.

ArrayExample.Entries インデックスArrayExample.Entries Index ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

JSON 配列の処理JSON array processing

JSON ファイルに配列が含まれる場合、配列要素の構成キーは、0 から始まるセクションのインデックスで作成されます。If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. 次の構成ファイルにおいて、subsection は配列です。In the following configuration file, subsection is an array:

{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}

JSON 構成プロバイダーは、次のキーと値のペアに構成データを読み取ります。The JSON Configuration Provider reads the configuration data into the following key-value pairs:

キーKey [値]Value
json_array:keyjson_array:key valueAvalueA
json_array:subsection:0json_array:subsection:0 valueBvalueB
json_array:subsection:1json_array:subsection:1 valueCvalueC
json_array:subsection:2json_array:subsection:2 valueDvalueD

サンプル アプリでは、構成のキーと値のペアをバインドするために、次の POCO クラスを使用できます。In the sample app, the following POCO class is available to bind the configuration key-value pairs:

public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

バインド後、JsonArrayExample.Key は値 valueA を保持します。After binding, JsonArrayExample.Key holds the value valueA. サブセクションの値は、POCO 配列のプロパティ Subsection に格納されます。The subsection values are stored in the POCO array property, Subsection.

JsonArrayExample.Subsection インデックスJsonArrayExample.Subsection Index JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

カスタム構成プロバイダーCustom configuration provider

サンプル アプリでは、Entity Framework (EF) を使用してデータベースから構成のキーと値のペアを読み取る、基本的な構成プロバイダーを作成する方法を示します。The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

プロバイダーの特徴は次のとおりです。The provider has the following characteristics:

  • EF のメモリ内データベースは、デモンストレーションのために使用されます。The EF in-memory database is used for demonstration purposes. 接続文字列を必要とするデータベースを使用するには、第 2 の ConfigurationBuilder を実装して、別の構成プロバイダーからの接続文字列を指定します。To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • プロバイダーは、起動時に、構成にデータベース テーブルを読み取ります。The provider reads a database table into configuration at startup. プロバイダーは、キー単位でデータベースを照会しません。The provider doesn't query the database on a per-key basis.
  • 変更時に再度読み込む機能は実装されていません。このため、アプリの起動後にデータベースを更新しても、アプリの構成には影響がありません。Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

データベースに構成値を格納するための EFConfigurationValue エンティティを定義します。Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

構成した値を格納し、その値にアクセスするための EFConfigurationContext を追加します。Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values { get; set; }
}

IConfigurationSource を実装するクラスを作成します。Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
    {
        _optionsAction = optionsAction;
    }

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

ConfigurationProvider から継承して、カスタム構成プロバイダーを作成します。Create the custom configuration provider by inheriting from ConfigurationProvider. データベースが空だった場合、構成プロバイダーはこれを初期化します。The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        var configValues = new Dictionary<string, string>
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue 
                {
                    Id = kvp.Key,
                    Value = kvp.Value
                })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

AddEFConfiguration 拡張メソッドを使用すると、ConfigurationBuilder に構成ソースを追加できます。An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

次のコードでは、Program.cs でカスタムの EFConfigurationProvider を使用する方法を示します。The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

起動中に構成にアクセスするAccess configuration during startup

Startup コンストラクターに IConfiguration を挿入して、Startup.ConfigureServices で構成値にアクセスします。Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Startup.Configure で構成にアクセスするには、メソッドに直接 IConfiguration を挿入するか、コンストラクターからのインスタンスを使用します。To access configuration in Startup.Configure, either inject IConfiguration directly into the method or use the instance from the constructor:

public class Startup
{
    private readonly IConfiguration _config;

    public Startup(IConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var value = _config["key"];
    }

    public void Configure(IApplicationBuilder app, IConfiguration config)
    {
        var value = config["key"];
    }
}

起動時の簡易メソッドを使用して構成にアクセスする例については、アプリ起動時の簡易メソッドに関連する記事をご覧ください。For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Razor Pages ページまたは MVC ビューで構成にアクセスするAccess configuration in a Razor Pages page or MVC view

Razor Pages ページまたは MVC ビューで構成設定にアクセスするには、Microsoft.Extensions.Configuration 名前空間using ディレクティブ (C# リファレンス: using ディレクティブ) を追加して、IConfiguration をページまたはビューに挿入します。To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

Razor ページ:In a Razor Pages page:

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

MVC ビュー:In an MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index View</title>
</head>
<body>
    <h1>Access configuration in an MVC view</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

外部アセンブリから構成を追加するAdd configuration from an external assembly

IHostingStartup の実装により、アプリの Startup クラスの外部にある外部アセンブリから、起動時に拡張機能をアプリに追加できるようになります。An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. 詳細については、「ASP.NET Core でホスティング スタートアップ アセンブリを使用する」を参照してください。For more information, see ASP.NET Core でホスティング スタートアップ アセンブリを使用する.

その他の技術情報Additional resources