共用方式為


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

注意

這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本

警告

不再支援此版本的 ASP.NET Core。 如需詳細資訊,請參閱 .NET 和 .NET Core 支援原則。 如需目前版本,請參閱本文的 .NET 8 版本

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。

如需目前版本,請參閱本文的 .NET 8 版本

作者:Rick AndersonKirk Larkin

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

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

環境

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

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT,呼叫 WebApplication.CreateBuilder 方法時。 預設 ASP.NET Core Web 應用程式範本呼叫 WebApplication.CreateBuilderASPNETCORE_ENVIRONMENT 值會覆寫 DOTNET_ENVIRONMENT

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

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

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

下列程式碼範例:

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 網頁伺服器

功能表上的 IIS Express 啟動

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_ENVIRONMENTASPNETCORE_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 值:

    系統進階屬性

    ASPNET Core 環境變數

  • 開啟系統管理命令提示字元,然後使用 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 w3svcnet 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.EnvironmentWebApplication.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

其他資源

作者:Rick AndersonKirk Larkin

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

環境

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

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENT,呼叫 ConfigureWebHostDefaults 時。 預設 ASP.NET Core Web 應用程式範本呼叫 ConfigureWebHostDefaultsASPNETCORE_ENVIRONMENT 值會覆寫 DOTNET_ENVIRONMENT

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

下列程式碼範例:

  • ASPNETCORE_ENVIRONMENT 設定為 Development 時呼叫 UseDeveloperExceptionPage
  • ASPNETCORE_ENVIRONMENT 的值設定為 StagingProductionStaging_2 時呼叫 UseExceptionHandler
  • IWebHostEnvironment 插入 Startup.Configure。 當應用程式只需要針對幾個環境調整 Startup.Configure,且每個環境的程式碼差異很少時,此方法就很有用。
  • 類似於 ASP.NET Core 範本所產生的程式碼。
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))
    {
        app.UseExceptionHandler("/Error");
    }

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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

<environment include="Development">
    <div>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,Staging_2">
    </div>
</environment>

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

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

建立 EnvironmentsSample

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

下列程式碼會建立並執行名為 EnvironmentsSample 的 Web 應用程式:

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

當應用程式執行時,它會顯示下列一些輸出:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

上述標記包含兩個設定檔:

  • IIS Express:從 Visual Studio 啟動應用程式時使用的預設設定檔。 "commandName" 索引鍵具有值 "IISExpress",因此 IISExpress 是網頁伺服器。 您可以將啟動設定檔設定為專案或包含的任何其他設定檔。 例如,在下圖中,選取專案名稱會啟動 Kestrel 網頁伺服器

    功能表上的 IIS Express 啟動

  • EnvironmentsSample:設定檔名稱是專案名稱。 使用 dotnet run 啟動應用程式 時,預設會使用此設定檔。 "commandName" 索引鍵具有值 "Project",因此會啟動 Kestrel 網頁伺服器

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

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

Visual Studio 專案屬性的 [偵錯] 索引標籤提供 GUI,可編輯 launchSettings.json 檔案。 您對專案設定檔所做的變更可能要等重新啟動網頁伺服器後才會生效。 您必須重新啟動 Kestrel,它才會偵測到對環境進行的變更。

專案屬性設定環境變數

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

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

可以選取設定檔:

  • 從 Visual Studio UI。

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

    dotnet run --launch-profile "SampleApp"
    

警告

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_ENVIRONMENTASPNETCORE_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

命令提示字元

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

PowerShell

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

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

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

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

    系統進階屬性

    ASPNET Core 環境變數

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

    命令提示字元

    setx ASPNETCORE_ENVIRONMENT Staging /M
    

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

    PowerShell

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

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

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

web.config

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

專案檔或發行設定檔

針對 Windows IIS 部署:在 [發行設定檔 (.pubxml)] 或專案檔中包含 <EnvironmentName> 屬性。 此方法會在專案發行時於 web.config 中設定環境:

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

每個 IIS 應用程式集區

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

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

  • 從命令提示字元執行後面接著 net start w3svcnet 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 檔案,進行機器層級的環境設定。

在程式碼中設定環境

建置主機時呼叫 UseEnvironment。 請參閱 ASP.NET Core 中的 .NET 泛型主機

取決於環境的組態

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

以環境為基礎的 Startup 類別和方法

將 IWebHostEnvironment 插入 Startup 類別

IWebHostEnvironment 插入 Startup 建構函式。 當應用程式只需要針對幾個環境設定 Startup,且每個環境的程式碼差異很少時,此方法就很有用。

在以下範例中:

  • 環境會保留在 _env 欄位中。
  • _env 會用於 ConfigureServicesConfigure 中,以根據應用程式的環境套用啟動設定。
public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Startup 類別慣例

ASP.NET Core 應用程式啟動時,Startup 類別會啟動應用程式。 應用程式可以針對不同的環境定義多個 Startup 類別。 在執行階段選取適當的 Startup 類別。 將優先使用其名稱尾碼符合目前環境的類別。 如果找不到相符的 Startup{EnvironmentName} 類別,會使用 Startup 類別。 當應用程式需要為數個環境設定啟動,且每個環境有許多程式碼差異時,此方法很有用。 一般應用程式不需要此方法。

若要實作環境型 Startup 類別,請建立 Startup{EnvironmentName} 類別和後援 Startup 類別:

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

使用會接受組件名稱的 UseStartup(IWebHostBuilder, String) 多載:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

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

Startup 方法慣例

ConfigureConfigureServices 支援表單 Configure<EnvironmentName>Configure<EnvironmentName>Services 的環境特定版本。 如果找不到相符的 Configure<EnvironmentName>ServicesConfigure<EnvironmentName> 方法,則會分別使用 ConfigureServicesConfigure 方法。 當應用程式需要為數個環境設定啟動,且每個環境有許多程式碼差異時,此方法很有用:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

其他資源