appsettings.json 設定ファイルの使用方法は？

在 .NET Core プロジェクトでは、appsettings.json 設定ファイルを使用してアプリケーションの設定情報を保存できます。この記事では、appsettings.json 設定ファイルの使用方法を学びます。

appsettings.json は、App.config よりも柔軟な設定ファイルであり、.NET Core 以降に追加された設定方法で、より多くの柔軟性を提供します。

クイックスタート#

プロジェクト内に appsettings.json ファイルを作成し、その生成操作を「新しい場合はコピー」または「常にコピー」に設定すると、プロジェクトのビルド時に appsettings.json ファイルが出力ディレクトリにコピーされます。

次に、以下の内容を追加できます：

{
    "AppSettings": {		
        "LogLevel":"Warning",
        "ConnectionStrings": {
            "Default": "this is the connection string"
        }	
    }
}

これで読み取ることができます。NuGet パッケージマネージャーを使用して Microsoft.Extensions.Configuration.Json パッケージをインストールします。これにより、Microsoft.Extensions.Configuration などの依存関係が暗黙的にインストールされ、明示的にインストールする必要はありません。

次に、コード内で設定ファイルを読み取ることができます：

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

これで上記の設定情報を取得できます：

var logLevel = configuration["AppSettings:LogLevel"];
var connectionString = configuration["AppSettings:ConnectionStrings:Default"];

ここでの AppSettings.LogLevel のような形式は特別な書き方で、簡単に言えば : を使って JSON 内の階層関係を示しています。

取得する設定項目が数字の場合、上記の方法で文字列を取得し、int.Parse や Convert.ToInt32 などの方法で変換することもできますが、GetValue メソッドを使用することもできます：

// 従来の方法
var logLevel = int.Parse(configuration["AppSettings:LogLevel"]);
// GetValue メソッドを使用
var logLevel = configuration.GetValue<int>("AppSettings:LogLevel");

接続文字列については、GetConnectionString メソッドを使用することもできます：

var connectionString = configuration.GetConnectionString("Default");

オプションと自動リロード#

上記のコードでは、AddJsonFile メソッドに optional と reloadOnChange の 2 つのパラメータがあることがわかります：

optional パラメータは、設定ファイルが存在しないことを許可するかどうかを示します。false に設定すると例外がスローされ、それ以外の場合は無視されます。
reloadOnChange パラメータは、設定ファイルが変更されたときに設定ファイルを再読み込みするかどうかを示します。true に設定すると、設定ファイルが変更されたときに再読み込みされます。

例えば、以下の例を使用して自動リロードの効果をテストできます：

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

while (true)
{
    Console.WriteLine(configuration["AppSettings:LogLevel"]);
    Thread.Sleep(1000);
}

プログラムを実行した後、appsettings.json ファイル内の LogLevel 設定を変更すると、プログラムが自動的に設定ファイルを再読み込みすることがわかります。ここで変更するのは出力ディレクトリ（つまり .exe ファイルのある場所）にある appsettings.json ファイルであり、プロジェクト内の appsettings.json ファイルではありません。

複数の JSON ファイルを追加#

1 つの JSON ファイルしか追加できない場合、設定ファイルの柔軟性は大幅に低下します。実際には、AddJsonFile メソッドを複数回呼び出して複数の JSON ファイルを追加できます。典型的なシナリオは、開発環境の設定情報を保存するために appsettings.Development.json ファイルを追加することです。

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddJsonFile("appsettings.Development.json", optional: true, reloadOnChange: true)
    .Build();

これにより、appsettings.Development.json ファイルに開発環境の設定情報を保存し、appsettings.json ファイルに一般的な設定情報を保存できます。

さらに、これらの間には優先順位、または上書きの関係があります。具体的には：

appsettings.json と appsettings.Development.json の両方に同じ設定項目がある場合、appsettings.Development.json の設定項目が appsettings.json の設定項目を上書きします。
appsettings.Development.json に特定の設定項目がなく、appsettings.json にある場合、appsettings.json の設定項目が使用されます。
appsettings.Development.json に特定の設定項目があり、appsettings.json にない場合、appsettings.Development.json の設定項目が使用されます。

強い型の設定を使用#

上記の例では、configuration["AppSettings:LogLevel"] を使用して設定情報を取得しましたが、この方法は弱い型の方法です。強い型の方法を使用して設定情報を取得することもできます。

appsettings.json ファイル内の設定項目を次のように変更します：

{
    "UserSettings": {
        "Name": "Alice",
        "Age": 18,
        "IsActive": true
    }
}

次に、強い型の設定クラスを定義します：

public class UserSettings
{
    public string Name { get; set; }
    public int Age { get; set; }
    public bool IsActive { get; set; }
}

設定を取得する前に、NuGet パッケージ Microsoft.Extensions.Options.ConfigurationExtensions をインストールする必要があります。次に、次のように設定情報を取得できます：

var userSettings = configuration.GetSection("UserSettings").Get<UserSettings>();

これで UserSettings オブジェクトを取得でき、userSettings.Name、userSettings.Age、userSettings.IsActive を使用して設定情報を取得できます。

ただし、ここでの userSettings インスタンスはすでに初期化されているため、前述の自動リロード機能は無効になります。自動リロードが必要な場合は、userSettings オブジェクトを再取得する必要があります。

環境変数とコマンドライン引数を追加#

.NET Core では、環境変数やコマンドライン引数を使用して設定ファイル内の設定情報を上書きすることもできます。さらに 2 つの NuGet パッケージをインストールする必要があります：

Microsoft.Extensions.Configuration.EnvironmentVariables
Microsoft.Extensions.Configuration.CommandLine

次に、環境変数とコマンドライン引数を追加できます：

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddEnvironmentVariables()
    .AddCommandLine(args)
    .Build();

これにより、環境変数やコマンドライン引数を使用して設定ファイル内の設定情報を上書きできます。

例えば、次のような .bat バッチファイルを作成できます：

@echo off
set UserSettings__Name=Bob
set UserSettings__Age=20

.\Demo.exe

または、PowerShell を使用することもできます：

$env:UserSettings__Name = "Bob"
$env:UserSettings__Age = 20

.\Demo.exe

まとめ#

この記事を通じて、appsettings.json 設定ファイルの強力さを理解していただけたと思います。これは柔軟な設定方法を提供するだけでなく、さまざまな設定方法の組み合わせを提供し、アプリケーションの設定をより柔軟に行えるようにします。

ただし、いくつかの制限もあります。最も重要な点は、設定項目が「読み取り専用」であり、App.config のように実行時に簡単に設定項目を変更できないことです。プロジェクトには複数の設定項目が存在する可能性があり、1 つの appsettings.json ファイルだけではありません。この場合、変更した場合はどのファイルに保存すべきでしょうか？

もちろん、1 つの設定ファイルしかない場合、appsettings.json は良い選択です。例えば、Newtonsoft.Json を使用して JSON ファイルに簡単に書き込むことで、設定項目の変更を実現できます。

最後に、通常の場合、上記の方法で設定項目を読み取ることはなく、さらに進んで Host をプログラム全体の入り口として使用し、設定を読み込み、サービスを注入するなどの操作を行います。次の記事では、Host を使用して .NET アプリケーションを構築する方法を学びます。