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

作者 :Rick AndersonKirk Larkin

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

環境

若要判斷執行時間環境,ASP.NET Core從下列環境變數讀取:

  1. DOTNET_ENVIRONMENT
  2. ASPNETCORE_ENVIRONMENTWebApplication.CreateBuilder呼叫 方法時。 預設 ASP.NET Core Web 應用程式範本呼叫 WebApplication.CreateBuilder 。 值 ASPNETCORE_ENVIRONMENTDOTNET_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>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 環境變數和值預設會區分大小寫。

建立環境範例

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

下列 .NET CLI 命令會建立並執行名為 EnvironmentSample的 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

開發和 launchSettings.json

您可以在開發環境中啟用生產環境不應該公開的功能。 例如,ASP.NET Core專案範本會在開發環境中啟用開發人員例外狀況頁面

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

launchSettings.json 檔案:

  • 僅用於本機開發電腦上。
  • 未部署。
  • 包含設定檔設定。

下列 JSON 顯示 launchSettings.json 名為EnvironmentSample的 ASP.NET Core Web 專案檔案,此專案是以 Visual Studio 或 dotnet new 建立:

{
  "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 launch on menu

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

  • IISExpress:啟動IIS Express。
  • IIS :未啟動網頁伺服器。 IIS 預期可供使用。
  • Project :啟動 Kestrel 。

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

Project Properties Setting Environment variables

下列 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 "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使用。

生產

生產環境應設定為最大化安全性、 效能和應用程式健全性。 不同於開發的某些一般設定包括:

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

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

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

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

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

Azure App Service

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

若要使用入口網站在Azure App 服務應用程式中設定環境:

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

Azure App 服務在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 中以全域的方式設定值,請使用下列其中一個方法:

  • 開啟主控台>SystemAdvanced> 系統設定,然後新增或編輯 ASPNETCORE_ENVIRONMENT 值:

    System Advanced Properties

    ASPNET Core Environment Variable

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

<EnvironmentName> 屬性包含在 發行設定檔 (.pubxml) 或專案檔中。 此方法會在專案發行時於 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 中的 .NET 泛型主機

取決於環境的組態

若要依環境載入設定,請參閱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 應用程式範本會呼叫 ConfigureWebHostDefaults 。 值 ASPNETCORE_ENVIRONMENTDOTNET_ENVIRONMENT 覆寫 。

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

下列程式碼:

  • 當 設定為 DevelopmentASPNETCORE_ENVIRONMENT 呼叫 UseDeveloperExceptionPage
  • 當 的值 ASPNETCORE_ENVIRONMENT 設定為 StagingProductionStaging_2 時呼叫 UseExceptionHandler
  • 插入 IWebHostEnvironmentStartup.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 的Pages 專案為基礎 Razor 。

下列程式碼會建立並執行名為 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 顯示 launchSettings.json 名為EnvironmentSample的 ASP.NET Core Web 專案檔案,此專案是使用 Visual Studio 或 dotnet new 所建立:

{
  "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 launch on menu

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

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

  • IISExpress:啟動IIS Express。
  • IIS :未啟動網頁伺服器。 IIS 預期可供使用。
  • Project :啟動 Kestrel 。

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

Project Properties Setting Environment variables

下列 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使用。

生產

生產環境應設定為最大化安全性、 效能和應用程式健全性。 不同於開發的某些一般設定包括:

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

設定環境

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

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

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

Azure App Service

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

若要在 Azure App Service 設定環境,請執行下列步驟:

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

Azure App 服務在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 中以全域的方式設定值,請使用下列其中一個方法:

  • 開啟主控台>SystemAdvanced> 系統設定,然後新增或編輯 ASPNETCORE_ENVIRONMENT 值:

    System Advanced Properties

    ASPNET Core Environment Variable

  • 開啟系統管理命令提示字元,然後使用 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 部署:<EnvironmentName>發行設定檔中包含 屬性, (.pubxml) 或專案檔。 此方法會在專案發行時於 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會用於 和 Configure ,以根據應用程式的環境套用 ConfigureServices 啟動組態。
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 方法慣例

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

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}");
    }
}

其他資源