Server timeout and Keep Alive interval config (#29297)

dotnet · Jun 2, 2023 · f566ed9 · f566ed9
1 parent df43a44
commit f566ed9
Show file tree

Hide file tree

Showing 4 changed files with 233 additions and 13 deletions.
diff --git a/aspnetcore/blazor/fundamentals/signalr.md b/aspnetcore/blazor/fundamentals/signalr.md
@@ -438,12 +438,57 @@ For more information, including how to initialize Blazor when the document is re
 
 ## Configure SignalR timeouts and Keep-Alive on the client
 
+:::moniker range=">= aspnetcore-8.0"
+
+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 `Pages/_Host.cshtml` file (Blazor Server) or `wwwroot/index.html` (Blazor WebAssembly) shows the assignment of default values:
+
+```html
+<script src="_framework/blazor.{HOSTING MODEL}.js" autostart="false"></script>
+<script>
+  Blazor.start({
+    configureSignalR: function (builder) {
+      builder.withServerTimeout(30000).withKeepAliveInterval(15000);
+    }
+  });
+</script>
+```
+
+In the preceding markup, the `{HOSTING MODEL}` placeholder is either `server` for a Blazor Server app or `webassembly` for a Blazor WebAssembly app.
+
+When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds) and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval> (default: 15 seconds) on the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnectionBuilder>. Set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds) on the built <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection>. The following example, based on the `Index` component in the [SignalR with Blazor tutorial](xref:blazor/tutorials/signalr-blazor), shows the assignment of default values:
+
+```csharp
+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();
+}
+```
+
+:::moniker-end
+
+:::moniker range="< aspnetcore-8.0"
+
 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 6.0), `Pages/_Layout.cshtml` file (Blazor Server, ASP.NET Core 6.0), or `wwwroot/index.html` (Blazor WebAssembly) uses default values:
+The following example for the `Pages/_Host.cshtml` file (Blazor Server, all versions except ASP.NET Core 6.0), `Pages/_Layout.cshtml` file (Blazor Server, ASP.NET Core 6.0), or `wwwroot/index.html` (Blazor WebAssembly) shows the assignment of default values:
 
 ```html
 <script src="_framework/blazor.{HOSTING MODEL}.js" autostart="false"></script>
@@ -463,7 +508,7 @@ The following example for the `Pages/_Host.cshtml` file (Blazor Server, all vers
 
 In the preceding markup, the `{HOSTING MODEL}` placeholder is either `server` for a Blazor Server app or `webassembly` for a Blazor WebAssembly app.
 
-When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds), <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds), and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval> (default: 15 seconds) on the built <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection>. The following example, based on the `Index` component in the [SignalR with Blazor tutorial](xref:blazor/tutorials/signalr-blazor), uses default values:
+When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds), <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds), and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval> (default: 15 seconds) on the built <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection>. The following example, based on the `Index` component in the [SignalR with Blazor tutorial](xref:blazor/tutorials/signalr-blazor), shows the assignment of default values:
 
 ```csharp
 protected override async Task OnInitializedAsync()
@@ -482,6 +527,8 @@ protected override async Task OnInitializedAsync()
 }
 ```
 
+:::moniker-end
+
 When changing the values of the server timeout (<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout>) or the Keep-Alive interval (<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval>:
 
 * The server timeout should be at least double the value assigned to the Keep-Alive interval.

diff --git a/aspnetcore/blazor/host-and-deploy/server.md b/aspnetcore/blazor/host-and-deploy/server.md
@@ -83,6 +83,54 @@ If a deployed app frequently displays the reconnection UI due to ping timeouts c
 
 * **Client**
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-8.0"
+
+  Typically, double the value used for the server's <xref:Microsoft.AspNetCore.SignalR.HubOptions.KeepAliveInterval> to set the timeout for the client's server timeout (`withServerTimeout` or <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout>, default: 30 seconds).
+
+  > [!IMPORTANT]
+  > The Keep-Alive interval (`withKeepAliveInterval` or <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval>) isn't directly related to the reconnection UI appearing. The Keep-Alive interval doesn't necessarily need to be changed. If the reconnection UI appearance issue is due to timeouts, the server timeout can be increased and the Keep-Alive interval can remain the same. The important consideration is that if you change the Keep-Alive interval, make sure that the timeout value is at least double the value of the Keep-Alive interval and that the Keep-Alive interval on the server matches the client setting.
+  >
+  > In the following example, a custom value of 60 seconds is used for the server timeout.
+
+  In `Pages/_Host.cshtml` of a Blazor Server app:
+
+  ```html
+  <script src="_framework/blazor.server.js" autostart="false"></script>
+  <script>
+    Blazor.start({
+      configureSignalR: function (builder) {
+        builder.withServerTimeout(60000);
+      }
+    });
+  </script>
+  ```
+
+  When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds) on the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnectionBuilder>. Set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds) on the built <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection>.
+
+  The following example is based on the `Index` component in the [SignalR with Blazor tutorial](xref:blazor/tutorials/signalr-blazor). The server timeout is increased to 60 seconds, and the handshake timeout is increased to 30 seconds:
+
+  ```csharp
+  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();
+  }
+  ```
+
+:::moniker-end
+
+:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"
+
   Typically, double the value used for the server's <xref:Microsoft.AspNetCore.SignalR.HubOptions.KeepAliveInterval> to set the timeout for the client's server timeout (`serverTimeoutInMilliseconds` or <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout>, default: 30 seconds).
 
   > [!IMPORTANT]
@@ -108,7 +156,7 @@ If a deployed app frequently displays the reconnection UI due to ping timeouts c
   ```
 
   When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds) and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds) on the built <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection>.
-  
+
   The following example is based on the `Index` component in the [SignalR with Blazor tutorial](xref:blazor/tutorials/signalr-blazor). The server timeout is increased to 60 seconds, and the handshake timeout is increased to 30 seconds:
 
   ```csharp
@@ -127,6 +175,10 @@ If a deployed app frequently displays the reconnection UI due to ping timeouts c
   }
   ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-7.0"
+
   When changing the values of the server timeout (<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout>) or the Keep-Alive interval (<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval>:
 
   * The server timeout should be at least double the value assigned to the Keep-Alive interval.

diff --git a/aspnetcore/blazor/host-and-deploy/webassembly.md b/aspnetcore/blazor/host-and-deploy/webassembly.md
@@ -1099,10 +1099,34 @@ If a deployed app frequently displays the reconnection UI due to ping timeouts c
   >
   > In the following example, a custom value of 60 seconds is used for the server timeout.
 
-  When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds) and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds) on the built <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection>.
+  When creating a hub connection in a component, set the <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds) and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeTimeout> (default: 15 seconds).
 
   The following example is based on the `Index` component in the [SignalR with Blazor tutorial](xref:blazor/tutorials/signalr-blazor). The server timeout is increased to 60 seconds, and the handshake timeout is increased to 30 seconds:
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-8.0"
+
+  ```csharp
+  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();
+  }
+  ```
+
+:::moniker-end
+
+:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"
+
   ```csharp
   protected override async Task OnInitializedAsync()
   {
@@ -1119,6 +1143,10 @@ If a deployed app frequently displays the reconnection UI due to ping timeouts c
   }
   ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-7.0"
+
   When changing the values of the server timeout (<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout>) or the Keep-Alive interval (<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval>:
 
   * The server timeout should be at least double the value assigned to the Keep-Alive interval.

diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md
@@ -28,6 +28,99 @@ This article is under development and not complete. More information may be foun
 ## Blazor
 -->
 
+## SignalR
+
+### New approach to set the server timeout and Keep-Alive interval
+
+<xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.ServerTimeout> (default: 30 seconds) and <xref:Microsoft.AspNetCore.SignalR.Client.HubConnection.KeepAliveInterval> (default: 15 seconds) can be set directly on <xref:Microsoft.AspNetCore.SignalR.Client.HubConnectionBuilder>.
+
+#### Prior approach for JavaScript clients
+
+The following example shows the assignment of values that are double the default values in ASP.NET Core 7.0 or earlier:
+
+```javascript
+var connection = new signalR.HubConnectionBuilder()
+  .withUrl("/chatHub")
+  .build();
+
+connection.serverTimeoutInMilliseconds = 60000;
+connection.keepAliveIntervalInMilliseconds = 30000;
+```
+
+#### New approach for JavaScript clients
+
+The following example shows the ***new approach*** for assigning values that are double the default values in ASP.NET Core 8.0 or later:
+
+```javascript
+var connection = new signalR.HubConnectionBuilder()
+  .withUrl("/chatHub")
+  .withServerTimeoutInMilliseconds(60000)
+  .withKeepAliveIntervalInMilliseconds(30000)
+  .build();
+```
+
+#### Prior approach for the JavaScript client of a Blazor Server app
+
+The following example shows the assignment of values that are double the default values in ASP.NET Core 7.0 or earlier:
+
+```javascript
+Blazor.start({
+  configureSignalR: function (builder) {
+    let c = builder.build();
+    c.serverTimeoutInMilliseconds = 60000;
+    c.keepAliveIntervalInMilliseconds = 30000;
+    builder.build = () => {
+      return c;
+    };
+  }
+});
+```
+
+#### New approach for the JavaScript client of a Blazor Server app
+
+The following example shows the ***new approach*** for assigning values that are double the default values in ASP.NET Core 8.0 or later:
+
+```javascript
+Blazor.start({
+  configureSignalR: function (builder) {
+    builder.withServerTimeout(60000).withKeepAliveInterval(30000);
+  }
+});
+```
+
+#### Prior approach for .NET clients
+
+The following example shows the assignment of values that are double the default values in ASP.NET Core 7.0 or earlier:
+
+```csharp
+var builder = new HubConnectionBuilder()
+    .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
+    .Build();
+
+builder.ServerTimeout = TimeSpan.FromSeconds(60);
+builder.KeepAliveInterval = TimeSpan.FromSeconds(30);
+
+builder.On<string, string>("ReceiveMessage", (user, message) => ...
+
+await builder.StartAsync();
+```
+
+#### New approach for .NET clients
+
+The following example shows the ***new approach*** for assigning values that are double the default values in ASP.NET Core 8.0 or later:
+
+```csharp
+var builder = new HubConnectionBuilder()
+    .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
+    .WithServerTimeout(TimeSpan.FromSeconds(60))
+    .WithKeepAliveInterval(TimeSpan.FromSeconds(30))
+    .Build();
+
+builder.On<string, string>("ReceiveMessage", (user, message) => ...
+
+await builder.StartAsync();
+```
+
 ## Minimal APIs
 
 ### Binding to forms with IFormCollection, IFormFile, and IFormFileCollection
@@ -99,16 +192,16 @@ For more information, see <xref:fundamentals/servers/kestrel/endpoints> and <xre
 
 ### Code analysis in ASP.NET Core apps
 
-The following new analyzers are available in ASP.NET Core 8.0:
+The new analyzers shown in the following table are available in ASP.NET Core 8.0.
 
-| Diagnostic ID    | Breaking or non-breaking | Description |
-|-------|-------|----------------------------|
-| [ASP0020](xref:diagnostics/asp0020) | Non-breaking             | Complex types referenced by route parameters must be parsable |
-| [ASP0021](xref:diagnostics/asp0021) | Non-breaking             | The return type of the BindAsync method must be `ValueTask<T>` |
-| [ASP0022](xref:diagnostics/asp0022) | Non-breaking             | Route conflict detected between route handlers |
-| [ASP0023](xref:diagnostics/asp0023) | Non-breaking             | MVC: Route conflict detected between route handlers |
-| [ASP0024](xref:diagnostics/asp0024) | Non-breaking             | Route handler has multiple parameters with the `[FromBody]` attribute |
-| [ASP0025](xref:diagnostics/asp0025) | Non-breaking             | Use AddAuthorizationBuilder |
+| Diagnostic ID | Breaking or non-breaking | Description |
+| --- | --- | --- |
+| [ASP0020](xref:diagnostics/asp0020) | Non-breaking | Complex types referenced by route parameters must be parsable |
+| [ASP0021](xref:diagnostics/asp0021) | Non-breaking | The return type of the BindAsync method must be `ValueTask<T>` |
+| [ASP0022](xref:diagnostics/asp0022) | Non-breaking | Route conflict detected between route handlers |
+| [ASP0023](xref:diagnostics/asp0023) | Non-breaking | MVC: Route conflict detected between route handlers |
+| [ASP0024](xref:diagnostics/asp0024) | Non-breaking | Route handler has multiple parameters with the `[FromBody]` attribute |
+| [ASP0025](xref:diagnostics/asp0025) | Non-breaking | Use AddAuthorizationBuilder |
 
 <!--
 ## API controllers