ASP.NET Core Blazor 環境

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

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

我們建議下列慣例：

• 請一律針對本機開發使用「Development」環境名稱。 這是因為 ASP.NET Core 架構在設定應用程式及應用程式本機開發執行的工具時，會預期是該名稱。

• 針對測試、暫存和實際執行環境，請一律發佈及部署應用程式。 您可以使用任何您想要用於已發佈應用程式的環境命名配置，但一律使用環境區段大小寫與環境名稱完全相符的應用程式設定檔案名稱。 針對暫存，使用「Staging」(大寫「S」) 作為環境名稱，並且為應用程式設定檔案命名以符合 (appsettings.Staging.json)。 針對實際執行環境，使用「Production」(大寫「P」) 作為環境名稱，並且為應用程式設定檔案命名以符合 (appsettings.Production.json)。

設定環境

會使用下列任何一種方法來設定環境:

• Blazor Web App：針對一般 ASP.NET Core 應用程式使用在 ASP.NET Core 中使用多個環境中所述的任何方法。
• Blazor Web App 或獨立 Blazor WebAssembly：Blazor 啟動設定
• 獨立 Blazor WebAssembly：blazor-environment 標頭
• Blazor Web App 或獨立 Blazor WebAssembly：Azure App Service

在 Blazor Web App Web 應用程式的用戶端上，環境會透過中介軟體從伺服器決定，而中介軟體會透過名為 blazor-environment 的標頭讓環境與瀏覽器通訊。 標頭在用戶端 Program 檔案 (WebAssemblyHostBuilder.CreateDefault) 中建立 WebAssemblyHost 時會設定環境。

針對在本機執行的獨立 Blazor WebAssembly 應用程式，開發伺服器會新增 blazor-environment 標頭。

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

透過 Blazor 啟動設定來設定用戶端環境

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

Blazor Web App：

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

在上述範例中，{BLAZOR SCRIPT} 預留位置是 Blazor 指令碼路徑和檔案名稱。 如需指令碼的位置，請參閱 ASP.NET Core Blazor 專案結構。

注意

對於Blazor Web App 來說將屬性 webAssembly>environment 在 Blazor.start 設定中設定 ，伺服器端的環境與 environment 屬性上設定的環境相匹配是明智的。 否則，在伺服器上預先轉譯會在不同於用戶端轉譯的環境中運作，這會導致任意效果。 如需設定 Blazor Web App 環境的一般指引，請參閱 Use multiple environments in ASP.NET Core。

獨立 Blazor WebAssembly：

<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 標頭的值，也沒有改變伺服器專案的控制台記錄啟動環境的 Blazor Web App 已經採用全域互動式 WebAssembly 轉譯的環境。

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

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

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

透過標頭設定用戶端環境

Blazor WebAssembly 應用程式可以使用 blazor-environment 標頭來設定環境。

在下列 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>

注意

若要針對應用程式發佈至 publish 資料夾時不會覆寫的 IIS 使用自訂的 web.config 檔案，請參閱 主持及部署 ASP.NET CoreBlazor WebAssembly。

雖然 Blazor 架構會全部以小寫字母發出標頭名稱 (blazor-environment)，但是您可以使用任意大小寫。 例如，支援每個單字大寫的標頭名稱 (Blazor-Environment)。

設定 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 位置的設定，使用 Staging 的值建立 ASPNETCORE_ENVIRONMENT 的應用程式設定。 已針對設定啟用部署位置設定。

在瀏覽器中要求時，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>

在 Blazor Web App 中讀取環境用戶端

假設元件或應用程式未停用預先轉譯，則 .Client 專案中的元件會在伺服器上預先轉譯。 因為伺服器沒有已註冊的 IWebAssemblyHostEnvironment 服務，所以無法在伺服器預先轉譯期間插入服務，並使用服務實作的主機環境擴充方法和屬性。 將服務插入互動式 WebAssembly 或互動式自動元件會導致下列執行階段錯誤：

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

若要解決此問題，請在伺服器上建立 IWebAssemblyHostEnvironment 的自訂服務實作。 將下列類別新增至伺服器專案。

ServerHostEnvironment.cs：

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

在伺服器專案的 Program 檔案中，註冊服務：

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

此時，IWebAssemblyHostEnvironment 服務可以插入互動式 WebAssembly 或互動式自動元件並且加以使用，如同在 Blazor WebAssembly 應用程式中讀取環境一節中所示。

上述範例可以示範可以擁有不同於用戶端環境的伺服器環境，但不建議這麼做，這麼做可能會導致任意結果。 在 Blazor Web App 中設定環境時，伺服器與 .Client 專案環境最好能相符。 在測試應用程式中考慮下列狀況：

• 透過 Blazor.start 使用 Staging 環境實作用戶端 (webassembly) 環境。 如需範例，請參閱透過啟動設定來設定用戶端環境一節。
• 請勿變更伺服器端 Properties/launchSettings.json 檔案。 保留 environmentVariables 區段中將 ASPNETCORE_ENVIRONMENT 環境變數設定為 Development。

您可以在使用者介面中看到 IWebAssemblyHostEnvironment.Environment 屬性值變更。

在伺服器上發生預先轉譯時，元件會在 Development 環境中轉譯：

Environment: Development

當元件在轉譯僅一兩秒後，下載 Blazor 搭售方案並啟動 .NET WebAssembly 執行階段之後，值就會變更以反映用戶端正在用戶端上 Staging 環境中運作：

Environment: Staging

上述範例示範為何建議將伺服器環境設定為符合開發、測試和生產部署的用戶端環境。

如需詳細資訊，請參閱轉譯模式一文的預先轉譯期間用戶端服務無法解析一節，該文章稍後會出現在 Blazor 文件中。

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

在啟動期間，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) (如何下載)