8.0 Update: SignalR Config: stateful reconnect (try 2) (#30850)

* v8.0 Update: SignalR Config: stateful reconnect * Apply suggestions from code review Co-authored-by: Brennan <brecon@microsoft.com> * Updated 8.0 what's new doc Co-authored-by: Tom Dykstra <tdykstra@microsoft.com> * Update aspnetcore/signalr/configuration.md Co-authored-by: Tom Dykstra <tdykstra@microsoft.com> * State default bytes for StatefulReconnectBufferSize --------- Co-authored-by: Brennan <brecon@microsoft.com> Co-authored-by: Tom Dykstra <tdykstra@microsoft.com>
dotnet · Oct 31, 2023 · 126e004 · 126e004
1 parent 9683200
commit 126e004
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 23 deletions.
diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md
@@ -4,7 +4,7 @@ author: rick-anderson
 description: Learn about the new features in ASP.NET Core 8.0.
 ms.author: riande
 ms.custom: mvc
-ms.date: 10/25/2023
+ms.date: 10/27/2023
 uid: aspnetcore-8
 ---
 # What's new in ASP.NET Core 8.0
@@ -407,16 +407,9 @@ Stateful reconnect achieves this by:
 * Acknowledging messages received (ACK-ing) by both the server and client.
 * Recognizing when a connection is returning and replaying messages that might have been sent while the connection was down.
 
-To opt in to stateful reconnect for a JavaScript or TypeScript client:
+Stateful reconnect is available in ASP.NET Core 8.0 and later.
 
-* Update the JavaScript or TypeScript client code to enable the `withStatefulReconnect` option:
-
-  ```JavaScript
-  const builder = new signalR.HubConnectionBuilder()
-    .withUrl("/hubname")
-    .withStatefulReconnect({ bufferSize: 1000 });  // Optional, defaults to 100,000
-  const connection = builder.build();
-  ```
+Opt in to stateful reconnect at both the server hub endpoint and the client:
 
 * Update the server hub endpoint configuration to enable the `AllowStatefulReconnects` option:
 
@@ -427,9 +420,34 @@ To opt in to stateful reconnect for a JavaScript or TypeScript client:
   });
   ```
 
-To opt in to stateful reconnect for a .NET client:
+  Optionally, the maximum buffer size in bytes allowed by the server can be set globally or for a specific hub with the `StatefulReconnectBufferSize` option:
+
+  The `StatefulReconnectBufferSize` option set globally:
+
+  ```csharp
+  builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
+  ```
+
+  The `StatefulReconnectBufferSize` option set for a specific hub:
+
+  ```csharp
+  builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
+  ```
+
+  The `StatefulReconnectBufferSize` option is optional with a default of 100,000 bytes.
 
-* Update the .NET client code to enable the `WithStatefulReconnect` option:
+* Update JavaScript or TypeScript client code to enable the `withStatefulReconnect` option:
+
+  ```JavaScript
+  const builder = new signalR.HubConnectionBuilder()
+    .withUrl("/hubname")
+    .withStatefulReconnect({ bufferSize: 1000 });  // Optional, defaults to 100,000
+  const connection = builder.build();
+  ```
+
+  The `bufferSize` option is optional with a default of 100,000 bytes.
+
+* Update .NET client code to enable the `WithStatefulReconnect` option:
 
   ```csharp
     var builder = new HubConnectionBuilder()
@@ -439,14 +457,9 @@ To opt in to stateful reconnect for a .NET client:
     var hubConnection = builder.Build();
   ```
 
-* Update the server hub endpoint configuration to enable the `AllowStatefulReconnects` option:
+  The `StatefulReconnectBufferSize` option is optional with a default of 100,000 bytes.
 
-  ```csharp
-  app.MapHub<MyHub>("/hubName", options =>
-  {
-      options.AllowStatefulReconnects = true;
-  });
-  ```
+For more information, see [Configure stateful reconnect](xref:signalr/configuration#configure-stateful-reconnect).
 
 ## Minimal APIs
 

diff --git a/aspnetcore/signalr/configuration.md b/aspnetcore/signalr/configuration.md
@@ -5,7 +5,7 @@ description: Learn how to configure ASP.NET Core SignalR apps.
 monikerRange: '>= aspnetcore-2.1'
 ms.author: bradyg
 ms.custom: mvc
-ms.date: 07/10/2023
+ms.date: 10/26/2023
 uid: signalr/configuration
 ---
 
@@ -68,9 +68,9 @@ The following table describes options for configuring SignalR hubs:
 | `SupportedProtocols` | All installed protocols | Protocols supported by this hub. By default, all protocols registered on the server are allowed. Protocols can be removed from this list to disable specific protocols for individual hubs. |
 | `EnableDetailedErrors` | `false` | If `true`, detailed exception messages are returned to clients when an exception is thrown in a Hub method. The default is `false` because these exception messages can contain sensitive information. |
 | `StreamBufferCapacity` | `10` | The maximum number of items that can be buffered for client upload streams. If this limit is reached, the processing of invocations is blocked until the server processes stream items.|
-| `MaximumReceiveMessageSize` | 32 KB | Maximum size of a single incoming hub message. Increasing the value may increase the risk of [Denial of service (DoS) attacks](https://developer.mozilla.org/docs/Glossary/DOS_attack). |
+| `MaximumReceiveMessageSize` | 32 KB | Maximum size of a single incoming hub message. Increasing the value might increase the risk of [Denial of service (DoS) attacks](https://developer.mozilla.org/docs/Glossary/DOS_attack). |
 | `MaximumParallelInvocationsPerClient` | 1 | The maximum number of hub methods that each client can call in parallel before queueing. |
-| `DisableImplicitFromServicesParameters` | `false` | Hub method arguments will be resolved from DI if possible. |
+| `DisableImplicitFromServicesParameters` | `false` | Hub method arguments are resolved from DI if possible. |
 
 Options can be configured for all hubs by providing an options delegate to the `AddSignalR` call in `Program.cs`.
 
@@ -108,7 +108,7 @@ The following table describes options for configuring ASP.NET Core SignalR's adv
 | `LongPolling` | See below. | Additional options specific to the Long Polling transport. |
 | `WebSockets` | See below. | Additional options specific to the WebSockets transport. |
 | `MinimumProtocolVersion` | 0 | Specify the minimum version of the negotiate protocol. This is used to limit clients to newer versions. |
-| `CloseOnAuthenticationExpiration` | false | Set this option to enable authentication expiration tracking which will close connections when a token expires. |
+| `CloseOnAuthenticationExpiration` | false | Set this option to enable authentication expiration tracking, which will close connections when a token expires. |
 
 The Long Polling transport has additional options that can be configured using the `LongPolling` property:
 
@@ -325,6 +325,68 @@ var connection = new signalR.HubConnectionBuilder()
 
 ---
 
+### Configure stateful reconnect
+
+SignalR stateful reconnect reduces the perceived downtime of clients that have a temporary disconnect in their network connection, such as when switching network connections or a short temporary loss in access.
+
+Stateful reconnect achieves this by:
+
+* Temporarily buffering data on the server and client.
+* Acknowledging messages received (ACK-ing) by both the server and client.
+* Recognizing when a connection is up and replaying messages that might have been sent while the connection was down.
+
+Stateful reconnect is available in ASP.NET Core 8.0 and later.
+
+Opt in to stateful reconnect at both the server hub endpoint and the client:
+
+* Update the server hub endpoint configuration to enable the `AllowStatefulReconnects` option:
+
+  ```csharp
+  app.MapHub<MyHub>("/hubName", options =>
+  {
+      options.AllowStatefulReconnects = true;
+  });
+  ```
+
+  Optionally, the maximum buffer size in bytes allowed by the server can be set globally or for a specific hub with the `StatefulReconnectBufferSize` option:
+
+  The `StatefulReconnectBufferSize` option set globally:
+
+  ```csharp
+  builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
+  ```
+
+  The `StatefulReconnectBufferSize` option set for a specific hub:
+
+  ```csharp
+  builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
+  ```
+
+  The `StatefulReconnectBufferSize` option is optional with a default of 100,000 bytes.
+
+* Update JavaScript or TypeScript client code to enable the `withStatefulReconnect` option:
+
+  ```JavaScript
+  const builder = new signalR.HubConnectionBuilder()
+    .withUrl("/hubname")
+    .withStatefulReconnect({ bufferSize: 1000 });  // Optional, defaults to 100,000
+  const connection = builder.build();
+  ```
+
+  The `bufferSize` option is optional with a default of 100,000 bytes.
+
+* Update .NET client code to enable the `WithStatefulReconnect` option:
+
+  ```csharp
+    var builder = new HubConnectionBuilder()
+        .WithUrl("<hub url>")
+        .WithStatefulReconnect();
+    builder.Services.Configure<HubConnectionOptions>(o => o.StatefulReconnectBufferSize = 1000);
+    var hubConnection = builder.Build();
+  ```
+
+  The `StatefulReconnectBufferSize` option is optional with a default of 100,000 bytes.
+
 ### Configure additional options
 
 Additional options can be configured in the `WithUrl` (`withUrl` in JavaScript) method on `HubConnectionBuilder` or on the various configuration APIs on the `HttpHubConnectionBuilder` in the Java client: