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 标头，其中包含从托管环境获取的环境名称。 托管环境根据项目的 Properties/launchSettings.json 文件建立的 ASPNETCORE_ENVIRONMENT 环境变量设置环境。 从 Blazor WebAssembly 项目模板创建的项目中环境变量的默认值 Development。 有关详细信息，请参阅通过标头设置客户端环境部分。

对于在开发中本地运行的应用，应用默认为 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 标头设置环境。 具体而言，必须在 _framework/blazor.boot.json 文件上设置响应标头，但对于其他 Blazor 文件请求或整个 Blazor 部署，在文件服务器响应上设置标头不会造成任何损害。

尽管 Blazor 框架以混合字母大小写 (Blazor-Environment) 的 kebab 大小写形式发出标头名称，但欢迎使用全小写或全大写的 kebabe 大小写（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>

注意

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

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

对于 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）（如何下载）