淺談 ASP.NET Core 中的環境名稱設定與應用

TLDR

• ASP.NET Core 透過 ASPNETCORE_ENVIRONMENT 環境變數區分執行環境（如 Development, Staging, Production）。
• 設定檔載入機制為「後載入覆蓋前載入」，系統會自動依序載入 appsettings.json 與 appsettings.{EnvironmentName}.json。
• 手動在程式中重複載入設定檔可能導致預期的環境設定被覆蓋。
• 本機開發可透過 launchSettings.json 設定；IIS 發佈需在 Publish Profile 的 XML 中加入 <EnvironmentName> 標籤；Docker 則透過 ENV 指令設定。
• 執行階段可透過注入 IWebHostEnvironment 並使用 IsDevelopment()、IsStaging()、IsProduction() 或 IsEnvironment() 進行判斷。

組態設定與環境名稱機制

在 .NET Core 及後續版本中，環境變數 EnvironmentName 是區分執行環境的核心機制。ASP.NET Core 預設提供三個環境：

• Development：本機開發使用。
• Staging：預發佈版本。
• Production：若未設定環境變數，則預設為此環境。

與過往 .NET Framework 使用 Web.config 的 Transform 機制不同，ASP.NET Core 採用 appsettings.json 的覆蓋邏輯。系統在執行 WebApplication.CreateBuilder(args) 時，會自動呼叫 ConfigureDefaults() 並依序載入設定檔：

builder.ConfigureAppConfiguration((hostingContext, config) => {
    IHostEnvironment env = hostingContext.HostingEnvironment;
    // 後載入的設定會覆蓋先載入的設定
    config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: reloadOnChange)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: reloadOnChange);
    
    // ... 其他設定
})

WARNING

什麼情況下會遇到設定失效的問題？ 若開發者在 Program.cs 中手動重複載入 appsettings.json，可能會覆蓋掉系統自動載入的 appsettings.{EnvironmentName}.json。若發現環境設定未生效，請檢查是否在 Program 中有不必要的重複載入邏輯。

設定環境變數的方法

本機開發

透過專案下的 Properties\launchSettings.json 設定，此設定會覆蓋全域環境變數，並影響 Visual Studio 的執行設定：

{
  "profiles": {
    "Sample": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

使用 Visual Studio 發佈至 IIS

若要指定發佈環境，需在 Publish Profile (.pubxml) 的 XML 中加入 <EnvironmentName> 標籤：

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

發佈後，IIS 的 web.config 會自動產生對應的環境變數設定：

<aspNetCore ...>
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Staging" />
  </environmentVariables>
</aspNetCore>

TIP

什麼情況下會無法排除多餘檔案？ 在 ASP.NET Core 中，舊版 Web.config 的 <ExcludeFilesFromDeployment> 設定已失效，因此無法透過此方式排除不需要的 appsettings.{環境}.json 檔案。

使用 Dockerfile 設定

在 Docker 容器中，直接於 Dockerfile 使用 ENV 指令即可指定環境：

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
ENV ASPNETCORE_ENVIRONMENT=Staging

操作環境設定

開發者可透過注入 IWebHostEnvironment 介面，在程式執行階段判斷目前的環境。

• 判斷方式：使用 IsDevelopment()、IsStaging() 或 IsProduction() 等擴充方法。
• 自定義環境：若使用非預設的環境名稱，可使用 IsEnvironment("{environmentName}") 進行判斷。

---

異動歷程

• 2024-07-12 初版文件建立。