ASP.NET Core アプリケーションで、appsettings.Development.json と appsettings.Production.json がどのような状況で読み込まれるかを紹介します。

「appsettings.Production.json はどういう場合に読み込まれるのか」「Visual Studio での実行時には読み込まれないのか」といった疑問に答える形で、 環境別の設定ファイルが読み込まれる仕組みと、実際の動作を確認します。

まとめ

実行状況ごとに読み込まれるファイルをまとめると以下の表になります。

実行状況	環境名	読み込まれるファイル
Visual Studio からの実行 (既定のプロファイル)	Development	appsettings.json + appsettings.Development.json
Visual Studio からの実行 (プロファイルの環境変数を Production に変更)	Production	appsettings.json + appsettings.Production.json
発行後の実行 (環境変数の設定なし)	Production (既定値)	appsettings.json + appsettings.Production.json
発行後の実行 (ASPNETCORE_ENVIRONMENT を設定)	環境変数の値	appsettings.json + appsettings.{環境名}.json (存在する場合)

概要

ASP.NET Core アプリケーションの設定ファイルには、すべての環境で共通に利用される appsettings.json のほかに、 appsettings.Development.json や appsettings.Production.json といった、環境別の設定ファイルがあります。

環境別の設定ファイルのファイル名は appsettings.{環境名}.json の形式です。 アプリケーションの起動時に、まず appsettings.json が読み込まれ、続いて「現在の実行環境名」に一致する appsettings.{環境名}.json が読み込まれます。後から読み込まれたファイルの値が優先されるため、 環境別ファイルに記述したキーは appsettings.json の値を上書きし、記述しなかったキーは appsettings.json の値がそのまま利用されます。

どちらの環境別ファイルが読み込まれるかは、ビルド構成 (Debug/Release) ではなく、実行時の「環境名」で決まる点がポイントです。

実行環境名の決まり方

実行環境名は、環境変数 ASPNETCORE_ENVIRONMENT (または DOTNET_ENVIRONMENT) の値で決まります。

• 環境変数に Development が設定されている場合 : 環境名は "Development" となり、appsettings.Development.json が読み込まれます。
• 環境変数に Production が設定されている場合 : 環境名は "Production" となり、appsettings.Production.json が読み込まれます。
• 環境変数が設定されていない場合 : 環境名は既定値の "Production" となり、appsettings.Production.json が読み込まれます。

「環境変数」はどこに設定するのか

「環境変数」というと、Windows の [システムのプロパティ] から設定する OS の環境変数 (システム環境変数・ユーザー環境変数) を 思い浮かべますが、アプリケーションが参照するのは OS に登録された環境変数そのものではなく、 アプリケーションのプロセスが起動されたときに、そのプロセスに渡されている環境変数です。

環境変数はプロセスごとに保持されており、プロセスは起動時に親プロセス (自分を起動したプロセス) の環境変数を引き継ぎます。 OS のシステム環境変数は「すべてのプロセスに共通で引き継がれる既定値」であり、環境変数の設定場所の一つにすぎません。 また、プロセスを起動する側は、起動するプロセスに対して環境変数を追加・上書きして渡すことができます。 launchSettings.json や web.config での環境変数の設定は、この仕組みを利用したものです。

• launchSettings.json の environmentVariables は、Visual Studio (または dotnet run) がアプリケーションのプロセスを起動する際に、起動するそのプロセスに対してだけ設定する環境変数です。OS の環境変数には登録されません。
• web.config の <environmentVariables> は、IIS (ASP.NET Core Module) がアプリケーションのワーカープロセスを起動する際に、そのアプリケーションのプロセスに対してだけ設定する環境変数です。こちらも OS の環境変数には登録されません。

このため、OS の環境変数に ASPNETCORE_ENVIRONMENT を何も設定していなくても、 launchSettings.json や web.config の記述だけで環境名を与えることができます。 逆に、web.config に記述した値が OS の環境変数を書き換えてしまうこともありません。 「どこに設定するか」は「誰がアプリケーションのプロセスを起動するか」で決まる、と理解すると分かりやすいです。

環境変数の設定場所の一覧

ASPNETCORE_ENVIRONMENT の主な設定場所と適用範囲は以下の表のとおりです。

設定場所	適用範囲	主な利用場面
OS のシステム環境変数・ユーザー環境変数 ([システムのプロパティ] や setx コマンドで設定)	マシン上の (そのユーザーの) すべてのプロセス	マシン全体を特定の環境に固定する場合。IIS に反映するには iisreset または OS の再起動が必要
launchSettings.json の environmentVariables	Visual Studio や dotnet run で起動したプロセスのみ	開発時の実行。プロジェクト新規作成時に Development が設定済み
web.config の environmentVariables	IIS がそのアプリケーション用に起動するプロセスのみ	IIS でサイト (アプリケーション) 単位に環境を切り替える場合
IIS マネージャーの [構成エディター] (applicationHost.config)	設定したサイト・アプリケーションのプロセス	発行のたびに上書きされる web.config を編集せずに IIS 側で設定したい場合
コマンドプロンプトで set コマンドを実行してから起動	そのコンソールから起動したプロセスのみ	動作確認や一時的な切り替え

複数のサイトを 1 台のサーバーで運用する場合、OS のシステム環境変数に設定するとすべてのサイトに同じ環境名が適用されてしまうため、 サイトごとに環境を分けたい場合は web.config (または IIS の構成エディター) で設定します。

複数の場所で設定されている場合の優先順位

同じ環境変数が複数の場所で設定されている場合は、プロセスの起動により近い側の設定が優先されます。 IIS での実行では、OS のシステム環境変数よりも web.config の environmentVariables の値が優先されます。 Visual Studio からの実行では、OS のシステム環境変数よりも launchSettings.json の値が優先されます。

また、環境変数とは別に、アプリケーション起動時のコマンドライン引数 --environment でも環境名を指定できます。 コマンドライン引数は環境変数よりも優先されます。

dotnet AppSettingsDemo.dll --environment Staging

Visual Studio から実行した場合

Visual Studio からデバッグ実行 (または dotnet run で実行) した場合は、プロジェクトの Properties\launchSettings.json に記述された 実行プロファイルの環境変数が適用されます。

プロジェクトを新規作成すると、launchSettings.json の各プロファイルには ASPNETCORE_ENVIRONMENT: Development があらかじめ設定されています。

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5158",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7179;http://localhost:5158",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

このため、Visual Studio からの実行時は環境名が "Development" となり、appsettings.Development.json が読み込まれます。 appsettings.Production.json は読み込まれません。

「Visual Studio 実行時には appsettings.Production.json は読み込まれない」というのは既定のプロファイル設定による動作であり、 launchSettings.json の ASPNETCORE_ENVIRONMENT の値を Production に書き換えれば (またはプロファイルから環境変数の設定を削除すれば)、 Visual Studio からの実行でも appsettings.Production.json を読み込ませることができます。 プロファイルの環境変数は、プロジェクトのプロパティの [デバッグ] の [起動プロファイル] 画面からも変更できます。

発行して実行した場合

アプリケーションを発行 (publish) して IIS やサーバー上で実行した場合、launchSettings.json は利用されないため、 環境変数 ASPNETCORE_ENVIRONMENT をサーバー側で明示的に設定していなければ、環境名は既定値の "Production" になります。 その結果、appsettings.Production.json が読み込まれます。

「本番サーバーに配置して普通に動かした場合に読み込まれるファイル」が appsettings.Production.json である、と理解すると分かりやすいです。

なお、発行時の出力フォルダには appsettings.json だけでなく、 appsettings.Development.json、appsettings.Production.json もすべてコピーされます。 どのファイルを読み込むかは配置先での実行時に環境名によって決まるため、環境別ファイルもすべて配置される動作となっています。

AppSettingsDemo.dll
appsettings.json
appsettings.Development.json
appsettings.Production.json
web.config

本番サーバーで環境名を明示的に指定したい場合は、環境変数 ASPNETCORE_ENVIRONMENT を設定します。 IIS で動作させる場合は、web.config に以下の記述を追加することでアプリケーション単位で環境変数を設定できます。

<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <aspNetCore processPath="dotnet" arguments=".\AppSettingsDemo.dll" stdoutLogEnabled="false" hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Staging" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

この記述は OS の環境変数を変更するものではなく、IIS がこのアプリケーションのプロセスを起動する際に、 そのプロセスに対して環境変数を設定するものです。詳細は前述の「環境変数はどこに設定するのか」を参照してください。

appsettings.Development.json、appsettings.Production.json のどちらが読み込まれるかは、 ビルド構成ではなく実行時の環境変数 ASPNETCORE_ENVIRONMENT の値 (未設定の場合は "Production") で決まります。 Visual Studio からの実行時は launchSettings.json により環境名が "Development" に設定されるため appsettings.Production.json は読み込まれず、 発行して環境変数を設定せずに実行した場合は appsettings.Production.json が読み込まれる動作となります。