|
| 1 | +# Release Notes |
| 2 | + |
| 3 | +## Microsoft.Data.SqlClient 3.0.0-preview1.21075.2 released 15 March 2021 |
| 4 | + |
| 5 | +This update brings the below changes over the previous release: |
| 6 | + |
| 7 | +### Breaking Changes over stable release v2.1 |
| 8 | +- The minimum supported .NET Framework version has been increased to v4.6.1. .NET Framework v4.6.0 is no longer supported. [#899](https://github.com/dotnet/SqlClient/pull/899) |
| 9 | + |
| 10 | +### Added |
| 11 | +- Added support for Configurable Retry Logic [#693](https://github.com/dotnet/SqlClient/pull/693) [#966](https://github.com/dotnet/SqlClient/pull/966) [Read more](#configurable-retry-logic) |
| 12 | +- Added support for Event counters in .NET Core 3.1+ and .NET Standard 2.1+ [#719](https://github.com/dotnet/SqlClient/pull/719) [Read more](#event-counters) |
| 13 | +- Added support for Assembly Context Unloading in .NET Core [#913](https://github.com/dotnet/SqlClient/pull/913) |
| 14 | +- Added missing `System.Runtime.Caching` dependency for .NET Standard assemblies [#877](https://github.com/dotnet/SqlClient/pull/877) |
| 15 | + |
| 16 | +### Fixed |
| 17 | +- Fixed wrong results issues by changing the timeout timer to ensure a correct execution state [#906](https://github.com/dotnet/SqlClient/pull/906) |
| 18 | +- Fixed Kerberos authentication issues when configured Server Principal Name (SPN) didn't contain default port [#930](https://github.com/dotnet/SqlClient/pull/930) |
| 19 | +- Fixed MARS header errors when `MakeReadAsyncBlocking` App Context switch is set to `false` [#910](https://github.com/dotnet/SqlClient/pull/910) [#922](https://github.com/dotnet/SqlClient/pull/922) |
| 20 | +- Fixed unwanted exceptions being thrown from `SqlDataReader.Dispose` [#920](https://github.com/dotnet/SqlClient/pull/920) |
| 21 | +- Fixed issues connecting to SQL Server instance with instance name specified from Unix environment [#870](https://github.com/dotnet/SqlClient/pull/870) |
| 22 | +- Fixed TCP Keep Alive issues in .NET Core [#854](https://github.com/dotnet/SqlClient/pull/854) |
| 23 | +- Fixed Kerberos Authentication issues caused due to regression [#845](https://github.com/dotnet/SqlClient/pull/845) |
| 24 | +- Fixed issues with System-Assigned Managed Identity in Azure Functions [#829](https://github.com/dotnet/SqlClient/pull/829) |
| 25 | +- Fixed missing error messages in Managed SNI [#882](https://github.com/dotnet/SqlClient/pull/882) |
| 26 | +- Fixed event source trace string issue [#940](https://github.com/dotnet/SqlClient/pull/940) |
| 27 | + |
| 28 | +### Changes |
| 29 | +- Changed App Context switch `MakeReadAsyncBlocking` default to `false` [#937](https://github.com/dotnet/SqlClient/pull/937) |
| 30 | +- Replaced usage of `BinaryFormatter` with `DataContractSerializer` [#869](https://github.com/dotnet/SqlClient/pull/869) |
| 31 | +- Prohibited `DtdProcessing` on `XmlTextReader` instance in .NET Core [#884](https://github.com/dotnet/SqlClient/pull/884) |
| 32 | +- Improved performance by reducing memory allocations in `SerializeEncodingChar`/`WriteEncodingChar` and some options boxing [#785](https://github.com/dotnet/SqlClient/pull/785) |
| 33 | +- Improved performance by preventing orphaned active packets being GC'ed without clear [#888](https://github.com/dotnet/SqlClient/pull/888) |
| 34 | +- Various performance improvements [#889](https://github.com/dotnet/SqlClient/pull/889) [#900](https://github.com/dotnet/SqlClient/pull/900) |
| 35 | +- Partial event source tracing improvements in .NET Core [#867](https://github.com/dotnet/SqlClient/pull/867) [#897](https://github.com/dotnet/SqlClient/pull/897) |
| 36 | +- Changes to share common files between NetFx and NetCore source code [#827](https://github.com/dotnet/SqlClient/pull/827) [#835](https://github.com/dotnet/SqlClient/pull/835) [#838](https://github.com/dotnet/SqlClient/pull/838) [#881](https://github.com/dotnet/SqlClient/pull/881) |
| 37 | + |
| 38 | + |
| 39 | +## New features over stable release v2.1 |
| 40 | + |
| 41 | +### Configurable Retry Logic |
| 42 | + |
| 43 | +This new feature introduces configurable support for client applications to retry on "transient" or "retriable" errors. Configuration can be done through code or app config files and retry operations can be applied to opening a connection or executing a command. This feature is disabled by default and is currently in preview. To enable this support, client applications must turn on the following safety switch: |
| 44 | + |
| 45 | +`AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);` |
| 46 | + |
| 47 | +Once the .NET AppContext switch is enabled, a retry logic policy can be defined for `SqlConnection` and `SqlCommand` independently, or together using various customization options. |
| 48 | + |
| 49 | +New public APIs are introduced in `SqlConnection` and `SqlCommand` for registering a custom `SqlRetryLogicBaseProvider` implementation: |
| 50 | + |
| 51 | +```cs |
| 52 | +public SqlConnection |
| 53 | +{ |
| 54 | + public SqlRetryLogicBaseProvider RetryLogicProvider; |
| 55 | +} |
| 56 | + |
| 57 | +public SqlCommand |
| 58 | +{ |
| 59 | + public SqlRetryLogicBaseProvider RetryLogicProvider; |
| 60 | +} |
| 61 | + |
| 62 | +``` |
| 63 | + |
| 64 | +API Usage examples can be found here: |
| 65 | +[SqlConnection retry sample](..\..\doc\samples\SqlConfigurableRetryLogic_OpenConnection.cs) |
| 66 | +[SqlCommand retry sample](..\..\doc\samples\SqlConfigurableRetryLogic_SqlCommand.cs) |
| 67 | +[Sample for retry logic options](..\..\doc\samples\SqlConfigurableRetryLogic_SqlRetryLogicOptions.cs) |
| 68 | + |
| 69 | +New configuration sections have also been introduced to do the same registration from configuration files, without having to modify existing code: |
| 70 | + |
| 71 | +```xml |
| 72 | +<section name="SqlConfigurableRetryLogicConnection" |
| 73 | + type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/> |
| 74 | + |
| 75 | +<section name="SqlConfigurableRetryLogicCommand" |
| 76 | + type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/> |
| 77 | +``` |
| 78 | + |
| 79 | +A simple example of using the new configuration sections in configuration files is below: |
| 80 | + |
| 81 | +```xml |
| 82 | +<?xml version="1.0" encoding="utf-8" ?> |
| 83 | +<configuration> |
| 84 | + <configSections> |
| 85 | + <section name="SqlConfigurableRetryLogicConnection" |
| 86 | + type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/> |
| 87 | + <section name="SqlConfigurableRetryLogicCommand" |
| 88 | + type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/> |
| 89 | + |
| 90 | + <section name="AppContextSwitchOverrides" |
| 91 | + type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/> |
| 92 | + </configSections> |
| 93 | + |
| 94 | + <!--Enable safety switch in .NET Core--> |
| 95 | + <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/> |
| 96 | + |
| 97 | + <!--Retry method for SqlConnection--> |
| 98 | + <SqlConfigurableRetryLogicConnection retryMethod ="CreateFixedRetryProvider" numberOfTries ="3" deltaTime ="00:00:10" maxTime ="00:00:30" |
| 99 | + transientErrors="40615" /> |
| 100 | + |
| 101 | + <!--Retry method for SqlCommand containing SELECT queries--> |
| 102 | + <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider" numberOfTries ="5" deltaTime ="00:00:10" maxTime ="00:01:10" |
| 103 | + authorizedSqlCondition="\b(SELECT)\b" transientErrors="102, 4060, 0"/> |
| 104 | +</configuration> |
| 105 | +``` |
| 106 | + |
| 107 | +Alternatively, applications can implement their own provider of the `SqlRetryLogicBaseProvider` base class, and register it with `SqlConnection`/`SqlCommand`. |
| 108 | + |
| 109 | +### Event Counters |
| 110 | + |
| 111 | +The following counters are now available for applications targeting .NET Core 3.1+ and .NET Standard 2.1+: |
| 112 | + |
| 113 | +- **HardConnects**: The number of physical connections that are being made. |
| 114 | +- **HardDisconnects**: The number of actual disconnects that are being made. |
| 115 | +- **ActiveHardConnections**: The number of active physical connections that are being made. |
| 116 | +- **SoftConnects**: The number of connections acquired from the pool. |
| 117 | +- **SoftDisconnects**: The number of connections returned to the pool. |
| 118 | +- **ActiveSoftConnections**: The total number of active pooled connections. |
| 119 | +- **NumberOfNonPooledConnections**: The total number of non-pooled connections. |
| 120 | +- **NumberOfPooledConnections**: The total number of pooled connections. |
| 121 | +- **NumberOfActiveConnectionPoolGroups**: The number of unique connection pool groups. |
| 122 | +- **NumberOfInactiveConnectionPoolGroups**: The number of unique connection pool groups to be pruned. |
| 123 | +- **NumberOfActiveConnectionPools**: The number of active connection pools. |
| 124 | +- **NumberOfInactiveConnectionPools**: The number of inactive connection pools. |
| 125 | +- **NumberOfActiveConnections**: The number of active connections currently in-use. |
| 126 | +- **NumberOfFreeConnections**: The number of free connections available for use. |
| 127 | +- **NumberOfStasisConnections**: The number of active free connections with open transactions. |
| 128 | +- **NumberOfReclaimedConnections**: The number of connections reclaimed from GC'd external connections. |
| 129 | + |
| 130 | +These counters can be used with .NET Core global CLI tools: `dotnet-counters` and `dotnet-trace` in Windows or Linux and PerfView in Windows, using `Microsoft.Data.SqlClient.EventSource` as the provider name. |
| 131 | + |
| 132 | +```cmd |
| 133 | +dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p |
| 134 | +PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 collect |
| 135 | +``` |
| 136 | + |
| 137 | +## Target Platform Support |
| 138 | + |
| 139 | +- .NET Framework 4.6.1+ (Windows x86, Windows x64) |
| 140 | +- .NET Core 2.1+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS) |
| 141 | +- .NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS) |
| 142 | + |
| 143 | +### Dependencies |
| 144 | + |
| 145 | +#### .NET Framework 4.6.1 |
| 146 | + |
| 147 | +- Microsoft.Data.SqlClient.SNI 2.1.1 |
| 148 | +- Microsoft.Identity.Client 4.21.1 |
| 149 | +- Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0 |
| 150 | +- Microsoft.IdentityModel.JsonWebTokens 6.8.0 |
| 151 | + |
| 152 | +#### .NET Core 2.1 |
| 153 | + |
| 154 | +- Microsoft.Data.SqlClient.SNI.runtime 2.1.1 |
| 155 | +- Microsoft.Win32.Registry 4.7.0 |
| 156 | +- System.Security.Principal.Windows 4.7.0 |
| 157 | +- System.Text.Encoding.CodePages 4.7.0 |
| 158 | +- System.Diagnostics.DiagnosticSource 4.7.0 |
| 159 | +- System.Configuration.ConfigurationManager 4.7.0 |
| 160 | +- System.Runtime.Caching 4.7.0 |
| 161 | +- Microsoft.Identity.Client 4.21.1 |
| 162 | +- Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0 |
| 163 | +- Microsoft.IdentityModel.JsonWebTokens 6.8.0 |
| 164 | + |
| 165 | +#### .NET Core 3.1 |
| 166 | + |
| 167 | +- Microsoft.Data.SqlClient.SNI.runtime 2.1.1 |
| 168 | +- Microsoft.Win32.Registry 4.7.0 |
| 169 | +- System.Security.Principal.Windows 4.7.0 |
| 170 | +- System.Text.Encoding.CodePages 4.7.0 |
| 171 | +- System.Diagnostics.DiagnosticSource 4.7.0 |
| 172 | +- System.Configuration.ConfigurationManager 4.7.0 |
| 173 | +- System.Runtime.Caching 4.7.0 |
| 174 | +- Microsoft.Identity.Client 4.21.1 |
| 175 | +- Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0 |
| 176 | +- Microsoft.IdentityModel.JsonWebTokens 6.8.0 |
| 177 | + |
| 178 | +#### .NET Standard 2.0 |
| 179 | + |
| 180 | +- Microsoft.Data.SqlClient.SNI.runtime 2.1.1 |
| 181 | +- Microsoft.Win32.Registry 4.7.0 |
| 182 | +- System.Buffers 4.5.1 |
| 183 | +- System.Memory 4.5.4 |
| 184 | +- System.Security.Principal.Windows 4.7.0 |
| 185 | +- System.Text.Encoding.CodePages 4.7.0 |
| 186 | +- System.Runtime.Caching 4.7.0 |
| 187 | +- Microsoft.Identity.Client 4.21.1 |
| 188 | +- Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0 |
| 189 | +- Microsoft.IdentityModel.JsonWebTokens 6.8.0 |
| 190 | + |
| 191 | +#### .NET Standard 2.1 |
| 192 | + |
| 193 | +- Microsoft.Data.SqlClient.SNI.runtime 2.1.1 |
| 194 | +- Microsoft.Win32.Registry 4.7.0 |
| 195 | +- System.Buffers 4.5.1 |
| 196 | +- System.Memory 4.5.4 |
| 197 | +- System.Security.Principal.Windows 4.7.0 |
| 198 | +- System.Text.Encoding.CodePages 4.7.0 |
| 199 | +- System.Runtime.Caching 4.7.0 |
| 200 | +- Microsoft.Identity.Client 4.21.1 |
| 201 | +- Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0 |
| 202 | +- Microsoft.IdentityModel.JsonWebTokens 6.8.0 |
0 commit comments