.NET での構成

2024-10-09

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

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

注

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

概念と抽象化

1 つ以上の構成ソースを指定すると、 IConfiguration の種類によって、構成データの統一されたビューが提供されます。構成は読み取り専用であり、構成パターンはプログラムで書き込み可能に設計されていません。 IConfiguration インターフェイスは、次の図に示すように、すべての構成ソースの単一の表現です。

コンソールアプリを構成する

dotnet の新しいコマンドテンプレートまたは Visual Studio を使用して作成された .NET コンソールアプリケーションでは、既定では構成機能は公開されません。新しい .NET コンソールアプリケーションで構成を追加するには、Microsoft.Extensions.Configuration へのパッケージ参照を追加します。このパッケージは、.NET アプリでの構成の基礎です。 ConfigurationBuilderおよび関連する型が提供されます。

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

前述のコード:

新しい ConfigurationBuilder インスタンスを作成します。
キーと値のペアのメモリ内コレクションを構成ビルダーに追加します。
Build() メソッドを呼び出して、IConfiguration インスタンスを作成します。
SomeKey キーの値をコンソールに書き込みます。

この例ではメモリ内構成を使用していますが、使用可能な構成プロバイダーは多数あり、ファイルベース、環境変数、コマンドライン引数、およびその他の構成ソースの機能が公開されています。詳細については、「 .NET の構成プロバイダー」を参照してください。

代替ホスティングアプローチ

一般的に、アプリは単なる読み取り構成以上の処理を行います。依存関係の挿入、ログ記録、およびその他のサービスを使用する可能性があります。これらのサービスを使用するアプリには、.NET 汎用ホストアプローチをお勧めします。代わりに、Microsoft.Extensions.Hosting へのパッケージ参照の追加を検討してください。次のコードに一致するように Program.cs ファイルを変更します。

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

Host.CreateApplicationBuilder(String[])メソッドは、アプリの既定の構成を、優先度が最も高いものから最も低いものまで、次の順序で提供します。

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

構成プロバイダーを追加すると、以前の構成値がオーバーライドされます。たとえば、コマンドライン構成プロバイダーは、最後に追加されるため、他のプロバイダーのすべての値をオーバーライドします。 appsettings.jsonと環境の両方でSomeKeyが設定されている場合は、appsettings.json後に追加されたため、環境の値が使用されます。

バインド

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

.NET 構成では、さまざまな抽象化が提供されます。次のインターフェイスについて考えてみましょう。

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

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

バインダーは、構成値を処理するためにさまざまな方法を使用できます。

プリミティブ型の直接逆シリアル化 (組み込みコンバーターを使用)。
複合型の TypeConverter (型に備わっている場合)。
プロパティを持つ複合型のリフレクション。

注

バインダーにはいくつかの制限があります。

プライベートセッターがある場合、または型を変換できない場合、プロパティは無視されます。
対応する構成キーのないプロパティは無視されます。

バインド階層

構成値には階層データを含めることができます。階層オブジェクトは、構成キーで : 区切り記号を使用して表されます。構成値にアクセスするには、 : 文字を使用して階層を区切ります。たとえば、次の構成値を考えてみます。

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

次の表は、前の JSON 例のキーの例とそれに対応する値を示しています。

鍵	価値
`"Parent:FavoriteNumber"`	`7`
`"Parent:Child:Name"`	`"Example"`
`"Parent:Child:GrandChild:Age"`	`3`

基本的な例

一般的なホスト アプローチを使用せずに、基本的な形式で構成値にアクセスするには、ConfigurationBuilder型を直接使用します。

ヒント

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

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.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="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.6" />
  </ItemGroup>

</Project>

上記のプロジェクトファイルは、いくつかの構成 NuGet パッケージを参照しています。

Microsoft.Extensions.Configuration.Binder: Microsoft.Extensions.Configurationの構成プロバイダー内のデータにオブジェクトをバインドする機能。
Microsoft.Extensions.Configuration.Json: Microsoft.Extensions.Configurationの JSON 構成プロバイダーの実装。
Microsoft.Extensions.Configuration.EnvironmentVariables: Microsoft.Extensions.Configurationの環境変数構成プロバイダーの実装。

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

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

次に、この JSON ファイルを考えると、構成ビルダーを直接使用した使用パターンの例を次に示します。

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot 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 sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

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

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.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="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.6" />
  </ItemGroup>

</Project>

上記のプロジェクトファイルでは、次のことが定義されています。

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

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

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

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

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

using IHost host = Host.CreateApplicationBuilder(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.CreateApplicationBuilder は JSON 構成を検出し、 IConfiguration インスタンスを介して公開する動作を定義します。 host インスタンスから、サービスプロバイダーに IConfiguration インスタンスを要求し、値を要求できます。

ヒント

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

インデクサー API のホスティングと使用に関する基本的な例

前の例と同じ appsettings.json ファイルの内容を考えてみます。

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

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

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

using IHost host = Host.CreateApplicationBuilder(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.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

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

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

各キーが文字列であり、値が文字列であるインデクサー API を使用して値にアクセスします。構成では、プロパティ、オブジェクト、配列、ディクショナリがサポートされています。

構成プロバイダー

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

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

ヒント

構成プロバイダーを追加する順序が重要です。複数の構成プロバイダーが使用され、複数のプロバイダーが同じキーを指定している場合は、最後に追加されたものが使用されます。

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

こちらも参照ください

.NET の構成プロバイダー
カスタム構成プロバイダーを実装する
github.com/dotnet/runtime リポジトリに構成のバグを作成する必要がある
ASP.NET Core での構成