ASP.NET Core Blazor 環境

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

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

我們建議使用下列慣例：

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

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

設定環境

環境是使用下列任何一種方法來設定：

• Blazor Web App 或 Blazor Server：針對一般 ASP.NET Core 應用程式使用 ASP.NET Core 執行階段環境中 所述的任何方法。
• 任何 Blazor 應用程式： Blazor 啟動設定
• 獨立 Blazor WebAssembly：<WasmApplicationEnvironmentName> 屬性

在 Blazor Web App 客戶端上，環境是透過開發人員不需互動的 HTML 註解，從伺服器判斷。

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

對於獨立 Blazor WebAssembly 應用程式，請在應用程式的專案檔案中使用 <WasmApplicationEnvironmentName> MSBuild 屬性設定環境 （.csproj）。 下列範例會設定 Staging 環境：

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

默認環境適用於 Development 建置和 Production 發佈。

在建置/發佈操作中，有多種設定獨立 Blazor WebAssembly 應用程式環境的方法，以及一種用於應用程式在用戶端啟動或執行的方法：

• 當dotnet build或dotnet publish執行時設定屬性值。 以下範例在 app 發佈時將環境設定為 Staging:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• 在建置或發佈時，根據 Visual Studio 應用程式的設定設定屬性。 以下屬性群組可用於應用程式的專案檔案或任何發佈設定檔（.pubxml）。 為其他正在使用的建構配置新增屬性群組。

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• 可依據發佈設定檔的使用來設定環境。 以下範例中，第一個條件在沒有使用發佈設定檔時將環境設為 Development（適用於未使用設定檔的建置與發佈操作），而第二個條件則在使用任何發佈設定檔時將環境設為 Production。

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• 建立一個自訂的伺服器端網頁 API 端點。 獨立 Blazor WebAssembly 應用程式會在應用程式啟動時或在運行期間按需，向網頁 API 請求其環境。 該值應傳遞給WebAssemblyStartOptions或withApplicationEnvironment。

  注意

  通常，指向 .NET 參考來源的文件連結會載入存放庫的預設分支，這代表 .NET 下一版本的最新開發進度。 若要選取特定發行版本的標籤，請使用「切換分支或標籤」下拉式清單。 如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。

針對在開發階段於本地執行的應用程式，應用程式預設至 Development 環境。 發佈應用程式會將環境預設為 Production。

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

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

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 的一般指南，請參閱 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 專案結構。

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

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

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

在 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 服務，所以無法在伺服器預先呈現期間插入服務，並使用服務實作的主機環境擴充方法和屬性。 將服務插入 Interactive WebAssembly 或 Interactive Auto 元件會導致下列運行時間錯誤：

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

若要解決此問題，請在伺服器上建立 IWebAssemblyHostEnvironment 的自定義服務實作。 如需詳細資訊和實作範例，請參閱伺服器上的自訂服務實作章節的預先轉譯文章，該章節稍後會出現在文件中Blazor。

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

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

在 Program 檔案中：

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

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

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

在 Program 檔案中：

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

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

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

其他資源

• ASP.NET Core Blazor 啟動
• ASP.NET 核心執行階段環境
• Blazor 範例 GitHub 存放庫 （dotnet/blazor-samples） （如何下載）