ASP.NET 核心執行階段環境

ASP.NET Core 會根據執行階段 環境來設定應用程式行為，這通常會反映應用程式的執行位置。

應用程式通常會在開發人員電腦上進行本機開發和測試期間，在 開發 環境中執行，並設定一組行為。 相反地，當部署至具有不同設定行為集的伺服器時，它們會在 生產 環境中執行。 可以使用任意數量的其他環境，例如架構提供的 暫存 環境，用於在即時部署或開發人員建立的其他環境之前暫存應用程式。

本文說明應用程式執行階段環境、如何使用環境來控制應用程式行為，以及如何設定環境。

如需 Blazor 可新增至或取代本文中指引的環境指引，請參閱 ASP.NET Core Blazor 環境。

Environments

雖然環境可以是任何字串值，但架構會提供下列環境值：

• Development
• Staging
• Production

生產環境已設定為將安全性、效能和應用程式可靠性最大化。 與開發環境不同的常見開發人員設定和組態包括：

• 啟用 快取。
• 捆綁和縮小用戶端資源，以及可能從 CDN 提供這些資源。
• 停用診斷錯誤頁面並啟用友好的錯誤頁面。
• 啟用生產日誌記錄和監控。 例如，Azure Application Insights 的記錄功能已啟用。

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

森林伐木業

啟動時執行中應用程式的命令殼層中的輸出會指出應用程式的環境。 在下列範例中，應用程式在預備環境中執行：

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

決定執行時期環境的環境變數

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

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

使用 WebApplication 時，DOTNET_ENVIRONMENT 值優於 ASPNETCORE_ENVIRONMENT。 使用 WebHost時， ASPNETCORE_ENVIRONMENT 優先。

如果未設定 和 DOTNET_ENVIRONMENT 環境變數，則ASPNETCORE_ENVIRONMENT生產環境是預設環境。

在 Windows 和 macOS 上，環境變數名稱不區分大小寫。 Linux 環境變數區分大小寫。

依據環境來控制程式碼的執行

根據目前的環境，使用 WebApplicationBuilder.Environment 或 WebApplication.Environment 有條件地新增服務或中介軟體。

應用程式檔案 Program 中的下列程式碼：

• 用於 WebApplication.Environment 區分環境。
• 呼叫 UseExceptionHandler，它會將 異常處理程序中介軟體 新增至請求處理管道以處理異常。
• 呼叫 UseHsts，這會新增 HSTS 中介軟體 來套用 Strict-Transport-Security 標頭。

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

上述範例會檢查要求處理管線的目前環境。 若要在設定服務時檢查目前的環境，請使用 builder.Environment 而非 app.Environment。

在應用程式內，IHostEnvironment 提供應用程式裝載環境的一般資訊，而 IHostEnvironment.EnvironmentName 屬性指出應用程式目前的環境。

控制已呈現的內容

IHostEnvironment插入伺服器轉譯的Razor元件，並使用服務的擴充方法和EnvironmentName屬性來決定轉譯內容的環境：

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

如需環境來控制用戶端轉譯的 Blazor Web App，請參閱 預先轉譯 ASP.NET Core Razor 元件。

在執行應用程式時在命令 shell 中設定環境 （dotnet run）

使用選項-e|--environment來設定環境：

dotnet run -e Staging

使用啟動設定檔案 （launchSettings.json） 設定環境

本地開發的環境可以在專案的檔案中 Properties\launchSettings.json 設定。 launchSettings.json 設定的環境值會覆蓋系統環境中設定的值。

launchSettings.json 檔案：

• 只在本機開發機器上使用。
• 應用程式發佈時不會進行部署。
• 可能包含多個設定檔，每個設定檔都設定不同的環境。

下列範例會使用https環境變數，為ASPNETCORE_ENVIRONMENT啟動設定檔設置預備環境：

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

在 Visual Studio 中，有兩種方法可透過啟動配置檔設定環境：

• 按 Alt+Enter 鍵，或在方案總管中以滑鼠右鍵按一下專案之後選取 [屬性]。 選取 偵錯>一般，然後選取 開啟偵錯啟動設定檔 UI 連結。

• 在 [方案總管] 中選取專案後，從 [偵錯] 功能表中選取 [{PROJECT NAME} 偵錯屬性]，其中{PROJECT NAME}預留位置是專案名稱。

上述方法會開啟「 啟動設定檔」 對話方塊，您可以在其中編輯檔案中的 launchSettings.json 環境變數設定。 您對專案設定檔所做的變更可能要等重新啟動網頁伺服器後才會生效。 您必須重新啟動 Kestrel，它才會偵測到對環境進行的變更。

在 Visual Studio 介面的 [開始] 按鈕 (►) 旁邊可以選擇設定檔。

當解決方案包含多個專案時，請只設定啟動專案的環境。

或者，使用dotnet run命令，將-lp|--launch-profile選項設定為設定檔的名稱。 此方法僅支援根據 Project 命令建立的啟動設定檔。

dotnet run -lp "https"

將 Visual Studio Code 與 Visual Studio Code 的 C# 開發套件 搭配使用時 （VS Code 中的 C# 快速入門） ，會從應用程式的 launchSettings.json 檔案中挑選啟動配置檔。

如果未使用 C# 開發套件，請在區段中的 ASPNETCORE_ENVIRONMENT 中.vscode/launch.json設定env環境變數，以及區段中設定的任何其他環境變數：

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

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

使用環境變數設定環境

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

Azure App Service

部署至 Azure App Service 的應用程式預設會採用生產環境。

若要設定 ASPNETCORE_ENVIRONMENT 環境變數，請參閱 Azure 檔中的下列資源：

• 設定 App Service 應用程式
• 在 Azure App Service 中設定預備環境

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

設定進程的環境變數

若要在 ASPNETCORE_ENVIRONMENT 使用 dotnet run啟動應用程式時設定目前工作階段 （命令 shell） 的環境變數，請使用下列命令。 設定環境變數之後，會使用選項 --no-launch-profile 啟動應用程式，而不使用啟動設定檔。

1. 在命令 shell 中，使用適合您作業系統的方法設定環境變數。

2. 在不使用啟動設定檔的情況下執行 dotnet run 命令：

   dotnet run --no-launch-profile
   

使用 PowerShell 時，上述步驟可以結合在下列兩個命令中。 下列範例會設定中繼環境：

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

全域設定環境變數

使用作業系統的適當指引來設定 ASPNETCORE_ENVIRONMENT 環境變數。

當將ASPNETCORE_ENVIRONMENT環境變數設為全域變數時，在設置值後開啟的任何命令 shell 中，dotnet run命令將生效。 launch profiles 在 launchSettings.json 檔案中設定的環境值會替換系統環境設定的值。

設定部署至 IIS 的應用程式環境

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

若要將部署時的環境變數設定為 IIS，請在<EnvironmentName> 或專案檔中包含屬性。 下列範例會在發佈專案時將環境 web.config 設定為暫存環境：

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

若要設定 ASPNETCORE_ENVIRONMENT 在隔離應用程式集區中執行的應用程式的環境變數 （IIS 10.0 或更新版本支援），請參閱 環境變數 <environmentVariables>。 為應用程式集區設定ASPNETCORE_ENVIRONMENT環境變數時，其值會覆寫系統層級的設定。

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

• 在命令 shell 中依次執行 net stop was /y 和 net start w3svc。
• 重新啟動伺服器。

Docker

使用本節中的任何方法設定應用程式的環境。

使用 Dockerfile

使用以下ASPNETCORE_ENVIRONMENT指令在 Dockerfile 中設定ENV環境變數：

ENV ASPNETCORE_ENVIRONMENT=Staging

使用 Docker Compose

對於使用 Docker Compose 管理的多服務應用程式，請在檔案中ASPNETCORE_ENVIRONMENT定義docker-compose.yml環境變數：

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

使用 Docker Compose 在執行時設定的環境會覆蓋由 Dockerfile 設定的環境。

使用命令 docker run

在使用命令docker run執行 Docker 容器時，請使用ASPNETCORE_ENVIRONMENT選項設定-e|--env環境變數。

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

在執行階段 docker run 設定的環境會覆寫 Dockerfile 所設定的環境。

Docker 環境檔案

使用 Docker 環境文件 ASPNETCORE_ENVIRONMENT 設定 .env 環境變數。

env_variables.env：

ASPNETCORE_ENVIRONMENT=Staging

執行--env-file時，使用選項docker run載入檔案：

docker run --env-file ./env_variables.env aspnet_core_image

在執行階段 docker run 設定的環境會覆寫 Dockerfile 所設定的環境。

在應用程式的啟動程式碼中設定環境

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

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

依環境載入設定

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

從 Startup 類別存取環境

在 .NET 6 發行之前，需要使用 Startup 類別 （Startup.cs） 搭配 Configure 和 ConfigureServices 方法，而且仍受支援。

將 IWebHostEnvironment 注入 Startup 建構函式以控制程式碼執行。 當應用程式只需要為少數環境設定啟動程式碼，且各環境之間的程式碼差異微小時，此方法很有用。

在下列範例中，環境會保留在欄位中 _env ，並根據應用程式的環境控制程式碼執行：

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

環境特定 Startup 類別

應用程式可以使用命名慣例Startup類別為不同的環境定義多個Startup{EnvironmentName}類別，其中{ENVIRONMENT NAME}預留位置是環境名稱。

將優先使用其名稱尾碼符合目前環境的類別。 如果找不到相符的 Startup{EnvironmentName} 類別，會使用 Startup 類別。

若要實作環境型 Startup 類別，請根據需求建立任意數量的 Startup{EnvironmentName} 類別，並包含一個預設的 Startup 類別：

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

在建立主機建置器的位置，呼叫 HostingAbstractionsWebHostBuilderExtensions.UseStartup，它接受元件名稱來載入正確的 Startup 類別：

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

環境特定的 Startup 類別方法

Configure和ConfigureServices方法支援Configure{ENVIRONMENT NAME}和Configure{ENVIRONMENT NAME}Services形式的環境特定版本，其中{ENVIRONMENT NAME}是環境名稱的佔位符。 如果找不到具名方法的相符環境名稱，則使用 ConfigureServices 或 Configure 方法。

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

其他資源

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