ASP.NET Core Blazor 環境

本文說明如何在 Blazor 應用程式中設定和讀取 環境。

在本機執行應用程式時，環境預設為 Development。 發佈應用程式時，環境預設為 Production。

我們建議使用下列慣例：

• 總是使用「Development」環境名稱進行本機開發。 這是因為在設定應用程式和其本機開發執行工具時，ASP.NET Core 架構要求使用確切的名稱。

• 針對測試、預備和生產環境，請一律發佈及部署應用程式。 您可以使用任何您想要用於已發佈的應用程式的環境命名方案，但必須一律使用應用程式設定檔案名稱，其中環境區段的大小寫必須完全符合環境名稱。 針對暫存環境，請使用「Staging」 （大寫「S」）作為環境名稱，並將應用程式設定檔命名為符合（appsettings.Staging.json）。 針對生產環境，請使用 "Production"（大寫 "P"）作為環境名稱，並將應用程式設定檔命名為符合 "appsettings.Production.json"。

設定環境

針對在本機執行的獨立 Blazor WebAssembly 應用程式，開發伺服器會新增 Blazor-Environment 標頭，其中包含從裝載環境取得的環境名稱。 裝載環境會從專案的 Properties/launchSettings.json 檔案所建立的 ASPNETCORE_ENVIRONMENT 環境變數中設定環境。 從 Blazor WebAssembly 項目樣本建立之項目中環境變數的預設值為 Development。 如需進一步資訊，請參閱「透過標頭設定用戶端環境」的部分。

針對在開發中本機執行的應用程式，應用程式預設為 Development 環境。 發佈應用程式會將環境預設為 Production。

透過 Blazor 啟動組態設定客戶端環境

如果主機名包含 localhost，下列範例會在 Staging 環境中啟動 Blazor。 否則，環境會設定為其預設值。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

在上述範例中，{BLAZOR SCRIPT} 佔位元是 Blazor 腳本路徑和檔名。 如需腳本的位置，請參閱 ASP.NET Core Blazor 專案結構。

使用 environment 屬性會覆寫 Blazor-Environment 標頭所設定的環境。

上述方法會設定客戶端的環境，而不變更 Blazor-Environment 標頭的值，也不會變更伺服器專案中記錄啟動環境的控制台記錄設定，對於已經採用全域 Interactive WebAssembly 渲染的 Blazor Web App。

若要在獨立 Blazor WebAssembly 專案或 Blazor Web App的 .Client 專案中將環境記錄到主控台，請在使用 WebAssemblyHostBuilder.CreateDefault 建立 WebAssemblyHost 之後，於建置並執行專案的行 (await builder.Build().RunAsync();) 之前，將下列 C# 程式碼放入 Program 檔案中。

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

如需有關 Blazor 啟動的詳細資訊，請參閱 ASP.NET Core Blazor 啟動。

透過標頭設定客戶端環境

Blazor WebAssembly 應用程式可以使用 Blazor-Environment 標頭來設定環境。 具體來說，必須在 _framework/blazor.boot.json 檔案上設置回應標頭，但在其他 Blazor 檔案請求或整個 Blazor 部署的檔案伺服器回應中設置這些標頭並不會造成任何問題。

雖然 Blazor 架構在連字號串燒式大小寫中發出標頭名稱與混合字母大小寫（Blazor-Environment），但歡迎使用全小寫或全大寫的連字號串燒式大小寫（blazor-environment，BLAZOR-ENVIRONMENT）。

使用 Blazor的內建開發伺服器進行本機開發時，您可以在專案的 Properties/launchSettings.json 檔案中設定 ASPNETCORE_ENVIRONMENT 環境變數的值，以控制 Blazor-Environment 標頭的值。 使用開發伺服器在本機執行時，判斷應用程式環境的優先順序是 Blazor.start 組態（environment 索引鍵）>Blazor-Environment 回應標頭（blazor.boot.json 檔案）>ASPNETCORE_ENVIRONMENT 環境變數（launchSettings.json）。 您無法針對已部署 Blazor WebAssembly 應用程式使用 ASPNETCORE_ENVIRONMENT 環境變數 （launchSettings.json） 方法。 這項技術只適用於在本地運行應用程式時的開發伺服器。

IIS

在下列 IIS 範例中，自定義標頭 （Blazor-Environment） 會新增至已發佈的 web.config 檔案。 web.config 檔案位於 bin/Release/{TARGET FRAMEWORK}/publish 資料夾中，其中 {TARGET FRAMEWORK} 占位元符是目標架構：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    ...
    <httpProtocol>
      <customHeaders>
        <add name="Blazor-Environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Nginx

針對 Nginx 伺服器，請使用來自 ngx_http_headers_module的 add_header 指令：

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

如需詳細資訊，請參閱下列資源：

• Nginx 文件
• Blazor WebAssembly Nginx 裝載指引

Apache

針對 Apache 伺服器，請使用來自 mod_headers 模組的 Header 指示詞：

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

如需詳細資訊：

• Apache 文件（搜尋最新版本的 “mod_headers”）
• Blazor WebAssembly Apache 主機設定指引

設定 Azure App Service 的環境

針對獨立 Blazor WebAssembly 應用程式，您可以透過 啟動組態 或 Blazor-Environment 標頭手動設定環境。

針對伺服器端應用程式，透過 Azure 中的 ASPNETCORE_ENVIRONMENT 應用程式設定來設定環境：

1. 確認應用程式設定檔名中的環境區段大小寫完全符合其環境名稱大小寫。 例如，Staging 環境的相符應用程式設定檔名稱 appsettings.Staging.json。 如果檔名是 appsettings.staging.json（小寫 “s”），則檔案未找到，而且檔案中的設定不會用於 Staging 環境中。

2. 針對 Visual Studio 部署，確認應用程式已部署到正確的部署位置。 針對名為 BlazorAzureAppSample的應用程式，應用程式會部署到 Staging 部署位置。

3. 在環境部署位置的 Azure 入口網站中，使用 ASPNETCORE_ENVIRONMENT 應用程式設定來設定環境。 針對名為 BlazorAzureAppSample的應用程式，暫存 App Service 插槽會命名為 BlazorAzureAppSample/Staging。 針對 Staging 槽的組態，為 ASPNETCORE_ENVIRONMENT 建立一個應用程式設定，並將其值設定為 Staging。 部署時段設定 已針對該設定啟用。

當在瀏覽器中請求時，BlazorAzureAppSample/Staging 應用程式會在 Staging 環境中載入於 https://blazorazureappsample-staging.azurewebsites.net。

在瀏覽器中載入應用程式時，blazor.boot.json 的回應標頭集合顯示，Blazor-Environment 的標頭值是 Staging。

應用程式會載入來自 appsettings.{ENVIRONMENT}.json 檔案的應用程式設定，其中 {ENVIRONMENT} 占位元是應用程式的環境。 在上述範例中，會載入來自 appsettings.Staging.json 檔案的設定。

在 Blazor WebAssembly 應用程式中讀取環境

藉由插入 IWebAssemblyHostEnvironment 並讀取 Environment 屬性，以取得元件中的應用程式環境。

ReadEnvironment.razor：

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

在啟動期間讀取客戶端環境

在啟動期間，WebAssemblyHostBuilder 會透過 HostEnvironment 屬性公開 IWebAssemblyHostEnvironment，以啟用主機產生器程式代碼中的環境特定邏輯。

在 Program 檔案中：

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

透過 WebAssemblyHostEnvironmentExtensions 提供的下列便利擴充方法，可以檢查目前環境是否包含 Development、Production、Staging和自定義環境名稱：

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

在 Program 檔案中：

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

NavigationManager 服務無法使用時，可以在啟動期間使用 IWebAssemblyHostEnvironment.BaseAddress 屬性。

其他資源

• ASP.NET Core Blazor 啟動
• 在 ASP.NET Core 中使用多個環境
• Blazor 範例 GitHub 存放庫 （dotnet/blazor-samples） （如何下載）