ASP.NET Core Blazor environments
Notitie
This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.
Waarschuwing
This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.
Belangrijk
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 9 version of this article.
This article explains how to configure and read the environment in a Blazor app.
When running an app locally, the environment defaults to Development
. When the app is published, the environment defaults to Production
.
We recommend the following conventions:
Always use the "
Development
" environment name for local development. This is because the ASP.NET Core framework expects exactly that name when configuring the app and tooling for local development runs of an app.For testing, staging, and production environments, always publish and deploy the app. You can use any environment naming scheme that you wish for published apps, but always use app setting file names with casing of the environment segment that exactly matches the environment name. For staging, use "
Staging
" (capital "S") as the environment name, and name the app settings file to match (appsettings.Staging.json
). For production, use "Production
" (capital "P") as the environment name, and name the app settings file to match (appsettings.Production.json
).
The environment is set using any of the following approaches:
- Blazor Web App: Use any of the approaches described in Use multiple environments in ASP.NET Core for general ASP.NET Core apps.
- Blazor Web App or standalone Blazor WebAssembly: Blazor start configuration
- Standalone Blazor WebAssembly:
blazor-environment
header - Blazor Web App or standalone Blazor WebAssembly: Azure App Service
On the client for a Blazor Web App, the environment is determined from the server via a middleware that communicates the environment to the browser via a header named blazor-environment
. The header sets the environment when the WebAssemblyHost is created in the client-side Program
file (WebAssemblyHostBuilder.CreateDefault).
The environment is set using any of the following approaches:
- Blazor Server: Use any of the approaches described in Use multiple environments in ASP.NET Core for general ASP.NET Core apps.
- Blazor Server or Blazor WebAssembly: Blazor start configuration
- Blazor WebAssembly:
blazor-environment
header - Blazor Server or Blazor WebAssembly: Azure App Service
On the client for a Blazor Web App or the client of a hosted Blazor WebAssembly app, the environment is determined from the server via a middleware that communicates the environment to the browser via a header named blazor-environment
. The header sets the environment when the WebAssemblyHost is created in the client-side Program
file (WebAssemblyHostBuilder.CreateDefault).
For a standalone Blazor WebAssembly app running locally, the development server adds the blazor-environment
header.
For app's running locally in development, the app defaults to the Development
environment. Publishing the app defaults the environment to Production
.
For general guidance on ASP.NET Core app configuration, see Use multiple environments in ASP.NET Core. For server-side app configuration with static files in environments other than the Development environment during development and testing (for example, Staging), see ASP.NET Core Blazor static files.
The following example starts Blazor in the Staging
environment if the hostname includes localhost
. Otherwise, the environment is set to its default value.
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>
In the preceding example, the {BLAZOR SCRIPT}
placeholder is the Blazor script path and file name. For the location of the script, see ASP.NET Core Blazor project structure.
Notitie
For Blazor Web Apps that set the webAssembly
> environment
property in Blazor.start
configuration, it's wise to match the server-side environment to the environment set on the environment
property. Otherwise, prerendering on the server will operate under a different environment than rendering on the client, which results in arbitrary effects. For general guidance on setting the environment for a Blazor Web App, see Use multiple environments in ASP.NET Core.
Standalone Blazor WebAssembly:
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
if (window.location.hostname.includes("localhost")) {
Blazor.start({
environment: "Staging"
});
} else {
Blazor.start();
}
</script>
In the preceding example, the {BLAZOR SCRIPT}
placeholder is the Blazor script path and file name. For the location of the script, see ASP.NET Core Blazor project structure.
Using the environment
property overrides the environment set by the blazor-environment
header.
The preceding approach sets the client's environment without changing the blazor-environment
header's value, nor does it change the server project's console logging of the startup environment for a Blazor Web App that has adopted global Interactive WebAssembly rendering.
To log the environment to the console in either a standalone Blazor WebAssembly project or the .Client
project of a Blazor Web App, place the following C# code in the Program
file after the WebAssemblyHost is created with WebAssemblyHostBuilder.CreateDefault and before the line that builds and runs the project (await builder.Build().RunAsync();
):
Console.WriteLine(
$"Client Hosting Environment: {builder.HostEnvironment.Environment}");
For more information on Blazor startup, see ASP.NET Core Blazor startup.
Blazor WebAssembly apps can set the environment with the blazor-environment
header.
In the following example for IIS, the custom header (blazor-environment
) is added to the published web.config
file. The web.config
file is located in the bin/Release/{TARGET FRAMEWORK}/publish
folder, where the {TARGET FRAMEWORK}
placeholder is the 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>
Notitie
To use a custom web.config
file for IIS that isn't overwritten when the app is published to the publish
folder, see Host and deploy ASP.NET Core Blazor WebAssembly.
Although the Blazor framework issues the header name in all lowercase letters (blazor-environment
), you're welcome to use any casing that you desire. For example, a header name that capitalizes each word (Blazor-Environment
) is supported.
For a standalone Blazor WebAssembly app, you can set the environment manually via start configuration or the blazor-environment
header.
For a server-side app, set the environment via an ASPNETCORE_ENVIRONMENT
app setting in Azure:
Confirm that the casing of environment segments in app settings file names match their environment name casing exactly. For example, the matching app settings file name for the
Staging
environment isappsettings.Staging.json
. If the file name isappsettings.staging.json
(lowercase "s
"), the file isn't located, and the settings in the file aren't used in theStaging
environment.For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. For an app named
BlazorAzureAppSample
, the app is deployed to theStaging
deployment slot.In the Azure portal for the environment's deployment slot, set the environment with the
ASPNETCORE_ENVIRONMENT
app setting. For an app namedBlazorAzureAppSample
, the staging App Service Slot is namedBlazorAzureAppSample/Staging
. For theStaging
slot's configuration, create an app setting forASPNETCORE_ENVIRONMENT
with a value ofStaging
. Deployment slot setting is enabled for the setting.
When requested in a browser, the BlazorAzureAppSample/Staging
app loads in the Staging
environment at https://blazorazureappsample-staging.azurewebsites.net
.
When the app is loaded in the browser, the response header collection for blazor.boot.json
indicates that the blazor-environment
header value is Staging
.
App settings from the appsettings.{ENVIRONMENT}.json
file are loaded by the app, where the {ENVIRONMENT}
placeholder is the app's environment. In the preceding example, settings from the appsettings.Staging.json
file are loaded.
Obtain the app's environment in a component by injecting IWebAssemblyHostEnvironment and reading the Environment property.
ReadEnvironment.razor
:
@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env
<h1>Environment example</h1>
<p>Environment: @Env.Environment</p>
Assuming that prerendering isn't disabled for a component or the app, a component in the .Client
project is prerendered on the server. Because the server doesn't have a registered IWebAssemblyHostEnvironment service, it isn't possible to inject the service and use the service implementation's host environment extension methods and properties during server prerendering. Injecting the service into an Interactive WebAssembly or Interactive Auto component results in the following runtime error:
There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.
To address this, create a custom service implementation for IWebAssemblyHostEnvironment on the server. Add the following class to the server project.
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;
}
In the server project's Program
file, register the service:
builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();
At this point, the IWebAssemblyHostEnvironment service can be injected into an interactive WebAssembly or interactive Auto component and used as shown in the Read the environment in a Blazor WebAssembly app section.
The preceding example can demonstrate that it's possible to have a different server environment than client environment, which isn't recommended and may lead to arbitrary results. When setting the environment in a Blazor Web App, it's best to match server and .Client
project environments. Consider the following scenario in a test app:
- Implement the client-side (
webassembly
) environment property with theStaging
environment viaBlazor.start
. See the Set the client-side environment via startup configuration section for an example. - Don't change the server-side
Properties/launchSettings.json
file. Leave theenvironmentVariables
section with theASPNETCORE_ENVIRONMENT
environment variable set toDevelopment
.
You can see the value of the IWebAssemblyHostEnvironment.Environment property change in the UI.
When prerendering occurs on the server, the component is rendered in the Development
environment:
Environment: Development
When the component is rerendered just a second or two later, after the Blazor bundle is downloaded and the .NET WebAssembly runtime activates, the values change to reflect that the client is operating in the Staging
environment on the client:
Environment: Staging
The preceding example demonstrates why we recommend setting the server environment to match the client environment for development, testing, and production deployments.
For more information, see the Client-side services fail to resolve during prerendering section of the Render modes article, which appears later in the Blazor documentation.
During startup, the WebAssemblyHostBuilder exposes the IWebAssemblyHostEnvironment through the HostEnvironment property, which enables environment-specific logic in host builder code.
In the Program
file:
if (builder.HostEnvironment.Environment == "Custom")
{
...
};
The following convenience extension methods provided through WebAssemblyHostEnvironmentExtensions permit checking the current environment for Development
, Production
, Staging
, and custom environment names:
In the Program
file:
if (builder.HostEnvironment.IsStaging())
{
...
};
if (builder.HostEnvironment.IsEnvironment("Custom"))
{
...
};
The IWebAssemblyHostEnvironment.BaseAddress property can be used during startup when the NavigationManager service isn't available.
Feedback over ASP.NET Core
ASP.NET Core is een opensourceproject. Selecteer een koppeling om feedback te geven: