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 4 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
74 changes: 69 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,63 @@ 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"

Customize the UI and reconnection behavior in the `ReconnectModal` component (`Components/Layout/ReconnectModal.razor`), its collocated stylesheet file (`ReconnectModal.razor.css`), and its collocated JavaScript file (`ReconnectModal.razor.js`). 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)]

The `components-reconnect-state-changed` event indicates a reconnection status change:

* `show`: The reconnection modal is shown.
* `hide`: The reconnection model is closed.
* `retrying`: Reconnect attempts are in progress.
* `failed`: A reconnection attempt failed.
* `rejected`: A reconnection attempt was received by the server but rejected.

The following table describes the CSS classes applied to the `components-reconnect-modal` element. The **Event** column represents the value of the matching `components-reconnect-state-changed` JavaScript event.

| CSS class | Event | Indicates&hellip; |
| --- | --- | --- |
| `components-reconnect-show` | `show` | A lost connection. The client is attempting to reconnect. Show the modal. |
| `components-reconnect-hide` | `hide` | An active connection is re-established to the server. Hide the modal. |
| `components-reconnect-retrying` | `retrying` | The client is attempting to reconnect. |
| `components-reconnect-failed` | `failed` | Reconnection failed, probably due to a network failure. To attempt reconnection, call `Blazor.reconnect()` in JavaScript. |
| `components-reconnect-rejected` | `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> |

Additional CSS classes to further control the style of rendered elements is described in the following table. The **Event** column represents the value of the matching `components-reconnect-state-changed` JavaScript event.

| CSS class | Event | Displayed on&hellip; |
| --- | --- | --- |
| `components-reconnect-first-attempt-visible` | `retrying` | The first retry attempt. |
| `components-reconnect-repeated-attempt-visible` | `retrying` | Subsequent retry attempts. |
| `components-reconnect-failed-visible` | `failed` | A failed reconnection attempt. |

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

:::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 +607,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 +620,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 +634,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 +666,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 +686,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 isn't required to inline styles programatically, so it doesn't violate stricter Content Security Policy (CSP) settings for the `style-src` policy, thus avoiding CSP violations that occurred with the reconnection UI in prior releases.

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

-->