ASP.NET Core Blazor 环境
注意
此版本不是本文的最新版本。 对于当前版本,请参阅此文的 .NET 8 版本。
警告
此版本的 ASP.NET Core 不再受支持。 有关详细信息,请参阅 .NET 和 .NET Core 支持策略。 对于当前版本,请参阅此文的 .NET 8 版本。
本文介绍如何在 Blazor 应用中配置和读取环境。
在本地运行应用时,环境默认为 Development
。 发布应用时,环境默认为 Production
。
建议使用以下约定:
始终使用“
Development
”环境名称进行本地开发。 这是因为,在为应用的本地开发运行配置应用和工具时,ASP.NET Core 框架确切需要该名称。对于测试、暂存和生产环境,请始终发布和部署应用。 可以使用希望用于已发布应用的任何环境命名方案,但始终使用应用设置文件名,环境段的大小写应与环境名称完全匹配。 对于暂存,请使用“
Staging
”(大写“S”)作为环境名称,并命名要匹配的应用设置文件 (appsettings.Staging.json
)。 对于生产,请使用“Production
”(大写“P”)作为环境名称,并命名要匹配的应用设置文件 (appsettings.Production.json
)。
设置环境
使用以下方法之一来设置环境:
- Blazor Web 应用:对常规 ASP.NET Core 应用使用在 ASP.NET Core 中使用多个环境中所述的任何方法。
- Blazor Web 应用或独立 Blazor WebAssembly:Blazor 启动配置
- 独立 Blazor WebAssembly:
blazor-environment
标头 - Blazor Web 应用或独立 Blazor WebAssembly:Azure 应用服务
在 Blazor Web 应用的客户端上,环境由服务器通过中间件确定,而中间件通过名为 blazor-environment
的标头使环境与浏览器通信。 该标头会在 WebAssemblyHost 于客户端侧 Program
文件 (WebAssemblyHostBuilder.CreateDefault) 中创建时设置环境。
使用以下方法之一来设置环境:
- Blazor Server:对常规 ASP.NET Core 应用使用在 ASP.NET Core 中使用多个环境中所述的任何方法。
- Blazor Server 或 Blazor WebAssembly:Blazor 启动配置
- Blazor WebAssembly:
blazor-environment
标头 - Blazor Server 或 Blazor WebAssembly:Azure 应用服务
在 Blazor Web 应用的客户端或托管的 Blazor WebAssembly 应用的客户端上,环境通过中间件从服务器确定,中间件通过名为 blazor-environment
的标头使环境与浏览器通信。 该标头会在 WebAssemblyHost 于客户端侧 Program
文件 (WebAssemblyHostBuilder.CreateDefault) 中创建时设置环境。
对于在本地运行的独立 Blazor WebAssembly 应用,开发服务器会添加 blazor-environment
标头。
对于在开发环境中本地运行的应用,应用默认为 Development
环境。 将应用默认环境发布到 Production
。
有关 ASP.NET Core 应用配置的一般指南,请参阅在 ASP.NET Core 中使用多个环境。 有关开发和测试期间 Development 环境以外的环境中静态文件的服务器端应用配置(例如 Staging),请参阅 ASP.NET Core Blazor 静态文件。
通过 Blazor 启动配置设置客户端环境
如果主机名包含 localhost
,则下面的示例在 Staging
环境中启动 Blazor。 否则,环境将设置为其默认值。
Blazor Web 应用:
<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 应用,最好将服务器端环境与 environment
属性上设置的环境匹配。 否则,服务器上的预呈现将在不同于客户端呈现的环境中运行,这会导致任意影响。 有关为 Blazor Web 应用设置环境的一般指导,请参阅在 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 应用,也不会更改启动环境的服务器项目控制台日志记录。
若要将环境记录到独立 Blazor WebAssembly 项目或 Blazor Web 应用的 .Client
项目中的控制台,请将以下 C# 代码放在 Program
文件中(使用 WebAssemblyHostBuilder.CreateDefault 创建 WebAssemblyHost 之后,生成并运行项目的行 (await builder.Build().RunAsync();
) 之前):
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
应用设置设置环境:
确认应用设置文件名中环境段的大小写与其环境名称大小写完全匹配。 例如,
Staging
环境匹配的应用设置文件名为appsettings.Staging.json
。 如果文件名为appsettings.staging.json
(小写的“s
”),则不会找到该文件,并且不会在Staging
环境中使用该文件中的设置。对于 Visual Studio 部署,请确认应用已部署到正确的部署槽位。 对于名为
BlazorAzureAppSample
的应用,会部署到Staging
部署槽位。在 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 应用中读取环境客户端
假设未为组件或应用禁用预呈现,则 .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 应用中设置环境时,最好匹配服务器和 .Client
项目环境。 在测试应用中考虑以下方案:
- 通过
Blazor.start
使用Staging
环境实现客户端 (webassembly
) 环境属性。 有关示例,请参阅通过启动配置设置客户端环境部分。 - 请勿更改服务器端
Properties/launchSettings.json
文件。 保留environmentVariables
部分,并将ASPNETCORE_ENVIRONMENT
环境变量设置为Development
。
可以在 UI 中查看 IWebAssemblyHostEnvironment.Environment 属性更改的值。
在服务器上预呈现时,组件将在 Development
环境中呈现:
Environment: Development
在下载 Blazor 捆绑包并激活 Blazor WebAssembly 运行时后,当组件重新呈现一两秒后,值会发生变化,以反映客户端正在客户端的 Staging
环境中运行:
Environment: Staging
前面的示例演示了为什么我们建议将服务器环境设置为与用于开发、测试和生产部署的客户端环境相匹配。
有关详细信息,请参阅稍后出现在 Blazor 文档中的呈现模式文章的客户端服务在预呈现期间无法解决部分。
在启动时读取客户端环境
在启动过程中,WebAssemblyHostBuilder 会通过 HostEnvironment 属性公开 IWebAssemblyHostEnvironment,这会在主机生成器代码中启用环境特定的逻辑。
在 Program
文件中:
if (builder.HostEnvironment.Environment == "Custom")
{
...
};
使用通过 WebAssemblyHostEnvironmentExtensions 提供的下列便捷扩展方法,可在当前环境中检查 Development
、Production
、Staging
和自定义环境名称:
在 Program
文件中:
if (builder.HostEnvironment.IsStaging())
{
...
};
if (builder.HostEnvironment.IsEnvironment("Custom"))
{
...
};
如果 NavigationManager 服务不可用,则启动期间可使用 IWebAssemblyHostEnvironment.BaseAddress 属性。
其他资源
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈