ASP.NET Core Blazor environments

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 either 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. 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:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      Blazor.start({
        environment: "Staging"
      });
    </script>
</body>

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.

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>

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

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 either 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. 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:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      Blazor.start({
        environment: "Staging"
      });
    </script>
</body>

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.

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>

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

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 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. 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 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.

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>

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