Skip to content

Reconnect UI component #34842

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guardrex merged 6 commits into from
Mar 10, 2025
Merged

Reconnect UI component #34842

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
abec238
Reconnect UI component
guardrex Feb 27, 2025
408b619
Updates
guardrex Feb 27, 2025
2244a1e
Updates
guardrex Feb 28, 2025
3a2593e
Updates
guardrex Feb 28, 2025
72be004
Updates
guardrex Mar 10, 2025
9091b6c
Updates
guardrex Mar 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 64 additions & 5 deletions aspnetcore/blazor/fundamentals/signalr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -519,7 +519,58 @@ If reconnection fails, the user is instructed to retry or reload the page:

If reconnection succeeds, user state is often lost. Custom code can be added to any component to save and reload user state across connection failures. For more information, see <xref:blazor/state-management>.

:::moniker range=">= aspnetcore-8.0"
:::moniker range=">= aspnetcore-10.0"

To create UI elements that track reconnection state, the following table describes:

* A set of `components-reconnect-*` CSS classes (**Css class** column) that are set or unset by Blazor on an element with an `id` of `components-reconnect-modal`.
* The `components-reconnect-state-changed` event value (**Event** column) that indicates a reconnection status change.

| CSS class | Event | Indicates&hellip; |
| --- | --- | --- |
| `components-reconnect-show` | `show` | A lost connection. The client is attempting to reconnect. The reconnection modal is shown. |
| `components-reconnect-hide` | `hide` | An active connection is re-established to the server. The reconnection model is closed. |
| `components-reconnect-retrying` | `retrying` | The client is attempting to reconnect. |
| `components-reconnect-failed` | `failed` | Reconnection failed, probably due to a network failure. |
| `components-reconnect-rejected` | `rejected` | Reconnection rejected. |

When the reconnection state change in `components-reconnect-state-changed` is `failed`, call `Blazor.reconnect()` in JavaScript to attempt reconnection.

When the reconnection state change is `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()` in JavaScript. 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 user's components are disposed.
* The server is restarted, or the app's worker process is recycled.

An element with an `id` of `components-reconnect-max-retries` displays the maximum number of reconnect retries:

```html
<span id="components-reconnect-max-retries"></span>
```

An element with an `id` of `components-reconnect-current-attempt` displays the current reconnect attempt:

```html
<span id="components-reconnect-current-attempt"></span>
```

An element with an `id` of `components-seconds-to-next-attempt` displays the number of seconds to the next reconnection attempt:

```html
<span id="components-seconds-to-next-attempt"></span>
```

The Blazor Web App project template includes a `ReconnectModal` component (`Components/Layout/ReconnectModal.razor`) with collocated stylesheet and JavaScript files (`ReconnectModal.razor.css`, `ReconnectModal.razor.js`) that can be customized as needed. These files can be examined in the ASP.NET Core reference source or by inspecting an app created from the Blazor Web App project template with Interactive WebAssembly or Interactive Auto rendering enabled:

* [`ReconnectModal` component](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor)
* [Stylesheet file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor.css)
* [JavaScript file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor.js)

[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]

:::moniker-end

:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"

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.

Expand Down Expand Up @@ -551,6 +602,8 @@ To customize the UI, define a single element with an `id` of `components-reconne

:::moniker-end

:::moniker range="< aspnetcore-10.0"

```cshtml
<div id="components-reconnect-modal">
Connection lost.<br>Attempting to reconnect...
Expand All @@ -562,7 +615,9 @@ To customize the UI, define a single element with an `id` of `components-reconne

Add the following CSS styles to the site's stylesheet.

:::moniker range=">= aspnetcore-8.0"
:::moniker-end

:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"

`wwwroot/app.css`:

Expand All @@ -574,6 +629,8 @@ Add the following CSS styles to the site's stylesheet.

:::moniker-end

:::moniker range="< aspnetcore-10.0"

```css
#components-reconnect-modal {
display: none;
Expand Down Expand Up @@ -604,13 +661,15 @@ The following table describes the CSS classes applied to the `components-reconne
| `components-reconnect-failed` | Reconnection failed, probably due to a network failure. To attempt reconnection, call `window.Blazor.reconnect()` in JavaScript. |
| `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()` in JavaScript. This connection state may result when:<ul><li>A crash in the server-side circuit occurs.</li><li>The client is disconnected long enough for the server to drop the user's state. Instances of the user's components are disposed.</li><li>The server is restarted, or the app's worker process is recycled.</li></ul> |

:::moniker range=">= aspnetcore-5.0"
:::moniker-end

:::moniker range=">= aspnetcore-5.0 < aspnetcore-10.0"

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

:::moniker-end

:::moniker range=">= aspnetcore-8.0"
:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"

`wwwroot/app.css`:

Expand All @@ -622,7 +681,7 @@ Customize the delay before the reconnection UI appears by setting the `transitio

:::moniker-end

:::moniker range=">= aspnetcore-5.0"
:::moniker range=">= aspnetcore-5.0 < aspnetcore-10.0"

```css
#components-reconnect-modal {
Expand Down
11 changes: 11 additions & 0 deletions aspnetcore/release-notes/aspnetcore-10/includes/blazor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,4 +36,15 @@ The [`[Route]` attribute](xref:Microsoft.AspNetCore.Components.RouteAttribute) n

Previously, <xref:Microsoft.AspNetCore.Components.NavigationManager.NavigateTo%2A?displayProperty=nameWithType> scrolled to the top of the page for same-page navigations. This behavior has been changed in .NET 10 so that the browser no longer scrolls to the top of the page when navigating to the same page. This means the viewport is no longer reset when making updates to the address for the current page, such as changing the query string or fragment.

### Reconnection UI component added to the Blazor Web App project template

The Blazor Web App project template now includes a `ReconnectModal` component, including collocated stylesheet and JavaScript files, for improved developer control over the reconnection UI when the client loses the WebSocket connection to the server. The component doesn't insert styles programmatically, so it doesn't violate stricter Content Security Policy (CSP) settings for the `style-src` policy. In prior releases, the default reconnection UI was created by the framework in a way that could cause CSP violations. Note that the default reconnection UI is still used as fallback when the app doesn't define the reconnection UI, such as by using the project template's `ReconnectModal` component or a similar custom component.

New reconnection UI features:

* Apart from indicating the reconnection state by setting a specific CSS class on the reconnection UI element, the new `components-reconnect-state-changed` event is dispatched for reconnection state changes.
* Code can better differentiate the stages of the reconnection process with the new reconnection state "`retrying`," indicated by both the CSS class and the new event.

For more information, see <xref:blazor/fundamentals/signalr?view=aspnetcore-10.0#reflect-the-server-side-connection-state-in-the-ui>.

-->