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

作成者: Rick AndersonMark MichaelisSteve SmithDaniel RothLuke LathamBy Rick Anderson, Mark Michaelis, Steve Smith, Daniel Roth, and Luke Latham

構成 API は、名前と値のペアのリストに基づく ASP.NET Core Web アプリの構成方法を提供します。The Configuration API provides a way to configure an ASP.NET Core web app based on a list of name-value pairs. 構成は実行時に複数のソースから読み取られます。Configuration is read at runtime from multiple sources. 名前と値の組は、複数レベルの階層にグループ化することができます。Name-value pairs can be grouped into a multi-level hierarchy.

以下の構成プロバイダーがあります。There are configuration providers for:

  • ファイル形式 (INI、JSON、および XML)。File formats (INI, JSON, and XML).
  • コマンド ライン引数。Command-line arguments.
  • 環境変数。Environment variables.
  • メモリ内 .NET オブジェクト。In-memory .NET objects.
  • 暗号化されていないシークレット マネージャーの記憶域。The unencrypted Secret Manager storage.
  • Azure Key Vault などの暗号化されたユーザー ストア。An encrypted user store, such as Azure Key Vault.
  • カスタム プロバイダー (インストール済みまたは作成済み)。Custom providers (installed or created).

各構成値は文字列キーにマップされます。Each configuration value maps to a string key. 設定をカスタム POCO オブジェクト (プロパティを持つ単純な .NET クラス) に逆シリアル化するための組み込みのバインド サポートがあります。There's built-in binding support to deserialize settings into a custom POCO object (a simple .NET class with properties).

オプション パターンではオプション クラスを使用して、関連する設定のグループを表します。The options pattern uses options classes to represent groups of related settings. オプション パターンの使用の詳細については、「オプション」トピックを参照してください。For more information on using the options pattern, see the Options topic.

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

JSON 構成JSON configuration

次のコンソール アプリでは JSON 構成プロバイダーを使用します。The following console app uses the JSON configuration provider:

using System;
using System.IO;
// Requires NuGet package
// Microsoft.Extensions.Configuration.Json
using Microsoft.Extensions.Configuration;

public class Program
{
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        Configuration = builder.Build();

        Console.WriteLine($"option1 = {Configuration["Option1"]}");
        Console.WriteLine($"option2 = {Configuration["option2"]}");
        Console.WriteLine(
            $"suboption1 = {Configuration["subsection:suboption1"]}");
        Console.WriteLine();

        Console.WriteLine("Wizards:");
        Console.Write($"{Configuration["wizards:0:Name"]}, ");
        Console.WriteLine($"age {Configuration["wizards:0:Age"]}");
        Console.Write($"{Configuration["wizards:1:Name"]}, ");
        Console.WriteLine($"age {Configuration["wizards:1:Age"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

アプリは以下の構成設定を読み取り、表示します。The app reads and displays the following configuration settings:

{
  "option1": "value1_from_json",
  "option2": 2,

  "subsection": {
    "suboption1": "subvalue1_from_json"
  },
  "wizards": [
    {
      "Name": "Gandalf",
      "Age": "1000"
    },
    {
      "Name": "Harry",
      "Age": "17"
    }
  ]
}

構成は、コロン (:) で区切られたノードの名前と値のペアの階層リストで構成されます。Configuration consists of a hierarchical list of name-value pairs in which the nodes are separated by a colon (:). 値を取得するには、対応する項目のキーを使用して Configuration インデクサーにアクセスします。To retrieve a value, access the Configuration indexer with the corresponding item's key:

Console.WriteLine(
    $"suboption1 = {Configuration["subsection:suboption1"]}");

JSON 形式の構成ソースの配列を操作する場合は、コロンで区切られた文字列の一部として配列インデックスを使用します。To work with arrays in JSON-formatted configuration sources, use an array index as part of the colon-separated string. 次の例では、上記の wizards 配列の最初の項目の名前を取得します。The following example gets the name of the first item in the preceding wizards array:

Console.Write($"{Configuration["wizards:0:Name"]}");
// Output: Gandalf

組み込みの構成プロバイダーに書き込まれた名前と値のペアは永続化されませんName-value pairs written to the built-in Configuration providers are not persisted. ただし、値を保存するカスタム プロバイダーを作成することができます。However, a custom provider that saves values can be created. カスタム構成プロバイダーに関する記述を参照してください。See custom configuration provider.

上記のサンプルでは、構成インデクサーを使用して値を読み取ります。The preceding sample uses the configuration indexer to read values. Startup の外部の構成にアクセスする場合は、オプション パターンを使用します。To access configuration outside of Startup, use the options pattern. 詳細については、「オプション」トピックを参照してください。For more information, see the Options topic.

XML 構成XML configuration

XML 形式の構成ソースの配列を操作するには、各要素に name インデックスを指定します。To work with arrays in XML-formatted configuration sources, provide a name index to each element. インデックスを使用して値にアクセスします。Use the index to access the values:

<wizards>
  <wizard name="Gandalf">
    <age>1000</age>
  </wizard>
  <wizard name="Harry">
    <age>17</age>
  </wizard>
</wizards>
Console.Write($"{Configuration["wizard:Harry:age"]}");
// Output: 17

環境別の構成Configuration by environment

開発、テスト、運用などの異なる環境に応じて異なる構成を設定するのが一般的です。It's typical to have different configuration settings for different environments, for example, development, testing, and production. ASP.NET Core 2.x アプリの CreateDefaultBuilder 拡張メソッド (ASP.NET Core 1.x アプリの場合は、AddJsonFile および AddEnvironmentVariables を直接使用) では、JSON ファイルとシステム構成ソースを読み取るために構成プロバイダーを追加します。The CreateDefaultBuilder extension method in an ASP.NET Core 2.x app (or using AddJsonFile and AddEnvironmentVariables directly in an ASP.NET Core 1.x app) adds configuration providers for reading JSON files and system configuration sources:

  • appsettings.jsonappsettings.json
  • appsettings.<EnvironmentName>.jsonappsettings.<EnvironmentName>.json
  • 環境変数Environment variables

ASP.NET Core 1.x アプリは、AddJsonFile および AddEnvironmentVariables を呼び出す必要があります。ASP.NET Core 1.x apps need to call AddJsonFile and AddEnvironmentVariables.

パラメーターの説明については、「AddJsonFile」を参照してください。See AddJsonFile for an explanation of the parameters. reloadOnChange は、ASP.NET Core 1.1 以降でのみサポートされます。reloadOnChange is only supported in ASP.NET Core 1.1 and later.

構成ソースは指定された順に読み取られます。Configuration sources are read in the order that they're specified. 先のコードでは、環境変数が最後に読み取られます。In the preceding code, the environment variables are read last. 環境を使用して設定された構成値で、2 つの前述のプロバイダーで設定された値が置き換えられます。Any configuration values set through the environment replace those set in the two previous providers.

次の appsettings.Staging.json ファイルをご覧ください。Consider the following appsettings.Staging.json file:

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "MyConfig": "My Config Value for staging."
}

次のコードで、ConfigureMyConfig の値を読み取ります。In the following code, Configure reads the value of MyConfig:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var myConfig = Configuration["MyConfig"];
    // use myConfig
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseBrowserLink();
    }

    if (env.IsProduction() || env.IsStaging())
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseMvcWithDefaultRoute();
}

通常、環境は DevelopmentStaging、または Production に設定されます。The environment is typically set to Development, Staging, or Production. 詳細については、「Use multiple environments」(複数の環境の使用) を参照してください。For more information, see Use multiple environments.

構成に関する考慮事項:Configuration considerations:

  • IOptionsSnapshot では、構成データを変更時に再読み込みできます。IOptionsSnapshot can reload configuration data when it changes.
  • 構成キーでは大文字と小文字が区別されませんConfiguration keys are not case-sensitive.
  • 構成プロバイダー コードやプレーンテキストの構成ファイルには、パスワードなどの機密データは格納しないでください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 safe storage of app secrets in development.
  • 環境変数で指定された階層の構成値では、コロン (:) が一部のプラットフォームで動作しない可能性があります。For hierarchical config values specified in environment variables, a colon (:) may not work on all platforms. 二重のアンダースコア (__) はすべてのプラットフォームでサポートされています。Double underscore (__) is supported by all platforms.
  • 構成 API とやり取りするときは、コロン (:) がすべてのプラットフォームで動作します。When interacting with the configuration API, a colon (:) works on all platforms.

メモリ内プロバイダーと POCO クラスへのバインディングIn-memory provider and binding to a POCO class

次の例では、メモリ内プロバイダーを使用して、クラスにバインドする方法を示します。The following sample shows how to use the in-memory provider and bind to a class:

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

public class Program
{   
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "Rick"},
                {"App:MainWindow:Height", "11"},
                {"App:MainWindow:Width", "11"},
                {"App:MainWindow:Top", "11"},
                {"App:MainWindow:Left", "11"}
            };

        var builder = new ConfigurationBuilder();
        builder.AddInMemoryCollection(dict);

        Configuration = builder.Build();

        Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");

        var window = new MyWindow();
        // Bind requrires NuGet package
        // Microsoft.Extensions.Configuration.Binder
        Configuration.GetSection("App:MainWindow").Bind(window);
        Console.WriteLine($"Left {window.Left}");
        Console.WriteLine();

        Console.WriteLine("Press any key...");
        Console.ReadKey();
    }
}

public class MyWindow
{
    public int Height { get; set; }
    public int Width { get; set; }
    public int Top { get; set; }
    public int Left { get; set; }
}

構成値は文字列として返されますが、バインディングすることでプロジェクトを構築できます。Configuration values are returned as strings, but binding enables the construction of objects. バインディングすることで POCO オブジェクトや、オブジェクト グラフ全体を取得できます。Binding allows the retrieval of POCO objects or even entire object graphs.

GetValueGetValue

次の例では、GetValue<T> 拡張メソッドを示します。The following sample demonstrates the GetValue<T> extension method:

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

public class Program
{   
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "Rick"},
                {"App:MainWindow:Height", "11"},
                {"App:MainWindow:Width", "11"},
                {"App:MainWindow:Top", "11"},
                {"App:MainWindow:Left", "11"}
            };

        var builder = new ConfigurationBuilder();
        builder.AddInMemoryCollection(dict);

        Configuration = builder.Build();

        Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");

        // Show GetValue overload and set the default value to 80
        // Requires NuGet package "Microsoft.Extensions.Configuration.Binder"
        var left = Configuration.GetValue<int>("App:MainWindow:Left", 80);
        Console.WriteLine($"Left {left}");

        var window = new MyWindow();
        Configuration.GetSection("App:MainWindow").Bind(window);
        Console.WriteLine($"Left {window.Left}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

public class MyWindow
{
    public int Height { get; set; }
    public int Width { get; set; }
    public int Top { get; set; }
    public int Left { get; set; }
}

ConfigurationBinder の GetValue<T> メソッドでは、既定値 (サンプルでは 80) を指定できます。The ConfigurationBinder's GetValue<T> method allows the specification of a default value (80 in the sample). GetValue<T> は単純なシナリオ用であり、セクション全体にはバインドされません。GetValue<T> is for simple scenarios and doesn't bind to entire sections. GetValue<T> は、特定の型に変換された GetSection(key).Value からスカラー値を取得します。GetValue<T> obtains scalar values from GetSection(key).Value converted to a specific type.

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

クラス内の各オブジェクトに再帰的にバインドすることができます。Each object in a class can be recursively bound. 次の AppSettings クラスがあるとします。Consider the following AppSettings class:

public class AppSettings
{
    public Window Window { get; set; }
    public Connection Connection { get; set; }
    public Profile Profile { get; set; }
}

public class Window
{
    public int Height { get; set; }
    public int Width { get; set; }
}

public class Connection
{
    public string Value { get; set; }
}

public class Profile
{
    public string Machine { get; set; }
}

次のサンプルでは AppSettings クラスにバインドします。The following sample binds to the AppSettings class:

using System;
using System.IO;
using Microsoft.Extensions.Configuration;

public class Program
{
    public static void Main(string[] args = null)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        var config = builder.Build();

        var appConfig = new AppSettings();
        config.GetSection("App").Bind(appConfig);

        Console.WriteLine($"Height {appConfig.Window.Height}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

ASP.NET Core 1.1 以上では、セクション全体を操作する Get<T> を使用できます。ASP.NET Core 1.1 and higher can use Get<T>, which works with entire sections. Get<T>Bind を使用するよりも便利な場合があります。Get<T> can be more convenient than using Bind. 次のコードでは、上記のサンプルで Get<T> を使用する方法を示します。The following code shows how to use Get<T> with the preceding sample:

var appConfig = config.GetSection("App").Get<AppSettings>();

以下の appsettings.json ファイルを使用します。Using the following appsettings.json file:

{
  "App": {
    "Profile": {
      "Machine": "Rick"
    },
    "Connection": {
      "Value": "connectionstring"
    },
    "Window": {
      "Height": "11",
      "Width": "11"
    }
  }
}

プログラムは Height 11 を表示します。The program displays Height 11.

次のコードを使用して、構成の単体テストを行うことができます。The following code can be used to unit test the configuration:

[Fact]
public void CanBindObjectTree()
{
    var dict = new Dictionary<string, string>
        {
            {"App:Profile:Machine", "Rick"},
            {"App:Connection:Value", "connectionstring"},
            {"App:Window:Height", "11"},
            {"App:Window:Width", "11"}
        };
    var builder = new ConfigurationBuilder();
    builder.AddInMemoryCollection(dict);
    var config = builder.Build();

    var settings = new AppSettings();
    config.GetSection("App").Bind(settings);

    Assert.Equal("Rick", settings.Profile.Machine);
    Assert.Equal(11, settings.Window.Height);
    Assert.Equal(11, settings.Window.Width);
    Assert.Equal("connectionstring", settings.Connection.Value);
}

Entity Framework のカスタム プロバイダーを作成するCreate an Entity Framework custom provider

このセクションでは、EF を使用してデータベースから名前と値のペアを読み取る基本的な構成プロバイダーが作成されます。In this section, a basic configuration provider that reads name-value pairs from a database using EF is created.

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

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

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

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

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

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

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public class EFConfigSource : IConfigurationSource
    {
        private readonly Action<DbContextOptionsBuilder> _optionsAction;

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

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

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

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

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

        Action<DbContextOptionsBuilder> OptionsAction { get; }

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

            using (var dbContext = new ConfigurationContext(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(
            ConfigurationContext dbContext)
        {
            var configValues = new Dictionary<string, string>
                {
                    { "key1", "value_from_ef_1" },
                    { "key2", "value_from_ef_2" }
                };
            dbContext.Values.AddRange(configValues
                .Select(kvp => new ConfigurationValue { Id = kvp.Key, Value = kvp.Value })
                .ToArray());
            dbContext.SaveChanges();
            return configValues;
        }
    }
}

サンプルを実行すると、データベースからの強調表示された値 ("value_from_ef_1" および "value_from_ef_2") が表示されます。The highlighted values from the database ("value_from_ef_1" and "value_from_ef_2") are displayed when the sample is run.

構成ソースを追加するための EFConfigSource 拡張メソッドを使用できます。An EFConfigSource extension method for adding the configuration source can be used:

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public static class EntityFrameworkExtensions
    {
        public static IConfigurationBuilder AddEntityFrameworkConfig(
            this IConfigurationBuilder builder, Action<DbContextOptionsBuilder> setup)
        {
            return builder.Add(new EFConfigSource(setup));
        }
    }
}

次のコードに、カスタム EFConfigProvider の使用方法を示します。The following code shows how to use the custom EFConfigProvider:

using System;
using System.IO;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using CustomConfigurationProvider;

public static class Program
{
    public static void Main()
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        var connectionStringConfig = builder.Build();

        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            // Add "appsettings.json" to bootstrap EF config.
            .AddJsonFile("appsettings.json")
            // Add the EF configuration provider, which will override any
            // config made with the JSON provider.
            .AddEntityFrameworkConfig(options =>
                options.UseSqlServer(connectionStringConfig.GetConnectionString(
                    "DefaultConnection"))
            )
            .Build();

        Console.WriteLine("key1={0}", config["key1"]);
        Console.WriteLine("key2={0}", config["key2"]);
        Console.WriteLine("key3={0}", config["key3"]);
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

サンプルでは JSON プロバイダーの後にカスタム EFConfigProvider を追加するため、データベースからのすべての設定で appsettings.json ファイルからの設定がオーバーライドされることに注意してください。Note the sample adds the custom EFConfigProvider after the JSON provider, so any settings from the database will override settings from the appsettings.json file.

以下の appsettings.json ファイルを使用します。Using the following appsettings.json file:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=CustomConfigurationProvider;Trusted_Connection=True;MultipleActiveResultSets=true"
  },
  "key1": "value_from_json_1",
  "key2": "value_from_json_2",
  "key3": "value_from_json_3"
}

次のような出力が表示されます。The following output is displayed:

key1=value_from_ef_1
key2=value_from_ef_2
key3=value_from_json_3

CommandLine 構成プロバイダーCommandLine configuration provider

CommandLine 構成プロバイダーは、実行時に構成するコマンドライン引数のキーと値のペアを受け取ります。The CommandLine configuration provider receives command-line argument key-value pairs for configuration at runtime.

CommandLine 構成サンプルを表示またはダウンロードするView or download the CommandLine configuration sample

CommandLine 構成プロバイダーをセットアップして使用するSetup and use the CommandLine configuration provider

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

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Configuration;

public class Program
{
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "MairaPC"},
                {"App:MainWindow:Left", "1980"}
            };

        var builder = new ConfigurationBuilder();

        builder.AddInMemoryCollection(dict)
            .AddCommandLine(args);

        Configuration = builder.Build();

        Console.WriteLine($"MachineName: {Configuration["Profile:MachineName"]}");
        Console.WriteLine($"Left: {Configuration["App:MainWindow:Left"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

コードを実行すると、次のような出力が表示されます。Running the code, the following output is displayed:

MachineName: MairaPC
Left: 1980

コマンド ラインで引数のキーと値のペアを渡すと、Profile:MachineNameApp:MainWindow:Left の値が変更されます。Passing argument key-value pairs on the command line changes the values of Profile:MachineName and App:MainWindow:Left:

dotnet run Profile:MachineName=BartPC App:MainWindow:Left=1979

コンソール ウィンドウには次のように表示されます。The console window displays:

MachineName: BartPC
Left: 1979

他の構成プロバイダーによって提供された構成をコマンドライン構成でオーバーライドするには、ConfigurationBuilder で最後に AddCommandLine を呼び出します。To override configuration provided by other configuration providers with command-line configuration, call AddCommandLine last on ConfigurationBuilder:

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

引数Arguments

コマンド ラインで渡される引数は、次の表に示すように 2 つの形式のいずれかに準拠する必要があります。Arguments passed on the command line must conform to one of two formats shown in the following table:

引数の形式Argument format Example
単一引数: 等号 (=) で区切られたキーと値のペアSingle argument: a key-value pair separated by an equals sign (=) key1=value
2 つの引数のシーケンス: スペースで区切られたキーと値のペアSequence of two arguments: a key-value pair separated by a space /key1 value1

単一引数Single argument

値は等号 (=) の後に配置する必要があります。The value must follow an equals sign (=). 値を null にすることができます (例: mykey=)。The value can be null (for example, mykey=).

キーにはプレフィックスが付く場合があります。The key may have a prefix.

キーのプレフィックスKey prefix Example
プレフィックスなしNo prefix key1=value1
単一のダッシュ (-)†Single dash (-)† -key2=value2
2 つのダッシュ (--)Two dashes (--) --key3=value3
スラッシュ (/)Forward slash (/) /key4=value4

†単一のダッシュ プレフィックス (-) が付いたキーは、スイッチ マッピングで指定する必要があります (以下を参照)。†A key with a single dash prefix (-) must be provided in switch mappings, described below.

コマンド例:Example command:

dotnet run key1=value1 -key2=value2 --key3=value3 /key4=value4

注: -key2 が構成プロバイダーに指定されたスイッチ マッピングに表示されていない場合は、FormatException がスローされます。Note: If -key2 isn't present in the switch mappings given to the configuration provider, a FormatException is thrown.

2 つの引数のシーケンスSequence of two arguments

値を null にすることはできません。値はスペースで区切られたキーの後に配置する必要があります。The value can't be null and must follow the key separated by a space.

キーにはプレフィックスを付ける必要があります。The key must have a prefix.

キーのプレフィックスKey prefix Example
単一のダッシュ (-)†Single dash (-)† -key1 value1
2 つのダッシュ (--)Two dashes (--) --key2 value2
スラッシュ (/)Forward slash (/) /key3 value3

†単一のダッシュ プレフィックス (-) が付いたキーは、スイッチ マッピングで指定する必要があります (以下を参照)。†A key with a single dash prefix (-) must be provided in switch mappings, described below.

コマンド例:Example command:

dotnet run -key1 value1 --key2 value2 /key3 value3

注: -key1 が構成プロバイダーに指定されたスイッチ マッピングに表示されていない場合は、FormatException がスローされます。Note: If -key1 isn't present in the switch mappings given to the configuration provider, a FormatException is thrown.

重複キーDuplicate keys

重複キーが指定されている場合は、最後のキーと値のペアが使用されます。If duplicate keys are provided, the last key-value pair is used.

スイッチ マッピングSwitch mappings

ConfigurationBuilder を使用して構成を手動でビルドする場合、スイッチ マッピング ディクショナリを AddCommandLine メソッドに追加できます。When manually building configuration with ConfigurationBuilder, a switch mappings dictionary can be added to the AddCommandLine method. スイッチ マッピングでは、キー名の交換ロジックが許可されます。Switch mappings allow key name replacement logic.

スイッチ マッピング ディクショナリが使用されている場合、そのディレクトリで、コマンドライン引数によって指定されたキーと一致するキーが確認されます。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 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.

以下の例では、GetSwitchMappings メソッドを使用します。これにより、コマンドライン引数で単一ダッシュ (-) キー プレフィックスを使用でき、先頭にサブキーのプレフィックスが付かないようにすることができます。In the following example, the GetSwitchMappings method allows command-line arguments to use a single dash (-) key prefix and avoid leading subkey prefixes.

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Configuration;

public class Program
{
    public static IConfiguration Configuration { get; set; }

    public static Dictionary<string, string> GetSwitchMappings(
        IReadOnlyDictionary<string, string> configurationStrings)
    {
        return configurationStrings.Select(item =>
            new KeyValuePair<string, string>(
                "-" + item.Key.Substring(item.Key.LastIndexOf(':') + 1),
                item.Key))
                .ToDictionary(
                    item => item.Key, item => item.Value);
    }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "RickPC"},
                {"App:MainWindow:Left", "1980"}
            };

        var builder = new ConfigurationBuilder();

        builder.AddInMemoryCollection(dict)
            .AddCommandLine(args, GetSwitchMappings(dict));

        Configuration = builder.Build();

        Console.WriteLine($"MachineName: {Configuration["Profile:MachineName"]}");
        Console.WriteLine($"Left: {Configuration["App:MainWindow:Left"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

コマンドライン引数を指定しないと、AddInMemoryCollection に指定されたディクショナリで構成値が設定されます。Without providing command-line arguments, the dictionary provided to AddInMemoryCollection sets the configuration values. 次のコマンドでアプリを実行します。Run the app with the following command:

dotnet run

コンソール ウィンドウには次のように表示されます。The console window displays:

MachineName: RickPC
Left: 1980

構成設定を渡す場合は、以下のコマンドを使用します。Use the following to pass in configuration settings:

dotnet run /Profile:MachineName=DahliaPC /App:MainWindow:Left=1984

コンソール ウィンドウには次のように表示されます。The console window displays:

MachineName: DahliaPC
Left: 1984

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

キーKey [値]Value
-MachineName Profile:MachineName
-Left App:MainWindow:Left

ディクショナリを使用してキーの切り替えを示すために、以下のコマンドを実行します。To demonstrate key switching using the dictionary, run the following command:

dotnet run -MachineName=ChadPC -Left=1988

コマンドライン キーが交換されます。The command-line keys are swapped. コンソール ウィンドウに、Profile:MachineNameApp:MainWindow:Left の構成値が表示されます。The console window displays the configuration values for Profile:MachineName and App:MainWindow:Left:

MachineName: ChadPC
Left: 1988

web.config ファイルweb.config file

IIS または IIS-Express でアプリをホストする場合は、web.config ファイルが必要です。A web.config file is required when hosting the app in IIS or IIS Express. web.config を設定することで、ASP.NET Core Module を有効にし、アプリを起動して他の IIS 設定とモジュールを構成することができます。Settings in web.config enable the ASP.NET Core Module to launch the app and configure other IIS settings and modules. web.config ファイルが存在せず、プロジェクト ファイルに <Project Sdk="Microsoft.NET.Sdk.Web"> が含まれている場合、プロジェクトを発行すると、発行先 (publish フォルダー) に web.config ファイルが作成されます。If the web.config file isn't present and the project file includes <Project Sdk="Microsoft.NET.Sdk.Web">, publishing the project creates a web.config file in the published output (the publish folder). 詳細については、「IIS を使用した Windows での ASP.NET Core のホスト」を参照してください。For more information, see Host ASP.NET Core on Windows with IIS.

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

起動中に ConfigureServices または Configure 内の構成にアクセスするには、アプリケーションの起動に関するトピックに示されている例を参照してください。To access configuration within ConfigureServices or Configure during startup, see the examples in the Application startup topic.

外部アセンブリからの構成の追加Adding 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. 詳細については、「Enhance an app from an external assembly」(外部アセンブリからアプリを拡張する) を参照してください。For more information, see Enhance an app from an external assembly.

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

Razor ページまたは 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[&quot;key&quot;]: @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[&quot;key&quot;]: @Configuration["key"]</p>
</body>
</html>

補足メモAdditional notes

  • 依存関係挿入 (DI) は、ConfigureServices が呼び出されるまでセットアップされません。Dependency Injection (DI) isn't set up until after ConfigureServices is invoked.
  • 構成システムは DI に対応していません。The configuration system isn't DI aware.
  • IConfiguration には次の 2 つ特性があります。IConfiguration has two specializations:
    • IConfigurationRoot ルート ノードに使用されます。IConfigurationRoot Used for the root node. 再読み込みをトリガーできます。Can trigger a reload.
    • IConfigurationSection 構成値のセクションを表します。IConfigurationSection Represents a section of configuration values. GetSection および GetChildren メソッドは IConfigurationSection を返します。The GetSection and GetChildren methods return an IConfigurationSection.
    • 構成を再度読み込むとき、あるいは各プロバイダーにアクセスする場合、IConfigurationRoot を使用します。Use IConfigurationRoot when reloading configuration or for access to each provider. いずれの状況も一般的ではありません。Neither of these situations are common.

その他の技術情報Additional resources