Skip to content

Commit abec238

Browse files
guardrexguardrex
committed
Reconnect UI component
1 parent 5415186 commit abec238

File tree

2 files changed

+78
-5
lines changed

2 files changed

+78
-5
lines changed

‎aspnetcore/blazor/fundamentals/signalr.md‎

Lines changed: 67 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -519,7 +519,63 @@ If reconnection fails, the user is instructed to retry or reload the page:
519519

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

522-
:::moniker range=">= aspnetcore-8.0"
522+
:::moniker range=">= aspnetcore-10.0"
523+
524+
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:
525+
526+
* [`ReconnectModal` component](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor)
527+
* [Stylesheet file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor.css)
528+
* [JavaScript file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor.js)
529+
530+
[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]
531+
532+
The `components-reconnect-state-changed` event indicates a reconnection status change:
533+
534+
* `show`: The reconnection modal is shown.
535+
* `hide`: The reconnection model is closed.
536+
* `retrying`: Reconnect attempts are in progress.
537+
* `failed`: A reconnection attempt has failed.
538+
* `rejected`: A reconnection attempt was received but rejected.
539+
540+
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.
541+
542+
| CSS class | Event | Indicates&hellip; |
543+
| --- | --- | --- |
544+
| `components-reconnect-show` | `show` | A lost connection. The client is attempting to reconnect. Show the modal. |
545+
| `components-reconnect-hide` | `hide` | An active connection is re-established to the server. Hide the modal. |
546+
| `components-reconnect-retrying` | `retrying` | The client is attempting to reconnect. |
547+
| `components-reconnect-failed` | `failed` | Reconnection failed, probably due to a network failure. To attempt reconnection, call `Blazor.reconnect()` in JavaScript. |
548+
| `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> |
549+
550+
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.
551+
552+
| CSS class | Event | Indicates&hellip; |
553+
| --- | --- | --- |
554+
| `components-reconnect-first-attempt-visible` | `retrying` | Displayed on the first retry attempt. |
555+
| `components-reconnect-repeated-attempt-visible` | `retrying` | Displayed on the subsequent retry attempts. |
556+
| `components-reconnect-failed-visible` | `failed`/`rejected` | Displayed when reconnection attempts have failed or a reconnection attempt has been rejected. |
557+
558+
To display the maximum number of reconnect retries, define an element with an `id` of `components-reconnect-max-retries`:
559+
560+
```html
561+
<span id="components-reconnect-max-retries"></span>
562+
```
563+
564+
To display the current reconnect attempt, define an element with an `id` of `components-reconnect-current-attempt`:
565+
566+
```html
567+
<span id="components-reconnect-current-attempt"></span>
568+
```
569+
570+
To display the number of seconds to the next reconnection attempt, define an element with an `id` of `components-seconds-to-next-attempt`:
571+
572+
```html
573+
<span id="components-seconds-to-next-attempt"></span>
574+
```
575+
576+
:::moniker-end
577+
578+
:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"
523579

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

@@ -551,6 +607,8 @@ To customize the UI, define a single element with an `id` of `components-reconne
551607

552608
:::moniker-end
553609

610+
:::moniker range="< aspnetcore-10.0"
611+
554612
```cshtml
555613
<div id="components-reconnect-modal">
556614
Connection lost.<br>Attempting to reconnect...
@@ -562,7 +620,9 @@ To customize the UI, define a single element with an `id` of `components-reconne
562620
563621
Add the following CSS styles to the site's stylesheet.
564622

565-
:::moniker range=">= aspnetcore-8.0"
623+
:::moniker-end
624+
625+
:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"
566626

567627
`wwwroot/app.css`:
568628

@@ -574,6 +634,8 @@ Add the following CSS styles to the site's stylesheet.
574634

575635
:::moniker-end
576636

637+
:::moniker range="< aspnetcore-10.0"
638+
577639
```css
578640
#components-reconnect-modal {
579641
display: none;
@@ -604,13 +666,13 @@ The following table describes the CSS classes applied to the `components-reconne
604666
| `components-reconnect-failed` | Reconnection failed, probably due to a network failure. To attempt reconnection, call `window.Blazor.reconnect()` in JavaScript. |
605667
| `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> |
606668

607-
:::moniker range=">= aspnetcore-5.0"
669+
:::moniker range=">= aspnetcore-5.0 < aspnetcore-10.0"
608670

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

611673
:::moniker-end
612674

613-
:::moniker range=">= aspnetcore-8.0"
675+
:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"
614676

615677
`wwwroot/app.css`:
616678

@@ -622,7 +684,7 @@ Customize the delay before the reconnection UI appears by setting the `transitio
622684

623685
:::moniker-end
624686

625-
:::moniker range=">= aspnetcore-5.0"
687+
:::moniker range=">= aspnetcore-5.0 < aspnetcore-10.0"
626688

627689
```css
628690
#components-reconnect-modal {

‎aspnetcore/release-notes/aspnetcore-10/includes/blazor.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,4 +36,15 @@ The [`[Route]` attribute](xref:Microsoft.AspNetCore.Components.RouteAttribute) n
3636
3737
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.
3838
39+
### Reconnection UI component added to the Blazor Web App template
40+
41+
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 faced the reconnection UI in prior releases.
42+
43+
New reconnection UI features:
44+
45+
* Apart from indicating the reconnection state by setting a specific CSS class on the element with the `components-reconnect-modal` ID, it also dispatches a custom event in `components-reconnect-state-changed` that can be listened for on the modal element.
46+
* The new reconnection state `retrying` is indicated by both a CSS class and the custom event, so that code can better differentiate the stages of the reconnection process.
47+
48+
For more information, see <xref:blazor/fundamentals/signalr?view=aspnetcore-10.0#reflect-the-server-side-connection-state-in-the-ui>.
49+
3950
-->

0 commit comments

Comments
 (0)