ASP.NET Core Blazor hosting model configuration

By Daniel Roth and Luke Latham

This article covers hosting model configuration.

SignalR cross-origin negotiation for authentication

This section applies to Blazor WebAssembly.

To configure SignalR's underlying client to send credentials, such as cookies or HTTP authentication headers:

  • Use SetBrowserRequestCredentials to set Include on cross-origin fetch requests:

    public class IncludeRequestCredentialsMessageHandler : DelegatingHandler
    {
        protected override Task<HttpResponseMessage> SendAsync(
            HttpRequestMessage request, CancellationToken cancellationToken)
        {
            request.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);
            return base.SendAsync(request, cancellationToken);
        }
    }
    
  • Assign the HttpMessageHandler to the HttpMessageHandlerFactory option:

    var connection = new HubConnectionBuilder()
        .WithUrl(new Uri("http://signalr.example.com"), options =>
        {
            options.HttpMessageHandlerFactory = innerHandler => 
                new IncludeRequestCredentialsMessageHandler { InnerHandler = innerHandler };
        }).Build();
    

For more information, see ASP.NET Core SignalR configuration.

Reflect the connection state in the UI

This section applies to Blazor Server.

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>

Add the following to the app's stylesheet (wwwroot/css/app.css or wwwroot/css/site.css):

#components-reconnect-modal {
    display: none;
}

#components-reconnect-modal.components-reconnect-show {
    display: block;
}

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

This section applies to Blazor Server.

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:

<body>
    <app>
      <component type="typeof(App)" render-mode="ServerPrerendered" />
    </app>

    <script src="_framework/blazor.server.js"></script>
</body>

RenderMode configures whether the component:

  • Is prerendered into the page.
  • Is rendered as static HTML on the page or if it includes the necessary information to bootstrap a Blazor app from the user agent.
Render mode Description
ServerPrerendered Renders the component into static HTML and includes a marker for a Blazor Server app. When the user-agent starts, this marker is used to bootstrap a Blazor app.
Server Renders a marker for a Blazor Server app. Output from the component isn't included. When the user-agent starts, this marker is used to bootstrap a Blazor app.
Static Renders the component into static HTML.

Rendering server components from a static HTML page isn't supported.

Configure the SignalR client for Blazor Server apps

This section applies to Blazor Server.

Configure the SignalR client used by Blazor Server apps in the Pages/_Host.cshtml file. Place a script that calls Blazor.start after the _framework/blazor.server.js script and inside the </body> tag.

Logging

To configure SignalR client logging:

  • Add an autostart="false" attribute to the <script> tag for the blazor.server.js script.
  • Pass in a configuration object (configureSignalR) that calls configureLogging with the log level on the client builder.
    ...

    <script src="_framework/blazor.server.js" autostart="false"></script>
    <script>
      Blazor.start({
        configureSignalR: function (builder) {
          builder.configureLogging("information");
        }
      });
    </script>
</body>

In the preceding example, information is equivalent to a log level of LogLevel.Information.

Modify the reconnection handler

The reconnection handler's circuit connection events can be modified for custom behaviors, such as:

  • To notify the user if the connection is dropped.
  • To perform logging (from the client) when a circuit is connected.

To modify the connection events:

  • Add an autostart="false" attribute to the <script> tag for the blazor.server.js script.
  • Register callbacks for connection changes for dropped connections (onConnectionDown) and established/re-established connections (onConnectionUp). Both onConnectionDown and onConnectionUp must be specified.
    ...

    <script src="_framework/blazor.server.js" autostart="false"></script>
    <script>
      Blazor.start({
        reconnectionHandler: {
          onConnectionDown: (options, error) => console.error(error);
          onConnectionUp: () => console.log("Up, up, and away!");
        }
      });
    </script>
</body>

Adjust the reconnection retry count and interval

To adjust the reconnection retry count and interval:

  • Add an autostart="false" attribute to the <script> tag for the blazor.server.js script.
  • Set the number of retries (maxRetries) and period in milliseconds permitted for each retry attempt (retryIntervalMilliseconds).
    ...

    <script src="_framework/blazor.server.js" autostart="false"></script>
    <script>
      Blazor.start({
        reconnectionOptions: {
          maxRetries: 3,
          retryIntervalMilliseconds: 2000
        }
      });
    </script>
</body>

Hide or replace the reconnection display

To hide the reconnection display:

  • Add an autostart="false" attribute to the <script> tag for the blazor.server.js script.
  • Set the reconnection handler's _reconnectionDisplay to an empty object ({} or new Object()).
    ...

    <script src="_framework/blazor.server.js" autostart="false"></script>
    <script>
      window.addEventListener('beforeunload', function () {
        Blazor.defaultReconnectionHandler._reconnectionDisplay = {};
      });
    </script>
</body>

To replace the reconnection display, set _reconnectionDisplay in the preceding example to the element for display:

Blazor.defaultReconnectionHandler._reconnectionDisplay = 
  document.getElementById("{ELEMENT ID}");

The placeholder {ELEMENT ID} is the ID of the HTML element to display.

Additional resources