ASP.NET Core Blazor SignalR guidance

Azure SignalR Service with stateful reconnect

The Azure SignalR Service with SDK v1.26.1 or later supports SignalR stateful reconnect (WithStatefulReconnect).

WebSocket compression for Interactive Server components

By default, Interactive Server components:

• Enable compression for WebSocket connections. DisableWebSocketCompression (default: false) controls WebSocket compression.

• Adopt a frame-ancestors Content Security Policy (CSP) directive set to 'self', which only permits embedding the app in an <iframe> of the origin from which the app is served when compression is enabled or when a configuration for the WebSocket context is provided. ContentSecurityFrameAncestorPolicy controls the frame-ancestors CSP.

The frame-ancestors CSP can be removed manually by setting the value of ContentSecurityFrameAncestorsPolicy to null, as you may want to configure the CSP in a centralized way. When the frame-ancestors CSP is managed in a centralized fashion, care must be taken to apply a policy whenever the first document is rendered. We don't recommend removing the policy completely, as it might make the app vulnerable to attack.

Use ConfigureWebSocketAcceptContext to configure the WebSocketAcceptContext for the websocket connections used by the server components. By default, a policy that enables compression and sets a CSP for the frame ancestors defined in ContentSecurityFrameAncestorsPolicy is applied.

Usage examples:

Disable compression by setting DisableWebSocketCompression to true, which reduces the vulnerability of the app to attack but may result in reduced performance:

builder.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode(o => o.DisableWebSocketCompression = true)

When compression is enabled, configure a stricter frame-ancestors CSP with a value of 'none' (single quotes required), which allows WebSocket compression but prevents browsers from embedding the app into any <iframe>:

builder.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode(o => o.ContentSecurityFrameAncestorsPolicy = "'none'")

When compression is enabled, remove the frame-ancestors CSP by setting ContentSecurityFrameAncestorsPolicy to null. This scenario is only recommended for apps that set the CSP in a centralized way:

builder.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode(o => o.ContentSecurityFrameAncestorsPolicy = null)

For security implications, see Threat mitigation guidance for ASP.NET Core Blazor interactive server-side rendering. For more information on the frame-ancestors directive, see CSP: frame-ancestors (MDN documentation).

Disable response compression for Hot Reload

When using Hot Reload, disable Response Compression Middleware in the Development environment. Whether or not the default code from a project template is used, always call UseResponseCompression first in the request processing pipeline.

In the Program file:

if (!app.Environment.IsDevelopment())
{
    app.UseResponseCompression();
}

If prerendering is configured, prerendering occurs before the client connection to the server is established. For more information, see Prerender ASP.NET Core Razor components.

If prerendering is configured, prerendering occurs before the client connection to the server is established. For more information, see the following articles:

• Component Tag Helper in ASP.NET Core
• Integrate ASP.NET Core Razor components with MVC or Razor Pages

Read or set the options in the Program file with an options delegate to AddInteractiveServerComponents. The {OPTION} placeholder represents the option, and the {VALUE} placeholder is the value.

In the Program file:

builder.Services.AddRazorComponents().AddInteractiveServerComponents(options =>
{
    options.{OPTION} = {VALUE};
});

Read or set the options in the Program file with an options delegate to AddServerSideBlazor. The {OPTION} placeholder represents the option, and the {VALUE} placeholder is the value.

In the Program file:

builder.Services.AddServerSideBlazor(options =>
{
    options.{OPTION} = {VALUE};
});

Read or set the options in Startup.ConfigureServices with an options delegate to AddServerSideBlazor. The {OPTION} placeholder represents the option, and the {VALUE} placeholder is the value.

In Startup.ConfigureServices of Startup.cs:

services.AddServerSideBlazor(options =>
{
    options.{OPTION} = {VALUE};
});

In the Program file:

builder.Services.AddRazorComponents().AddInteractiveServerComponents().AddHubOptions(options =>
{
    options.{OPTION} = {VALUE};
});

In the Program file:

builder.Services.AddServerSideBlazor().AddHubOptions(options =>
{
    options.{OPTION} = {VALUE};
});

In Startup.ConfigureServices of Startup.cs:

services.AddServerSideBlazor().AddHubOptions(options =>
{
    options.{OPTION} = {VALUE};
});

Place the call to app.MapBlazorHub after the call to app.MapRazorComponents in the app's Program file:

app.MapBlazorHub(options =>
{
    options.{OPTION} = {VALUE};
});

Configuring the hub used by AddInteractiveServerRenderMode with MapBlazorHub fails with an AmbiguousMatchException:

Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints.

To workaround the problem for apps targeting .NET 8, give the custom-configured Blazor hub higher precedence using the WithOrder method:

app.MapBlazorHub(options =>
{
    options.CloseOnAuthenticationExpiration = true;
}).WithOrder(-1);

For more information, see the following resources:

• MapBlazorHub configuration in NET8 throws a The request matched multiple endpoints exception (dotnet/aspnetcore #51698)
• Attempts to map multiple blazor entry points with MapBlazorHub causes Ambiguous Route Error. This worked with net7 (dotnet/aspnetcore #52156)

Supply the options to app.MapBlazorHub in the app's Program file:

app.MapBlazorHub(options =>
{
    options.{OPTION} = {VALUE};
});

Supply the options to app.MapBlazorHub in endpoint routing configuration:

app.UseEndpoints(endpoints =>
{
    endpoints.MapBlazorHub(options =>
    {
        options.{OPTION} = {VALUE};
    });
    ...
});

One approach involves increasing the limit by setting MaximumReceiveMessageSize in the Program file. The following example sets the maximum receive message size to 64 KB:

builder.Services.AddRazorComponents().AddInteractiveServerComponents()
    .AddHubOptions(options => options.MaximumReceiveMessageSize = 64 * 1024);

Increasing the SignalR incoming message size limit comes at the cost of requiring more server resources, and it increases the risk of Denial of Service (DoS) attacks. Additionally, reading a large amount of content in to memory as strings or byte arrays can also result in allocations that work poorly with the garbage collector, resulting in additional performance penalties.

A better option for reading large payloads is to send the content in smaller chunks and process the payload as a Stream. This can be used when reading large JavaScript (JS) interop JSON payloads or if JS interop data is available as raw bytes. For an example that demonstrates sending large binary payloads in server-side apps that uses techniques similar to the InputFile component, see the Binary Submit sample app and the Blazor InputLargeTextArea Component Sample.

Forms that process large payloads over SignalR can also use streaming JS interop directly. For more information, see Call .NET methods from JavaScript functions in ASP.NET Core Blazor. For a forms example that streams <textarea> data to the server, see Troubleshoot ASP.NET Core Blazor forms.

One approach involves increasing the limit by setting MaximumReceiveMessageSize in the Program file. The following example sets the maximum receive message size to 64 KB:

builder.Services.AddServerSideBlazor()
    .AddHubOptions(options => options.MaximumReceiveMessageSize = 64 * 1024);

Increasing the SignalR incoming message size limit comes at the cost of requiring more server resources, and it increases the risk of Denial of Service (DoS) attacks. Additionally, reading a large amount of content in to memory as strings or byte arrays can also result in allocations that work poorly with the garbage collector, resulting in additional performance penalties.

A better option for reading large payloads is to send the content in smaller chunks and process the payload as a Stream. This can be used when reading large JavaScript (JS) interop JSON payloads or if JS interop data is available as raw bytes. For an example that demonstrates sending large binary payloads in Blazor Server that uses techniques similar to the InputFile component, see the Binary Submit sample app and the Blazor InputLargeTextArea Component Sample.

Forms that process large payloads over SignalR can also use streaming JS interop directly. For more information, see Call .NET methods from JavaScript functions in ASP.NET Core Blazor. For a forms example that streams <textarea> data in a Blazor Server app, see Troubleshoot ASP.NET Core Blazor forms.

Increase the limit by setting MaximumReceiveMessageSize in Startup.ConfigureServices:

services.AddServerSideBlazor()
    .AddHubOptions(options => options.MaximumReceiveMessageSize = 64 * 1024);

Increasing the SignalR incoming message size limit comes at the cost of requiring more server resources, and it increases the risk of Denial of Service (DoS) attacks. Additionally, reading a large amount of content in to memory as strings or byte arrays can also result in allocations that work poorly with the garbage collector, resulting in additional performance penalties.

• Leverage the native streaming JS interop support to transfer data larger than the SignalR incoming message size limit:
  • Call JavaScript functions from .NET methods in ASP.NET Core Blazor
  • Call .NET methods from JavaScript functions in ASP.NET Core Blazor
  • Form payload example: Troubleshoot ASP.NET Core Blazor forms
• General tips:
  • Don't allocate large objects in JS and C# code.
  • Free consumed memory when the process is completed or cancelled.
  • Enforce the following additional requirements for security purposes:
    • Declare the maximum file or data size that can be passed.
    • Declare the minimum upload rate from the client to the server.
  • After the data is received by the server, the data can be:
    • Temporarily stored in a memory buffer until all of the segments are collected.
    • Consumed immediately. For example, the data can be stored immediately in a database or written to disk as each segment is received.

• Slice the data into smaller pieces, and send the data segments sequentially until all of the data is received by the server.
• Don't allocate large objects in JS and C# code.
• Don't block the main UI thread for long periods when sending or receiving data.
• Free consumed memory when the process is completed or cancelled.
• Enforce the following additional requirements for security purposes:
  • Declare the maximum file or data size that can be passed.
  • Declare the minimum upload rate from the client to the server.
• After the data is received by the server, the data can be:
  • Temporarily stored in a memory buffer until all of the segments are collected.
  • Consumed immediately. For example, the data can be stored immediately in a database or written to disk as each segment is received.

To customize the UI, define a single element with an id of components-reconnect-modal in the <body> element content. The following example places the element in the App component.

App.razor:

To customize the UI, define a single element with an id of components-reconnect-modal in the <body> element content. The following example places the element in the host page.

Pages/_Host.cshtml:

To customize the UI, define a single element with an id of components-reconnect-modal in the <body> element content. The following example places the element in the layout page.

Pages/_Layout.cshtml:

To customize the UI, define a single element with an id of components-reconnect-modal in the <body> element content. The following example places the element in the host page.

Pages/_Host.cshtml:

wwwroot/app.css:

wwwroot/css/site.css:

Customize the delay before the reconnection UI appears by setting the transition-delay property in the site's CSS for the modal element. The following example sets the transition delay from 500 ms (default) to 1,000 ms (1 second).

wwwroot/app.css:

wwwroot/css/site.css:

#components-reconnect-modal {
    transition: visibility 0s linear 1000ms;
}

To display the current reconnect attempt, define an element with an id of components-reconnect-current-attempt. To display the maximum number of reconnect retries, define an element with an id of components-reconnect-max-retries. The following example places these elements inside a reconnect attempt modal element following the previous example.

<div id="components-reconnect-modal">
    There was a problem with the connection!
    (Current reconnect attempt: 
    <span id="components-reconnect-current-attempt"></span> /
    <span id="components-reconnect-max-retries"></span>)
</div>

When the custom reconnect modal appears, it renders the following content with a reconnection attempt counter:

There was a problem with the connection! (Current reconnect attempt: 1 / 8)

By default, components are prerendered on the server before the client connection to the server is established. For more information, see Prerender ASP.NET Core Razor components.

By default, components are prerendered on the server before the client connection to the server is established. For more information, see Component Tag Helper in ASP.NET Core.

Monitor server-side circuit activity

Monitor inbound circuit activity using the CreateInboundActivityHandler method on CircuitHandler. Inbound circuit activity is any activity sent from the browser to the server, such as UI events or JavaScript-to-.NET interop calls.

For example, you can use a circuit activity handler to detect if the client is idle and log its circuit ID (Circuit.Id):

using Microsoft.AspNetCore.Components.Server.Circuits;
using Microsoft.Extensions.Options;
using Timer = System.Timers.Timer;

public sealed class IdleCircuitHandler : CircuitHandler, IDisposable
{
    private Circuit? currentCircuit;
    private readonly ILogger logger;
    private readonly Timer timer;

    public IdleCircuitHandler(ILogger<IdleCircuitHandler> logger, 
        IOptions<IdleCircuitOptions> options)
    {
        timer = new Timer
        {
            Interval = options.Value.IdleTimeout.TotalMilliseconds,
            AutoReset = false
        };

        timer.Elapsed += CircuitIdle;
        this.logger = logger;
    }

    private void CircuitIdle(object? sender, System.Timers.ElapsedEventArgs e)
    {
        logger.LogInformation("{CircuitId} is idle", currentCircuit?.Id);
    }

    public override Task OnCircuitOpenedAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        currentCircuit = circuit;

        return Task.CompletedTask;
    }

    public override Func<CircuitInboundActivityContext, Task> CreateInboundActivityHandler(
        Func<CircuitInboundActivityContext, Task> next)
    {
        return context =>
        {
            timer.Stop();
            timer.Start();

            return next(context);
        };
    }

    public void Dispose() => timer.Dispose();
}

public class IdleCircuitOptions
{
    public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromMinutes(5);
}

public static class IdleCircuitHandlerServiceCollectionExtensions
{
    public static IServiceCollection AddIdleCircuitHandler(
        this IServiceCollection services, 
        Action<IdleCircuitOptions> configureOptions)
    {
        services.Configure(configureOptions);
        services.AddIdleCircuitHandler();

        return services;
    }

    public static IServiceCollection AddIdleCircuitHandler(
        this IServiceCollection services)
    {
        services.AddScoped<CircuitHandler, IdleCircuitHandler>();

        return services;
    }
}

Register the service in the Program file. The following example configures the default idle timeout of five minutes to five seconds in order to test the preceding IdleCircuitHandler implementation:

builder.Services.AddIdleCircuitHandler(options => 
    options.IdleTimeout = TimeSpan.FromSeconds(5));

Circuit activity handlers also provide an approach for accessing scoped Blazor services from other non-Blazor dependency injection (DI) scopes. For more information and examples, see:

• ASP.NET Core Blazor dependency injection
• ASP.NET Core server-side and Blazor Web App additional security scenarios

Configure the manual start of Blazor's SignalR circuit in the App.razor file of a Blazor Web App:

Configure the manual start of Blazor's SignalR circuit in the Pages/_Host.cshtml file (Blazor Server):

Configure the manual start of Blazor's SignalR circuit in the Pages/_Layout.cshtml file (Blazor Server):

Configure the manual start of Blazor's SignalR circuit in the Pages/_Host.cshtml file (Blazor Server):

Configure the following values for the client:

• withServerTimeout: Configures the server timeout in milliseconds. If this timeout elapses without receiving any messages from the server, the connection is terminated with an error. The default timeout value is 30 seconds. The server timeout should be at least double the value assigned to the Keep-Alive interval (withKeepAliveInterval).
• withKeepAliveInterval: Configures the Keep-Alive interval in milliseconds (default interval at which to ping the server). This setting allows the server to detect hard disconnects, such as when a client unplugs their computer from the network. The ping occurs at most as often as the server pings. If the server pings every five seconds, assigning a value lower than 5000 (5 seconds) pings every five seconds. The default value is 15 seconds. The Keep-Alive interval should be less than or equal to half the value assigned to the server timeout (withServerTimeout).

The following example for the App.razor file (Blazor Web App) shows the assignment of default values.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      configureSignalR: function (builder) {
        builder.withServerTimeout(30000).withKeepAliveInterval(15000);
      }
    }
  });
</script>

The following example for the Pages/_Host.cshtml file (Blazor Server, all versions except ASP.NET Core in .NET 6) or Pages/_Layout.cshtml file (Blazor Server, ASP.NET Core in .NET 6).

Blazor Server:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      builder.withServerTimeout(30000).withKeepAliveInterval(15000);
    }
  });
</script>

In the preceding example, the {BLAZOR SCRIPT} placeholder is the Blazor script path and file name. For the location of the script and the path to use, see ASP.NET Core Blazor project structure.

When creating a hub connection in a component, set the ServerTimeout (default: 30 seconds) and KeepAliveInterval (default: 15 seconds) on the HubConnectionBuilder. Set the HandshakeTimeout (default: 15 seconds) on the built HubConnection. The following example shows the assignment of default values:

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .WithServerTimeout(TimeSpan.FromSeconds(30))
        .WithKeepAliveInterval(TimeSpan.FromSeconds(15))
        .Build();

    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(15);

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Configure the following values for the client:

• serverTimeoutInMilliseconds: The server timeout in milliseconds. If this timeout elapses without receiving any messages from the server, the connection is terminated with an error. The default timeout value is 30 seconds. The server timeout should be at least double the value assigned to the Keep-Alive interval (keepAliveIntervalInMilliseconds).
• keepAliveIntervalInMilliseconds: Default interval at which to ping the server. This setting allows the server to detect hard disconnects, such as when a client unplugs their computer from the network. The ping occurs at most as often as the server pings. If the server pings every five seconds, assigning a value lower than 5000 (5 seconds) pings every five seconds. The default value is 15 seconds. The Keep-Alive interval should be less than or equal to half the value assigned to the server timeout (serverTimeoutInMilliseconds).

The following example for the Pages/_Host.cshtml file (Blazor Server, all versions except ASP.NET Core in .NET 6) or Pages/_Layout.cshtml file (Blazor Server, ASP.NET Core in .NET 6):

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      let c = builder.build();
      c.serverTimeoutInMilliseconds = 30000;
      c.keepAliveIntervalInMilliseconds = 15000;
      builder.build = () => {
        return c;
      };
    }
  });
</script>

In the preceding example, the {BLAZOR SCRIPT} placeholder is the Blazor script path and file name. For the location of the script and the path to use, see ASP.NET Core Blazor project structure.

When creating a hub connection in a component, set the ServerTimeout (default: 30 seconds), HandshakeTimeout (default: 15 seconds), and KeepAliveInterval (default: 15 seconds) on the built HubConnection. The following example shows the assignment of default values:

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .Build();

    hubConnection.ServerTimeout = TimeSpan.FromSeconds(30);
    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(15);
    hubConnection.KeepAliveInterval = TimeSpan.FromSeconds(15);

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      reconnectionHandler: {
        onConnectionDown: (options, error) => console.error(error),
        onConnectionUp: () => console.log("Up, up, and away!")
      }
    }
  });
</script>

Blazor Server:

Automatically refresh the page when server-side reconnection fails

The default reconnection behavior requires the user to take manual action to refresh the page after reconnection fails. However, a custom reconnection handler can be used to automatically refresh the page:

App.razor:

Pages/_Host.cshtml:

<div id="reconnect-modal" style="display: none;"></div>
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script src="boot.js"></script>

In the preceding example, the {BLAZOR SCRIPT} placeholder is the Blazor script path and file name. For the location of the script and the path to use, see ASP.NET Core Blazor project structure.

Create the following wwwroot/boot.js file.

Blazor Web App:

(() => {
  const maximumRetryCount = 3;
  const retryIntervalMilliseconds = 5000;
  const reconnectModal = document.getElementById('reconnect-modal');

  const startReconnectionProcess = () => {
    reconnectModal.style.display = 'block';

    let isCanceled = false;

    (async () => {
      for (let i = 0; i < maximumRetryCount; i++) {
        reconnectModal.innerText = `Attempting to reconnect: ${i + 1} of ${maximumRetryCount}`;

        await new Promise(resolve => setTimeout(resolve, retryIntervalMilliseconds));

        if (isCanceled) {
          return;
        }

        try {
          const result = await Blazor.reconnect();
          if (!result) {
            // The server was reached, but the connection was rejected; reload the page.
            location.reload();
            return;
          }

          // Successfully reconnected to the server.
          return;
        } catch {
          // Didn't reach the server; try again.
        }
      }

      // Retried too many times; reload the page.
      location.reload();
    })();

    return {
      cancel: () => {
        isCanceled = true;
        reconnectModal.style.display = 'none';
      },
    };
  };

  let currentReconnectionProcess = null;

  Blazor.start({
    circuit: {
      reconnectionHandler: {
        onConnectionDown: () => currentReconnectionProcess ??= startReconnectionProcess(),
        onConnectionUp: () => {
          currentReconnectionProcess?.cancel();
          currentReconnectionProcess = null;
        }
      }
    }
  });
})();

Blazor Server:

(() => {
  const maximumRetryCount = 3;
  const retryIntervalMilliseconds = 5000;
  const reconnectModal = document.getElementById('reconnect-modal');

  const startReconnectionProcess = () => {
    reconnectModal.style.display = 'block';

    let isCanceled = false;

    (async () => {
      for (let i = 0; i < maximumRetryCount; i++) {
        reconnectModal.innerText = `Attempting to reconnect: ${i + 1} of ${maximumRetryCount}`;

        await new Promise(resolve => setTimeout(resolve, retryIntervalMilliseconds));

        if (isCanceled) {
          return;
        }

        try {
          const result = await Blazor.reconnect();
          if (!result) {
            // The server was reached, but the connection was rejected; reload the page.
            location.reload();
            return;
          }

          // Successfully reconnected to the server.
          return;
        } catch {
          // Didn't reach the server; try again.
        }
      }

      // Retried too many times; reload the page.
      location.reload();
    })();

    return {
      cancel: () => {
        isCanceled = true;
        reconnectModal.style.display = 'none';
      },
    };
  };

  let currentReconnectionProcess = null;

  Blazor.start({
    reconnectionHandler: {
      onConnectionDown: () => currentReconnectionProcess ??= startReconnectionProcess(),
      onConnectionUp: () => {
        currentReconnectionProcess?.cancel();
        currentReconnectionProcess = null;
      }
    }
  });
})();

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

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      reconnectionOptions: {
        maxRetries: 3,
        retryIntervalMilliseconds: 2000
      }
    }
  });
</script>

Blazor Server:

When the user navigates back to an app with a disconnected circuit, reconnection is attempted immediately rather than waiting for the duration of the next reconnect interval. This behavior seeks to resume the connection as quickly as possible for the user.

The default reconnect timing uses a computed backoff strategy. The first several reconnection attempts occur in rapid succession before computed delays are introduced between attempts. The default logic for computing the retry interval is an implementation detail subject to change without notice, but you can find the default logic that the Blazor framework uses in the computeDefaultRetryInterval function (reference source).

Customize the retry interval behavior by specifying a function to compute the retry interval. In the following exponential backoff example, the number of previous reconnection attempts is multiplied by 1,000 ms to calculate the retry interval. When the count of previous attempts to reconnect (previousAttempts) is greater than the maximum retry limit (maxRetries), null is assigned to the retry interval (retryIntervalMilliseconds) to cease further reconnection attempts:

Blazor.start({
  circuit: {
    reconnectionOptions: {
      retryIntervalMilliseconds: (previousAttempts, maxRetries) => 
        previousAttempts >= maxRetries ? null : previousAttempts * 1000
    },
  },
});

An alternative is to specify the exact sequence of retry intervals. After the last specified retry interval, retries stop because the retryIntervalMilliseconds function returns undefined:

Blazor.start({
  circuit: {
    reconnectionOptions: {
      retryIntervalMilliseconds: 
        Array.prototype.at.bind([0, 1000, 2000, 5000, 10000, 15000, 30000]),
    },
  },
});

Control when the reconnection UI appears

Controlling when the reconnection UI appears can be useful in the following situations:

• A deployed app frequently displays the reconnection UI due to ping timeouts caused by internal network or Internet latency, and you would like to increase the delay.
• An app should report to users that the connection has dropped sooner, and you would like to shorten the delay.

The timing of the appearance of the reconnection UI is influenced by adjusting the Keep-Alive interval and timeouts on the client. The reconnection UI appears when the server timeout is reached on the client (withServerTimeout, Client configuration section). However, changing the value of withServerTimeout requires changes to other Keep-Alive, timeout, and handshake settings described in the following guidance.

As general recommendations for the guidance that follows:

• The Keep-Alive interval should match between client and server configurations.
• Timeouts should be at least double the value assigned to the Keep-Alive interval.

Server configuration

Set the following:

• ClientTimeoutInterval (default: 30 seconds): The time window clients have to send a message before the server closes the connection.
• HandshakeTimeout (default: 15 seconds): The interval used by the server to timeout incoming handshake requests by clients.
• KeepAliveInterval (default: 15 seconds): The interval used by the server to send keep alive pings to connected clients. Note that there is also a Keep-Alive interval setting on the client, which should match the server's value.

The ClientTimeoutInterval and HandshakeTimeout can be increased, and the KeepAliveInterval can remain the same. The important consideration is that if you change the values, make sure that the timeouts are at least double the value of the Keep-Alive interval and that the Keep-Alive interval matches between server and client. For more information, see the Configure SignalR timeouts and Keep-Alive on the client section.

In the following example:

• The ClientTimeoutInterval is increased to 60 seconds (default value: 30 seconds).
• The HandshakeTimeout is increased to 30 seconds (default value: 15 seconds).
• The KeepAliveInterval isn't set in developer code and uses its default value of 15 seconds. Decreasing the value of the Keep-Alive interval increases the frequency of communication pings, which increases the load on the app, server, and network. Care must be taken to avoid introducing poor performance when lowering the Keep-Alive interval.

Blazor Web App (.NET 8 or later) in the server project's Program file:

builder.Services.AddRazorComponents().AddInteractiveServerComponents()
    .AddHubOptions(options =>
{
    options.ClientTimeoutInterval = TimeSpan.FromSeconds(60);
    options.HandshakeTimeout = TimeSpan.FromSeconds(30);
});

Blazor Server in the Program file:

builder.Services.AddServerSideBlazor()
    .AddHubOptions(options =>
    {
        options.ClientTimeoutInterval = TimeSpan.FromSeconds(60);
        options.HandshakeTimeout = TimeSpan.FromSeconds(30);
    });

For more information, see the Server-side circuit handler options section.

Client configuration

Set the following:

• withServerTimeout (default: 30 seconds): Configures the server timeout, specified in milliseconds, for the circuit's hub connection.
• withKeepAliveInterval (default: 15 seconds): The interval, specified in milliseconds, at which the connection sends Keep-Alive messages.

The server timeout can be increased, and the Keep-Alive interval can remain the same. The important consideration is that if you change the values, make sure that the server timeout is at least double the value of the Keep-Alive interval and that the Keep-Alive interval values match between server and client. For more information, see the Configure SignalR timeouts and Keep-Alive on the client section.

In the following startup configuration example (location of the Blazor script), a custom value of 60 seconds is used for the server timeout. The Keep-Alive interval (withKeepAliveInterval) isn't set and uses its default value of 15 seconds.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      configureSignalR: function (builder) {
        builder.withServerTimeout(60000);
      }
    }
  });
</script>

Blazor Server:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      builder.withServerTimeout(60000);
    }
  });
</script>

When creating a hub connection in a component, set the server timeout (WithServerTimeout, default: 30 seconds) on the HubConnectionBuilder. Set the HandshakeTimeout (default: 15 seconds) on the built HubConnection. Confirm that the timeouts are at least double the Keep-Alive interval (WithKeepAliveInterval/KeepAliveInterval) and that the Keep-Alive value matches between server and client.

The following example is based on the Index component in the SignalR with Blazor tutorial. The server timeout is increased to 60 seconds, and the handshake timeout is increased to 30 seconds. The Keep-Alive interval isn't set and uses its default value of 15 seconds.

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .WithServerTimeout(TimeSpan.FromSeconds(60))
        .Build();

    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(30);

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Set the following:

• serverTimeoutInMilliseconds (default: 30 seconds): Configures the server timeout, specified in milliseconds, for the circuit's hub connection.
• keepAliveIntervalInMilliseconds (default: 15 seconds): The interval, specified in milliseconds, at which the connection sends Keep-Alive messages.

The server timeout can be increased, and the Keep-Alive interval can remain the same. The important consideration is that if you change the values, make sure that the server timeout is at least double the value of the Keep-Alive interval and that the Keep-Alive interval values match between server and client. For more information, see the Configure SignalR timeouts and Keep-Alive on the client section.

In the following startup configuration example (location of the Blazor script), a custom value of 60 seconds is used for the server timeout. The Keep-Alive interval (keepAliveIntervalInMilliseconds) isn't set and uses its default value of 15 seconds.

In Pages/_Host.cshtml:

<script src="_framework/blazor.server.js" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      let c = builder.build();
      c.serverTimeoutInMilliseconds = 60000;
      builder.build = () => {
        return c;
      };
    }
  });
</script>

When creating a hub connection in a component, set the ServerTimeout (default: 30 seconds) and HandshakeTimeout (default: 15 seconds) on the built HubConnection. Confirm that the timeouts are at least double the Keep-Alive interval. Confirm that the Keep-Alive interval matches between server and client.

The following example is based on the Index component in the SignalR with Blazor tutorial. The ServerTimeout is increased to 60 seconds, and the HandshakeTimeout is increased to 30 seconds. The Keep-Alive interval (KeepAliveInterval) isn't set and uses its default value of 15 seconds.

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .Build();

    hubConnection.ServerTimeout = TimeSpan.FromSeconds(60);
    hubConnection.HandshakeTimeout = TimeSpan.FromSeconds(30);

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Disconnect Blazor's SignalR circuit from the client

Blazor's SignalR circuit is disconnected when the unload page event is triggered. To disconnect the circuit for other scenarios on the client, invoke Blazor.disconnect in the appropriate event handler. In the following example, the circuit is disconnected when the page is hidden (pagehide event):

window.addEventListener('pagehide', () => {
  Blazor.disconnect();
});

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

In the Program file:

builder.Services.AddSingleton<CircuitHandler, TrackingCircuitHandler>();

In Startup.ConfigureServices of Startup.cs:

services.AddSingleton<CircuitHandler, TrackingCircuitHandler>();

Closure of circuits when there are no remaining Interactive Server components

Interactive Server components handle web UI events using a real-time connection with the browser called a circuit. A circuit and its associated state are created when a root Interactive Server component is rendered. The circuit is closed when there are no remaining Interactive Server components on the page, which frees up server resources.

Blazor Web Apps:

- <script src="_framework/blazor.web.js"></script>
+ <script src="_framework/blazor.web.js" autostart="false"></script>
+ <script>
+   Blazor.start({
+     circuit: {
+       configureSignalR: builder => builder.withUrl("/signalr")
+     },
+   });
+ </script>

Blazor Server:

Blazor Web Apps:

app.MapBlazorHub("/signalr");

Blazor Server:

IHttpContextAccessor generally should be avoided with interactive rendering because a valid HttpContext isn't always available.

IHttpContextAccessor can be used for components that are statically rendered on the server. However, we recommend avoiding it if possible.

HttpContext can be used as a cascading parameter only in statically-rendered root components for general tasks, such as inspecting and modifying headers or other properties in the App component (Components/App.razor). The value is always null for interactive rendering.

[CascadingParameter]
public HttpContext? HttpContext { get; set; }

For scenarios where the HttpContext is required in interactive components, we recommend flowing the data via persistent component state from the server. For more information, see ASP.NET Core server-side and Blazor Web App additional security scenarios.

Don't use IHttpContextAccessor/HttpContext directly or indirectly in the Razor components of server-side Blazor apps. Blazor apps run outside of the ASP.NET Core pipeline context. The HttpContext isn't guaranteed to be available within the IHttpContextAccessor, and HttpContext isn't guaranteed to hold the context that started the Blazor app.

The recommended approach for passing request state to the Blazor app is through root component parameters during the app's initial rendering. Alternatively, the app can copy the data into a scoped service in the root component's initialization lifecycle event for use across the app. For more information, see ASP.NET Core server-side and Blazor Web App additional security scenarios.

A critical aspect of server-side Blazor security is that the user attached to a given circuit might become updated at some point after the Blazor circuit is established but the IHttpContextAccessor isn't updated. For more information on addressing this situation with custom services, see ASP.NET Core server-side and Blazor Web App additional security scenarios.