在 ASP.NET Core 中使用多個環境

作者：Rick Anderson 與 Kirk Larkin

ASP.NET Core 會使用環境變數根據執行階段環境來設定應用程式行為。

環境

為判斷執行階段環境，ASP.NET Core 會從下列環境變數讀取：

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT，呼叫 WebApplication.CreateBuilder 方法時。 預設 ASP.NET Core Web 應用程式範本呼叫 WebApplication.CreateBuilder。 使用 WebApplicationBuilder 時，DOTNET_ENVIRONMENT 值會覆寫 ASPNETCORE_ENVIRONMENT。 對於其他主機，例如 ConfigureWebHostDefaults 和 WebHost.CreateDefaultBuilder，ASPNETCORE_ENVIRONMENT 具有較高的優先順序。

IHostEnvironment.EnvironmentName 可以設定為任何值，但架構會提供下列值：

• Development：launchSettings.json 檔案會在本機電腦上將 ASPNETCORE_ENVIRONMENT 設定為 Development。
• Staging
• Production：如果未設定 DOTNET_ENVIRONMENT 和 ASPNETCORE_ENVIRONMENT，則為預設值。

下列程式碼範例：

• 類似於 ASP.NET Core 範本所產生的程式碼。
• 當 ASPNETCORE_ENVIRONMENT 設定為 Development 時，啟用開發人員例外狀況頁面。 這會由 WebApplication.CreateBuilder 方法自動完成。
• 當 ASPNETCORE_ENVIRONMENT 的值不是 Development 時呼叫 UseExceptionHandler。
• 在 WebApplication 的 Environment 屬性中提供 IWebHostEnvironment 執行個體。

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

環境標籤協助程式會使用 IHostEnvironment.EnvironmentName 的值來包含或排除元素中的標記：

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

範例程式碼的關於頁面包含上述標記，並顯示 IWebHostEnvironment.EnvironmentName 的值。

在 Windows 及 macOS 上，環境變數和值不區分大小寫。 Linux 的環境變數和值則預設區分大小寫。

建立 EnvironmentsSample

本文中使用的範例程式碼是以名為 EnvironmentsSample 的 Razor Pages 專案為基礎。

下列 .NET CLI 命令會建立並執行名為 EnvironmentsSample 的 Web 應用程式：

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

應用程式執行時會顯示類似下列的輸出：

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

在命令列上設定環境

使用 --environment 旗標來設定環境。 例如：

dotnet run --environment Production

上述命令會將環境設定為 Production，並在命令視窗中顯示類似下列的輸出：

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

開發和 launchSettings.json

您可以在開發環境中啟用生產環境不應該公開的功能。 例如，ASP.NET Core 專案範本會在開發環境中啟用開發人員例外狀況頁面。 由於效能成本，範圍驗證和相依性驗證只會在開發中發生。

您可以在專案的 Properties\launchSettings.json 檔案設定適用於本機電腦開發的環境。 在 launchSettings.json 中設定的環境值會覆寫在系統環境設定的值。

launchSettings.json 檔案：

• 只在本機開發機器上使用。
• 未部署。
• 包含設定檔設定。

下列 JSON 顯示使用 Visual Studio 或 dotnet new 建立、名為 EnvironmentsSample 的 ASP.NET Core Web 專案的 launchSettings.json 檔案：

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

上述 JSON 包含兩個設定檔：

• EnvironmentsSample：設定檔名稱是專案名稱。 如所列的第一個設定檔，預設會使用此設定檔。 "commandName" 索引鍵具有值 "Project"，因此會啟動 Kestrel 網頁伺服器。

• IIS Express："commandName" 索引鍵具有值 "IISExpress"，因此 IISExpress 是網頁伺服器。

您可以將啟動設定檔設定為專案或包含在 launchSettings.json 中的任何其他設定檔。 例如，在下圖中，選取專案名稱會啟動 Kestrel 網頁伺服器。

commandName 的值可以指定要啟動的網頁伺服器。 commandName 可以是下列任何一個項目：

• IISExpress：啟動 IIS Express。
• IIS：未啟動網頁伺服器。 IIS 必須可用。
• Project：啟動 Kestrel。

Visual Studio 2022 專案屬性 [偵錯/一般] 索引標籤提供 [開啟偵錯啟動設定檔 UI] 連結。 此連結會開啟 [啟動設定檔] 對話方塊，讓您編輯 launchSettings.json 檔案中的環境變數設定。 您也可以選取 [<專案名稱> 偵錯屬性]，從 [偵錯] 功能表開啟 [啟動設定檔] 對話方塊。 您對專案設定檔所做的變更可能要等重新啟動網頁伺服器後才會生效。 您必須重新啟動 Kestrel，它才會偵測到對環境進行的變更。

下列 launchSettings.json 檔案包含多個設定檔：

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

可以選取設定檔：

• 從 Visual Studio UI。

• 使用 dotnet run CLI 命令，並將 --launch-profile 選項設定為設定檔的名稱。 此方法僅支援 Kestrel 設定檔。

  dotnet run --launch-profile "EnvironmentsSample"
  

警告

launchSettings.json 不應該儲存祕密。 密碼管理員工具可以用來儲存本機開發的密碼。

使用 Visual Studio Code 時，可以在 .vscode/launch.json 檔案中設定環境變數。 下列範例會為主機設定值的設定數個環境變數：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

.vscode/launch.json 檔案僅供 Visual Studio Code 使用。

Production

若要將安全性、效能及應用程式的健全性最大化，您應該設定生產環境。 不同於開發的某些一般設定包括：

• 快取。
• 用戶端的資源會經過配套、縮減，且可能由 CDN 提供。
• 停用診斷錯誤頁面。
• 啟用易懂的錯誤頁面。
• 啟用生產記錄與監視。 例如，使用 Application Insights。

藉由設定環境變數來設定環境

使用環境變數或平台設定來測試特定環境通常很有用。 如果您未設定環境，它會預設為 Production 並停用大部分的偵錯功能。 環境的設定方法取決於作業系統而定。

建置主機時，應用程式讀取的最後一個環境設定會決定應用程式的環境。 應用程式執行時，無法變更應用程式的環境。

範例程式碼中的關於頁面會顯示 IWebHostEnvironment.EnvironmentName 的值。

Azure App Service

如果 DOTNET_ENVIRONMENT 和 ASPNETCORE_ENVIRONMENT 尚未設定，則 Production 為預設值。 部署至 Azure 的應用程式預設為 Production。

若要使用入口網站在 Azure App Service 應用程式中設定環境：

1. 從 [應用程式服務] 頁面選取應用程式。
2. 在 [設定] 群組中，選取 [設定]。
3. 在 [應用程式設定] 索引標籤中，選取 [新增應用程式設定]。
4. 在 [新增/編輯應用程式設定] 視窗中，針對 [名稱] 提供 ASPNETCORE_ENVIRONMENT。 針對 [值]，提供環境 (例如 Staging)。
5. 如果您想要在交換部署位置時，環境設定保留目前的位置，請選取 [部署位置設定] 核取方塊。 如需詳細資訊，請參閱 Azure 文件中的在 Azure App Service 中設定預備環境。
6. 選取 [確定] 以關閉 [新增/編輯應用程式設定] 對話方塊。
7. 選取 [設定] 頁面頂端的 [儲存]。

Azure App Service 會在新增、變更或刪除 Azure 入口網站的應用程式設定之後自動重新啟動應用程式。

Windows - 設定程序的環境變數

launchSettings.json 中的環境值會覆寫在系統環境設定的值。

若要在使用 dotnet run 啟動應用程式時設定目前工作階段的 ASPNETCORE_ENVIRONMENT，請在命令提示字元或 PowerShell 中使用下列命令：

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Windows - 全域設定環境變數

上述命令只會針對從該命令視窗啟動的程序設定 ASPNETCORE_ENVIRONMENT。

若要在 Windows 中以全域的方式設定值，請使用下列其中一個方法：

• 開啟 [控制台]>[系統]>[進階系統設定]，然後新增或編輯 ASPNETCORE_ENVIRONMENT 值：

  

  

• 開啟系統管理命令提示字元，然後使用 setx 命令，或開啟系統管理 PowerShell 命令提示字元，然後使用 [Environment]::SetEnvironmentVariable：

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    /M 參數會在系統層級設定環境變數。 若未使用 /M 參數，則將環境變數設定為使用者帳戶。

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    Machine 選項會在系統層級設定環境變數。 若選項值變更為 User，則將環境變數設定為使用者帳戶。

當以全域的方式設定 ASPNETCORE_ENVIRONMENT 環境變數時，則在設定該值後開啟的任何命令視窗中，對 dotnet run 均有效。 launchSettings.json 中的環境值會覆寫在系統環境設定的值。

Windows - 使用 web.config

若要使用 web.config 設定 ASPNETCORE_ENVIRONMENT 環境變數，請參閱 web.config 檔案的設定環境變數區段。

Windows - IIS 部署

在發行設定檔 (.pubxml) 或專案檔中包括 <EnvironmentName> 屬性。 此方法會在專案發行時於 web.config 中設定環境：

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

若要為執行於隔離應用程式集區 (受 IIS 10.0 或更新版本支援) 的應用程式設定 ASPNETCORE_ENVIRONMENT 環境變數，請參閱環境變數 <environmentVariables> 的 AppCmd.exe 命令區段。 當 ASPNETCORE_ENVIRONMENT 環境變數設定為應用程式集區時，其值會覆寫系統層級的設定。

在 IIS 中裝載應用程式時，並新增或變更 ASPNETCORE_ENVIRONMENT 環境變數時，請使用下列其中一種方法，讓應用程式挑選新的值：

• 從命令提示字元執行後面接著 net start w3svc 的 net stop was /y。
• 重新啟動伺服器。

macOS

您可以在執行應用程式時，以內嵌方式設定 macOS 目前的環境：

ASPNETCORE_ENVIRONMENT=Staging dotnet run

或者，在執行應用程式之前，使用 export 設定環境：

export ASPNETCORE_ENVIRONMENT=Staging

您可以在 .bashrc 或 .bash_profile 檔案中設定電腦層級的環境變數。 使用任何文字編輯器編輯檔案。 新增下列陳述式：

export ASPNETCORE_ENVIRONMENT=Staging

Linux

針對 Linux 散發版本，請在命令提示字元使用 export 命令，進行以工作階段為基礎的變數設定，並使用 bash_profile 檔案，進行機器層級的環境設定。

在程式碼中設定環境

若要在程式碼中設定環境，請在建立 WebApplicationBuilder 時使用 WebApplicationOptions.EnvironmentName，如下列範例所示：

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

取決於環境的組態

若要依環境載入設定，請參閱 ASP.NET Core 中的設定。

依環境設定服務和中介軟體

根據目前的環境，使用 WebApplicationBuilder.Environment 或 WebApplication.Environment 有條件地新增服務或中介軟體。 專案範本包含程式碼範例，只有在目前的環境不是開發時，才會新增中介軟體：

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

反白顯示的程式碼會在建置要求管線時檢查目前的環境。 若要在設定服務時檢查目前的環境，請使用 builder.Environment 而非 app.Environment。

其他資源

• 檢視或下載範例程式碼 \(英文\) (如何下載)
• ASP.NET Core 中的應用程式啟動
• ASP.NET Core 中的設定
• ASP.NET Core Blazor 環境