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 应用服务

在 Blazor Web App 的客户端上，环境通过中间件从服务器确定，而中间件通过名为 blazor-environment 的标头使环境与浏览器通信。 该标头会在 WebAssemblyHost 于客户端侧 Program 文件 (WebAssemblyHostBuilder.CreateDefault) 中创建时设置环境。

对于在本地运行的独立 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.start 配置中设置 webAssembly>environment 属性的 Blazor Web App，最好使服务器端环境与 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 项目结构。

使用 environment 属性将替代 blazor-environment 标头设置的环境。

上述方法设置客户端的环境，而不会更改 blazor-environment 标头的值，对于已采用全局交互式 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 标头设置环境。

在下面的 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>

注意

若要为 IIS 使用一个自定义 web.config 文件，并且它在应用发布到 publish 文件夹时不会被覆盖，请参阅托管和部署 ASP.NET Core Blazor WebAssembly。

尽管 Blazor 框架以全部小写字母 (blazor-environment) 发出标头名称，但欢迎使用所需的任何大小写。 例如，支持将每个单词大写的标头名称 (Blazor-Environment)。

设置 Azure 应用服务的环境

对于独立的 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 的应用，暂存应用服务槽命名为 BlazorAzureAppSample/Staging。 对于 Staging 槽的配置，请通过值 Staging 为 ASPNETCORE_ENVIRONMENT 创建应用设置。 为设置启用了部署槽位设置。

在浏览器中请求时，BlazorAzureAppSample/Staging 应用会在 https://blazorazureappsample-staging.azurewebsites.net 的 Staging 环境中加载。

在浏览器中加载应用时，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。

可以在 UI 中查看 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)（下载方法）