Add performance guidance for large async session-state reads in SQL

Readme.md

@@ -35,6 +35,11 @@ The specific settings available for the new session state module and providers a
 - [Microsoft.AspNet.SessionState.SqlSessionStateProviderAsync](docs/SqlSessionStateProviderAsync.md)
 - [Microsoft.AspNet.SessionState.CosmosDBSessionStateProviderAsync](docs/CosmosDBSessionStateProviderAsync.md)
 
+## SQL Provider Async Read Performance
+Applications using `Microsoft.AspNet.SessionState.SqlSessionStateProviderAsync`, especially those that store large session-state payloads, should use `Microsoft.Data.SqlClient` 7.0 or later and evaluate its opt-in packet-multiplexing path for large async reads. Enable that path by setting both `Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour` and `Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni` to `false`.
+
+See the [SQL provider configuration and performance guidance](docs/SqlSessionStateProviderAsync.md#performance-of-large-async-session-reads), Microsoft's documentation for [packet multiplexing and the SqlClient AppContext switches](https://learn.microsoft.com/en-us/sql/connect/ado-net/appcontext-switches?view=sql-server-ver17#enable-packet-multiplexing-for-async-reads), and the [Microsoft.Data.SqlClient 7.0 release notes](https://github.com/dotnet/SqlClient/blob/main/release-notes/7.0/7.0.0.md#async-read-performance-packet-multiplexing-preview). Packet multiplexing is disabled by default for compatibility, affects all SqlClient use in the application, and should be tested with the application's workload before production deployment.
+
 <a name="updates"></a>
 ## V2.1 Updates:
   * New `ISessionStateItemCollection` implementations for concurrent access. The `SessionStateItemCollection` that comes in the framework is not thread-safe and can cause issues when multiple threads are trying to access the same session state, which is something that is allowed with this package and the `AllowConcurrentRequestsPerSession` setting. When this feature is enabled, the providers in this repo will use the new thread-safe implementations: `ConcurrentNonSerializingSessionStateItemCollection` for the In-Proc provider, since it does not need to serialize session state data, and `ConcurrentSessionStateItemCollection` for the SQL and CosmosDB providers, since they do need to serialize session state data. This latter implementation is as direct of a port from the .Net framework as possible while fixing the concurrency issue with the original implementaiton.

docs/SqlSessionStateProviderAsync.md

@@ -15,6 +15,23 @@ Then, register your new provider like so:
   </sessionState>
 ```
 
+## Performance of Large Async Session Reads
+Applications that store large session-state payloads should use `Microsoft.Data.SqlClient` 7.0 or later. Version 7.0 introduced an opt-in packet-multiplexing path that can substantially improve the performance of large async reads while allowing this provider to continue releasing ASP.NET worker threads during database I/O.
+
+Packet multiplexing is disabled by default for compatibility. On .NET Framework, it can be enabled early in application startup by adding both switches to the application's `web.config`:
+
+```xml
+<configuration>
+  <runtime>
+    <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour=false;Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni=false" />
+  </runtime>
+</configuration>
+```
+
+If the application already has an `AppContextSwitchOverrides` element, add these semicolon-separated values to its existing `value` attribute rather than adding another element. The switches affect all SqlClient use in the application, so test the configuration with the application's workload before deploying it to production.
+
+See Microsoft's documentation for [packet multiplexing and the SqlClient AppContext switches](https://learn.microsoft.com/en-us/sql/connect/ado-net/appcontext-switches?view=sql-server-ver17#enable-packet-multiplexing-for-async-reads), the [.NET Framework `AppContextSwitchOverrides` configuration element](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element), and the [Microsoft.Data.SqlClient 7.0 release notes](https://github.com/dotnet/SqlClient/blob/main/release-notes/7.0/7.0.0.md#async-read-performance-packet-multiplexing-preview).
+
 ## A Note About Tables and Data Durability
 The old in-box SQL provider allowed for applications to choose between three data configurations by using the `-sstype` argument to `aspnet_regsql.exe`. Those types were <u>*p*</u>ermanent, <u>*t*</u>emporary, or <u>*c*</u>ustom. The difference between all three is simply the database and table name used by `aspnet_regsql.exe` and the application at runtime.
  * With the permanent option, session state would be stored in a hard-coded well-known table name in the database specified by the connection string. The table schema and data are "permanent" in this setup because they survive SQL server reboot.