ASP.NET Core Blazor hosting model configuration

In this article

Blazor WebAssembly

Environment

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

A hosted Blazor WebAssembly app picks up the environment from the server via a middleware that communicates the environment to the browser by adding the blazor-environment header. The value of the header is the environment. The hosted Blazor app and the server app share the same environment. For more information, including how to configure the environment, see Use multiple environments in ASP.NET Core.

For a standalone app running locally, the development server adds the blazor-environment header to specify the Development environment. To specify the environment for other hosting environments, add the blazor-environment header.

In the following example for IIS, add the custom header to the published web.config file. The web.config file is located in the bin/Release/{TARGET FRAMEWORK}/publish folder:

To read other configuration files from the wwwroot folder into configuration, use an HttpClient to obtain the file's content. When using this approach, the existing HttpClient service registration can use the local client created to read the file, as the following example shows:

Host builder configuration

Program.Main:

var hostname = builder.Configuration["HostName"];

Cached configuration

Configuration files are cached for offline use. With Progressive Web Applications (PWAs), you can only update configuration files when creating a new deployment. Editing configuration files between deployments has no effect because:

Users have cached versions of the files that they continue to use.

The PWA's service-worker.js and service-worker-assets.js files must be rebuilt on compilation, which signal to the app on the user's next online visit that the app has been redeployed.

Logging

Blazor Server

Reflect the connection state in the UI

When the client detects that the connection has been lost, a default UI is displayed to the user while the client attempts to reconnect. If reconnection fails, the user is provided the option to retry.

To customize the UI, define an element with an id of components-reconnect-modal in the <body> of the _Host.cshtml Razor page:

<div id="components-reconnect-modal">
...
</div>

The following table describes the CSS classes applied to the components-reconnect-modal element.

CSS class

Indicates…

components-reconnect-show

A lost connection. The client is attempting to reconnect. Show the modal.

components-reconnect-hide

An active connection is re-established to the server. Hide the modal.

components-reconnect-failed

Reconnection failed, probably due to a network failure. To attempt reconnection, call window.Blazor.reconnect().

components-reconnect-rejected

Reconnection rejected. The server was reached but refused the connection, and the user's state on the server is lost. To reload the app, call location.reload(). This connection state may result when:

A crash in the server-side circuit occurs.

The client is disconnected long enough for the server to drop the user's state. Instances of the components that the user is interacting with are disposed.

The server is restarted, or the app's worker process is recycled.

Render mode

Blazor Server apps are set up by default to prerender the UI on the server before the client connection to the server is established. This is set up in the _Host.cshtml Razor page: