.NET での構成

.NET での構成は、1 つまたは複数の構成プロバイダーを使用して実行されます。 構成プロバイダーは、以下のようなさまざまな構成ソースを使用して、キーと値のペアから構成データを読み取ります:

  • appsettings.json などの設定ファイル
  • 環境変数
  • Azure Key Vault
  • Azure App Configuration
  • コマンド ライン引数
  • インストール済みまたは作成済みのカスタム プロバイダー
  • ディレクトリ ファイル
  • メモリ内 .NET オブジェクト
  • サード パーティ プロバイダー

Note

.NET ランタイム自体の構成については、「.NET ランタイム構成設定」を参照してください。

コンソール アプリの構成

既定で dotnet new または Visual Studio を使用して作成された新しい .NET コンソール アプリケーションでは、構成機能は公開 "されません"。 新しい .NET コンソール アプリケーションで構成を追加するには、パッケージ参照を追加します。 Program.cs ファイルを次のコードに一致するように変更します。

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateDefaultBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Host.CreateDefaultBuilder(String[]) メソッドにより、次の順序でアプリの既定の構成が提供されます。

  1. ChainedConfigurationProvider: 既存の をソースとして追加します。
  2. JSON 構成プロバイダーを使用する appsettings.json
  3. JSON 構成プロバイダーを使用する appsettings.json。 たとえば、appsettings.Production.json および appsettings.Development.json
  4. 環境でアプリが実行される際の App シークレット
  5. 環境変数構成プロバイダーを使用する環境変数。
  6. コマンドライン構成プロバイダーを使用するコマンドライン引数。

後から追加される構成プロバイダーは、それ以前のキー設定をオーバーライドします。 たとえば、SomeKeySomeKey と環境の両方で設定されている場合、環境の値が使用されます。 既定の構成プロバイダーを使用すると、コマンドライン構成プロバイダーによって他のすべてのプロバイダーがオーバーライドされます。

バインド

.NET 構成の抽象化を使用する主な利点の 1 つは、構成値を .NET オブジェクトのインスタンスにバインドできることです。 たとえば、JSON 構成プロバイダーは、appsettings.json ファイルを .NET オブジェクトにマップするのに使用でき、依存関係の挿入で使用されます。 これによりオプション パターンが有効になります。これは、クラスを使用して、関連する設定のグループに厳密に型指定されたアクセスを提供します。 .NET 構成では、さまざまな抽象化が提供されます。 次のインターフェイスについて考えてみましょう。

  • IConfiguration: キー/値のアプリケーション構成プロパティのセットを表します。
  • IConfigurationRoot: IConfiguration 階層のルートを表します。
  • IConfigurationSection: アプリケーション構成値のセクションを表します。

これらの抽象化は、基になる構成プロバイダー (IConfigurationProvider) に依存します。 つまり、IConfiguration インスタンスを使用して、複数のプロバイダーから任意の構成値にアクセスできます。

基本的な例

汎用ホスト アプローチのサポートなしに、基本形式で構成値にアクセスするには、 型を直接使用します。

ヒント

System.Configuration.ConfigurationBuilder 型は Microsoft.Extensions.Configuration.ConfigurationBuilder 型と異なります。 このコンテンツはすべて、Microsoft.Extensions.* NuGet パッケージと名前空間に固有です。

次の C# プロジェクトについて考えてみましょう。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="6.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="6.0.0" />
  </ItemGroup>

</Project>

前のプロジェクト ファイルでは、次の複数の構成 NuGet パッケージが参照されています。

appsettings.json ファイルの例を考えてみましょう。

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice..."
        }
    }
}

ここで、この JSON ファイルは、構成ビルダーを直接使用した使用パターンの例です。

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings.KeyOne}");
Console.WriteLine($"KeyTwo = {settings.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings.KeyThree.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

前述の C# コードでは、次のことが行われます。

  • ConfigurationBuilder をインスタンス化します。
  • JSON 構成プロバイダーによって認識される "appsettings.json" ファイルを追加します。
  • 環境変数構成プロバイダーによって認識される環境変数を追加します。
  • config インスタンスを使用して、必要な "Settings" セクションと対応する Settings インスタンスを取得します。

Settings オブジェクトは次のように成型されます。

public class Settings
{
    public int KeyOne { get; set; }
    public bool KeyTwo { get; set; }
    public NestedSettings KeyThree { get; set; } = null!;
}
public class NestedSettings
{
    public string Message { get; set; } = null!;
}

ホスティングの基本的な例

IConfiguration 値にアクセスするには、Microsoft.Extensions.Hosting NuGet パッケージを再度使用できます。 新しいコンソール アプリケーションを作成し、次のプロジェクト ファイルの内容を貼り付けます。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="6.0.0" />
  </ItemGroup>

</Project>

前のプロジェクト ファイルでは、次のものを定義します。

  • アプリケーションが実行可能ファイルである。
  • プロジェクトのコンパイル時に、appsettings.json ファイルを出力ディレクトリにコピーする。
  • Microsoft.Extensions.Hosting NuGet パッケージ参照が追加されている。

次の内容を含む appsettings.json ファイルを、プロジェクトのルートに追加します。

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

次の C# コードで、Program.cs ファイルの内容を置き換えます。

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateDefaultBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

このアプリケーションを実行すると、Host.CreateDefaultBuilder では JSON 構成を検出する動作が定義され、IConfiguration インスタンスを介してそれが公開されます。 host インスタンスから、サービス プロバイダーに IConfiguration インスタンスを求め、次に値を求めることができます。

ヒント

この方法で生の IConfiguration インスタンスを使用すると便利ですが、あまりうまくスケーリングされません。 アプリケーションが複雑になり、対応する構成がより複雑になる場合は、代替手段としてオプション パターンを使用することをお勧めします。

構成プロバイダー

.NET Core アプリで使用できる構成プロバイダーを次の表に示します。

プロバイダー 以下から構成を提供します
Azure App Configuration プロバイダー Azure App Configuration
Azure Key Vault 構成プロバイダー Azure Key Vault
コマンド ライン構成プロバイダー コマンド ライン パラメーター
カスタム構成プロバイダー カスタム ソース
環境変数構成プロバイダー 環境変数
ファイル構成プロバイダー JSON、XML、および INI ファイル
ファイルごとのキーの構成プロバイダー ディレクトリ ファイル
メモリ構成プロバイダー メモリ内コレクション
アプリのシークレット (Secret Manager) ユーザー プロファイル ディレクトリ内のファイル

さまざまな構成プロバイダーの詳細については、「.NET の構成プロバイダー」を参照してください。

関連項目