Edit

ASP.NET Core Blazor environments

  • Article
  • 4 minutes to read

This article explains ASP.NET Core environments in Blazor, including how to set the environment.

Important

This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, which describes the approaches to use for Blazor Server apps, see Use multiple environments in ASP.NET Core.

For Blazor Server app configuration for static files in environments other than the Development environment during development and testing (for example, Staging), see ASP.NET Core Blazor static files.

Note

This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, which describes the approaches to use for Blazor Server apps, see Use multiple environments in ASP.NET Core.

When running an app locally, the environment defaults to Development. When the app is published, the environment defaults to Production.

The environment is set using any of the following approaches:

The client-side Blazor app (Client) of a hosted Blazor WebAssembly solution determines the environment from the Server app of the solution via a middleware that communicates the environment to the browser. The Server app adds a header named Blazor-Environment with the environment as the value of the header. The Client app reads the header and sets the environment when the WebAssemblyHost is created in Program.cs (WebAssemblyHostBuilder.CreateDefault). The Server app of the solution is an ASP.NET Core app, so more information on how to configure the environment is found in Use multiple environments in ASP.NET Core.

For a standalone Blazor WebAssembly app running locally, the development server adds the Blazor-Environment header to specify the Development environment.

Set the environment via startup configuration

The following example starts Blazor in the Staging environment if the hostname includes localhost. Otherwise, the environment is set to Production.

Inside the closing </body> tag of wwwroot/index.html:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start({
      environment: "Production"
    });
  }
</script>

Using the environment property overrides the environment set by the Blazor-Environment header.

For more information on Blazor startup, see ASP.NET Core Blazor startup.

Set the environment via header

To specify the environment for other hosting environments, add 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 placeholder {TARGET FRAMEWORK} 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>

Note

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.

Set the environment for Azure App Service

The guidance in this section requires the use of a hosted Blazor WebAssembly app.

Note

For standalone Blazor Webassembly apps, set the environment manually via start configuration or the Blazor-Environment header.

Use the following guidance for hosted Blazor WebAssembly solutions hosted by Azure App Service:

  1. Confirm that the casing of environment segments in app settings file names matches their environment name casing exactly. For example, the matching app settings file name for the Staging environment is appsettings.Staging.json. If the file name is appsettings.staging.json (lowercase "s"), the file isn't located, and the settings in the file aren't used in the Staging environment.

  2. In the Azure portal for the environment's deployment slot, set the environment with the ASPNETCORE_ENVIRONMENT app setting. For an app named BlazorAzureAppSample, the staging App Service Slot is named BlazorAzureAppSample/Staging. For the Staging slot's configuration, create an app setting for ASPNETCORE_ENVIRONMENT with a value of Staging. Deployment slot setting is enabled for the setting.

  3. 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 the Staging deployment slot.

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.

Read the environment

Obtain the app's environment in a component by injecting IWebAssemblyHostEnvironment and reading the Environment property.

Pages/ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment HostEnvironment

<h1>Environment example</h1>

<p>Environment: @HostEnvironment.Environment</p>

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment HostEnvironment

<h1>Environment example</h1>

<p>Environment: @HostEnvironment.Environment</p>

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment HostEnvironment

<h1>Environment example</h1>

<p>Environment: @HostEnvironment.Environment</p>

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment HostEnvironment

<h1>Environment example</h1>

<p>Environment: @HostEnvironment.Environment</p>

During startup, the WebAssemblyHostBuilder exposes the IWebAssemblyHostEnvironment through the HostEnvironment property, which enables environment-specific logic in host builder code.

In Program.cs:

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 Program.cs:

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.

Additional resources