diff --git a/docs/connect/ado-net/appcontext-switches.md b/docs/connect/ado-net/appcontext-switches.md index 3f5d5b014c1..75d93ede2d8 100644 --- a/docs/connect/ado-net/appcontext-switches.md +++ b/docs/connect/ado-net/appcontext-switches.md @@ -1,10 +1,9 @@ --- title: AppContext switches in SqlClient description: Learn about the AppContext switches available in SqlClient and how to use them to modify some default behaviors. -author: David-Engel -ms.author: davidengel -ms.reviewer: v-davidengel -ms.date: 05/10/2023 +author: cheenamalhotra +ms.author: cmalhotra +ms.date: 08/19/2025 ms.service: sql ms.subservice: connectivity ms.topic: conceptual @@ -18,18 +17,6 @@ ms.custom: sfi-ropc-nochange The AppContext class allows SqlClient to provide new functionality while continuing to support callers who depend on the previous behavior. Users can opt out of a change in behavior by setting specific AppContext switches. -## Force use of operating system encryption protocols - -[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)] - -Starting with Microsoft.Data.SqlClient 4.0, TLS 1.3 isn't supported by the driver and was removed from the supported protocols list by default. Users can switch back to forcing use of the operating system's client protocols, by setting the AppContext switch **"Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols"** to true: - -```csharp -AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols", true); -``` - -Starting with version 5.0, TLS 1.3 is supported in TDS 8.0 connections without having to use the above switch. TDS 8.0 is enabled when `Encrypt` is set to `Strict`. - ## Enabling decimal truncation behavior [!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)] @@ -102,23 +89,6 @@ Starting in version 3.0, ReadAsync runs asynchronously. Previous versions run Re AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false); ``` -## Enable configurable retry logic - -[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)] - -(Available starting with version 3.0) - -By default, configurable retry logic is disabled. To enable this feature, set the AppContext switch **Switch.Microsoft.Data.SqlClient.EnableRetryLogic** to `true` at application startup. This switch is required, even if a retry provider is assigned to a connection or command. - -```csharp -AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true); -``` - -* For information on how to enable the switch by using a configuration file see [Enable safety switch](configurable-retry-logic-config-file-sqlclient.md#enable-safety-switch). - -> [!NOTE] -> Starting from Microsoft.Data.SqlClient v4.0, the App Context switch "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" will no longer be required to use the configurable retry logic feature. The feature is now supported in production. The default behavior of the feature will continue to be a non-retry policy, which will need to be overridden by client applications to enable retries. - ## Enabling rowversion null behavior [!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)] diff --git a/docs/connect/ado-net/asynchronous-programming.md b/docs/connect/ado-net/asynchronous-programming.md index b49c3b39f7b..c4072b8cd18 100644 --- a/docs/connect/ado-net/asynchronous-programming.md +++ b/docs/connect/ado-net/asynchronous-programming.md @@ -1,9 +1,9 @@ --- title: Asynchronous programming description: Learn about asynchronous programming in the Microsoft SqlClient Data Provider for SQL Server. -author: David-Engel -ms.author: davidengel -ms.date: 12/04/2020 +author: cheenamalhotra +ms.author: cmalhotra +ms.date: 08/19/2025 ms.service: sql ms.subservice: connectivity ms.topic: conceptual @@ -29,6 +29,9 @@ The Microsoft SqlClient Data Provider for SQL Server includes methods from **Sys > [!TIP] > In the Microsoft SqlClient Data Provider for SQL Server, these legacy methods no longer require `Asynchronous Processing=true` in the connection string. +> [!WARNING] +> The `Asynchronous Processing` connection property is no longer supported in the Microsoft SqlClient Data Provider v4.0 onwards. + ## Asynchronous programming features These asynchronous programming features provide a simple technique to make code asynchronous. diff --git a/docs/connect/ado-net/configurable-retry-logic-config-file-sqlclient.md b/docs/connect/ado-net/configurable-retry-logic-config-file-sqlclient.md index b6b797a31de..ede9b915bf0 100644 --- a/docs/connect/ado-net/configurable-retry-logic-config-file-sqlclient.md +++ b/docs/connect/ado-net/configurable-retry-logic-config-file-sqlclient.md @@ -35,37 +35,9 @@ Default retry logic options for an application can be changed by adding the foll type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/> ``` -- `AppContextSwitchOverrides`: .NET Framework supports AppContext switches via an [AppContextSwitchOverrides](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) section, which doesn't need to be defined explicitly. To turn on a switch in **.NET Core**, you must specify this section. - -```csharp -
-``` - > [!NOTE] > The following configurations should be specified inside the `configuration` section. Declare these new sections to configure the default retry logic through an application configuration file. -### Enable safety switch - -> [!NOTE] -> Starting from Microsoft.Data.SqlClient v4.0, the App Context switch "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" will no longer be required to use the configurable retry logic feature. The feature is now supported in production. The default behavior of the feature will continue to be a non-retry policy, which will need to be overridden by client applications to enable retries. - -You can enable the safety switch through a configuration file. To learn how to enable it through application code, see [Enable configurable retry logic](appcontext-switches.md#enable-configurable-retry-logic). - -- **.NET Framework**: For more information, see [AppContextSwitchOverrides element](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element). - -```csharp - - - -``` - -- **.NET Core**: supports multiple, semi-colon (;) delimited switches like .NET Framework. - -```csharp - -``` - ### Connection section The following attributes can be used to specify the default retry logic for all instances in an application: @@ -159,7 +131,6 @@ The following attribute can also be set for all [!NOTE] -> Don't forget to enable the configurable retry logic switch before using it. For more information, see [Enable configurable retry logic](appcontext-switches.md#enable-configurable-retry-logic). - ## See also - [Microsoft.Data.SqlClient GitHub repository](https://github.com/dotnet/SqlClient/) diff --git a/docs/connect/ado-net/configurable-retry-logic-sqlclient-introduction.md b/docs/connect/ado-net/configurable-retry-logic-sqlclient-introduction.md index 4abf423238c..4d48e0862ea 100644 --- a/docs/connect/ado-net/configurable-retry-logic-sqlclient-introduction.md +++ b/docs/connect/ado-net/configurable-retry-logic-sqlclient-introduction.md @@ -27,20 +27,18 @@ This feature consists of three main components: ## Quick start -To use this feature, follow these four steps: +To use this feature, follow these steps: -1. Enable the safety switch in the preview version. For information on how to enable the AppContext safety switch, see [Enable configurable retry logic](appcontext-switches.md#enable-configurable-retry-logic). - -2. Define the retry logic options using . +1. Define the retry logic options using . In this sample, some of the retry parameters are set and the rest of them will use the default values. [!code-csharp[SqlConfigurableRetryLogic_StepByStep_OpenConnection#1](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_StepByStep_OpenConnection.cs#1)] -3. Create a retry logic provider using your object. +2. Create a retry logic provider using your object. [!code-csharp[SqlConfigurableRetryLogic_StepByStep_OpenConnection#2](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_StepByStep_OpenConnection.cs#2)] -4. Assign the instance to the or . +3. Assign the instance to the or . In this sample, the connection open command will retry if it hits one of the transient errors in the internal list for a maximum of five times. [!code-csharp[SqlConfigurableRetryLogic_StepByStep_OpenConnection#3](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_StepByStep_OpenConnection.cs#3)] @@ -53,6 +51,5 @@ In this sample, the connection open command will retry if it hits one of the tra - [Configurable retry logic core APIs in SqlClient](configurable-retry-logic-core-apis-sqlclient.md) - [Internal retry logic providers in SqlClient](internal-retry-logic-providers-sqlclient.md) - [Configurable retry logic configuration file with SqlClient](configurable-retry-logic-config-file-sqlclient.md) -- [Enable configurable retry logic](appcontext-switches.md#enable-configurable-retry-logic) - [Configurable retry logic in SqlClient](configurable-retry-logic.md) - [Microsoft ADO.NET for SQL Server](microsoft-ado-net-sql-server.md) diff --git a/docs/connect/ado-net/download-microsoft-sqlclient-data-provider.md b/docs/connect/ado-net/download-microsoft-sqlclient-data-provider.md index 97aa31332dd..2a957531c5e 100644 --- a/docs/connect/ado-net/download-microsoft-sqlclient-data-provider.md +++ b/docs/connect/ado-net/download-microsoft-sqlclient-data-provider.md @@ -3,7 +3,7 @@ title: Download Microsoft SqlClient Data Provider for SQL Server description: Download page for ADO.NET and Microsoft SqlClient Data Provider for SQL Server. author: cheenamalhotra ms.author: cmalhotra -ms.date: 06/19/2025 +ms.date: 08/19/2025 ms.service: sql ms.subservice: connectivity ms.topic: conceptual @@ -22,6 +22,7 @@ For more information about version compatibility and support, see [SQL version c ## Download supported versions of Microsoft SqlClient Data Provider for SQL Server +* [6.1.1](https://www.nuget.org/packages/Microsoft.Data.SqlClient/6.1.1) * [6.0.2](https://www.nuget.org/packages/Microsoft.Data.SqlClient/6.0.2) * [5.2.3](https://www.nuget.org/packages/Microsoft.Data.SqlClient/5.2.3) * [5.1.7](https://www.nuget.org/packages/Microsoft.Data.SqlClient/5.1.7) diff --git a/docs/connect/ado-net/introduction-microsoft-data-sqlclient-namespace.md b/docs/connect/ado-net/introduction-microsoft-data-sqlclient-namespace.md index 64e4aab7a0f..5dc163922fb 100644 --- a/docs/connect/ado-net/introduction-microsoft-data-sqlclient-namespace.md +++ b/docs/connect/ado-net/introduction-microsoft-data-sqlclient-namespace.md @@ -1,26 +1,99 @@ --- -title: Introduction to Microsoft.Data.SqlClient namespace +title: "Introduction to Microsoft.Data.SqlClient Namespace" description: Learn about the Microsoft.Data.SqlClient namespace and how it's the preferred way to connect to SQL for .NET applications. author: cheenamalhotra ms.author: cmalhotra -ms.date: 01/24/2025 +ms.reviewer: randolphwest +ms.date: 09/05/2025 ms.service: sql ms.subservice: connectivity ms.topic: conceptual -ms.custom: sfi-ropc-nochange +ms.custom: + - sfi-ropc-nochange --- # Introduction to Microsoft.Data.SqlClient namespace [!INCLUDE [Driver_ADONET_Download](../../includes/driver_adonet_download.md)] -The Microsoft.Data.SqlClient namespace is essentially a new version of the System.Data.SqlClient namespace. Microsoft.Data.SqlClient generally maintains the same API and backwards compatibility with System.Data.SqlClient. To migrate from System.Data.SqlClient to Microsoft.Data.SqlClient, for most applications, it's simple. Add a NuGet dependency on Microsoft.Data.SqlClient and update references and `using` statements to Microsoft.Data.SqlClient. +The Microsoft.Data.SqlClient namespace is essentially a new version of the System.Data.SqlClient namespace. Microsoft.Data.SqlClient generally maintains the same API and backward compatibility with System.Data.SqlClient. To migrate from System.Data.SqlClient to Microsoft.Data.SqlClient, for most applications, it's simple. Add a NuGet dependency on Microsoft.Data.SqlClient and update references and `using` statements to Microsoft.Data.SqlClient. -There are a few differences in less-used APIs compared to System.Data.SqlClient that may affect some applications. For those differences, refer to the useful [porting cheat sheet](https://github.com/dotnet/SqlClient/blob/main/porting-cheat-sheet.md). +There are a few differences in less-used APIs compared to System.Data.SqlClient that might affect some applications. For those differences, refer to the useful [porting cheat sheet](https://github.com/dotnet/SqlClient/blob/main/porting-cheat-sheet.md). ## API reference The Microsoft.Data.SqlClient API details can be found in the [.NET API Browser](/dotnet/api/microsoft.data.sqlclient). +## Release notes for Microsoft.Data.SqlClient 6.1 + +### New features in 6.1 + +#### Added dedicated SQL Server vector data type support + +*What changed:* + +- Optimized vector communications between MDS and SQL Server 2025, employing a custom binary format over the TDS protocol ([#3433](https://github.com/dotnet/SqlClient/pull/3433), [#3443](https://github.com/dotnet/SqlClient/pull/3443)). + +- Reduced processing load compared to existing JSON-based vector support. + +- Initial support for 32-bit single-precision floating point vectors. + +*Who benefits:* + +- Applications moving large vector data sets see beneficial improvements to processing times and memory requirements. +- Vector-specific APIs are ready to support future numeric representations with a consistent look-and-feel. + +*Effect:* + +- Reduced transmission and processing times for vector operations versus JSON using SQL Server 2025 preview: + + - Reads: 50x improvement + - Writes: 3.3x improvement + - Bulk Copy: 19x improvement + - (Observed with vector column of max 1998 size, and 10,000 records for each operation.) + +- Improved memory footprint due to the elimination of JSON serialization/deserialization and string representation bloat. + +- For backward compatibility with earlier SQL Server Vector implementations, applications might continue to use JSON strings to send/receive vector data, although they don't see any of the performance improvements noted previously. + +#### Revived .NET Standard 2.0 target support + +*What changed:* + +- Support for targeting .NET Standard 2.0 has returned ([#3381](https://github.com/dotnet/SqlClient/pull/3381)) +- Support had previously been removed in the 6.0 release, with the [community voicing concerns](https://github.com/dotnet/SqlClient/discussions/3115). + +*Who benefits:* + +- Libraries that depend on MDS might seamlessly target any of the following frameworks: + - .NET Standard 2.0 + - .NET Framework 4.6.2 and above + - .NET 8.0 + - .NET 9.0 +- Applications should continue to target runtimes. + - The MDS .NET Standard 2.0 target framework support doesn't include an actual implementation, and can't be used with a runtime. + - An application's build/publish process should always pick the appropriate MDS .NET/.NET Framework runtime implementation. + - Custom build/publish actions that incorrectly try to deploy the MDS .NET Standard 2.0 reference DLL at runtime aren't supported. + +*Effect:* + +- Libraries targeting .NET Standard 2.0 no longer receive warnings such as: + + ```output + warning NU1701: Package 'Microsoft.Data.SqlClient 6.0.2' was restored using '.NETFramework,Version=v4.6.1, .NETFramework,Version=v4.6.2, .NETFramework,Version=v4.7, .NETFramework,Version=v4.7.1, .NETFramework,Version=v4.7.2, .NETFramework,Version=v4.8, .NETFramework,Version=v4.8.1' instead of the project target framework '.NETStandard,Version=v2.0'. This package may not be fully compatible with your project. + ``` + +#### Other additions + +- Added support for special casing with Fabric endpoints. + ([#3084](https://github.com/dotnet/SqlClient/pull/3084)) + +### 6.1 Target platform support + +- .NET Framework 4.6.2+ (Windows Arm64, Windows x86, Windows x64) +- .NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) + +Full release notes, including dependencies, are available in the GitHub Repository: [6.1 Release Notes](https://github.com/dotnet/SqlClient/tree/main/release-notes/6.1). + ## Release notes for Microsoft.Data.SqlClient 6.0 ### Breaking changes in 6.0 @@ -48,7 +121,7 @@ The Microsoft.Data.SqlClient API details can be found in the [.NET API Browser]( JSON data type support is now available in Microsoft.Data.SqlClient v6.0. This release introduces the `SqlJson` type available as an extension to `System.Data.SqlDbTypes`: -```cs +```csharp using System; using System.Data.SqlTypes; using System.Text.Json; @@ -61,7 +134,7 @@ namespace Microsoft.Data.SqlTypes public class SqlJson : INullable { /// - /// Parameterless constructor. Initializes a new instance of the SqlJson class which + /// Parameterless constructor. Initializes a new instance of the SqlJson class which /// represents a null JSON value. /// public SqlJson() { } @@ -98,7 +171,7 @@ The JSON data type supports reading, writing, streaming, and bulk copy operation ### Introducing SqlClientDiagnostics -New types are available in the `Microsoft.Data.SqlClient.Diagnostics` namespace that provide a strongly-typed collection of key-value pairs. These types can be captured by consuming applications for gathering diagnostic events emitted by the driver. This release introduces the following types: +New types are available in the `Microsoft.Data.SqlClient.Diagnostics` namespace that provide a strongly typed collection of key-value pairs. These types can be captured by consuming applications for gathering diagnostic events emitted by the driver. This release introduces the following types: - `SqlClientCommandBefore` - `SqlClientCommandAfter` @@ -120,14 +193,14 @@ New types are available in the `Microsoft.Data.SqlClient.Diagnostics` namespace The default behavior of `SqlConnection.OpenAsync()` can be overridden to disable the ten-second delay and automatic connection retries triggered by transient errors. -```cs +```csharp using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;")) { await sqlConnection.OpenAsync(SqlConnectionOverrides.OpenWithoutRetry, cancellationToken); } ``` -## 6.0 Target platform support +### 6.0 Target platform support - .NET Framework 4.6.2+ (Windows x86, Windows x64) - .NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -151,11 +224,11 @@ Full release notes, including dependencies, are available in the GitHub Reposito - Added explicit version for major .NET version dependencies on System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0, and System.Diagnostics.DiagnosticSource 8.0.0 [#2303](https://github.com/dotnet/SqlClient/pull/2303) - Added the ability to generate debugging symbols in a separate package file [#2137](https://github.com/dotnet/SqlClient/pull/2137) -### Added new property `RowsCopied64` to SqlBulkCopy +#### Added new property `RowsCopied64` to SqlBulkCopy SqlBulkCopy has a new property `RowsCopied64` which supports `long` value types. -**Note that the existing `SqlBulkCopy.RowsCopied` behavior is unchanged. When the value exceeds `int.MaxValue`, `RowsCopied` can return a negative number.** +**The existing `SqlBulkCopy.RowsCopied` behavior is unchanged. When the value exceeds `int.MaxValue`, `RowsCopied` can return a negative number.** Example usage: @@ -182,13 +255,13 @@ Example usage: } ``` -### Added new property `AccessTokenCallBack` to SqlConnection +#### Added new property `AccessTokenCallBack` to SqlConnection SqlConnection supports `TokenCredential` authentication by introducing a new `AccessTokenCallBack` property as a `Func>` delegate to return a federated authentication access token. Example usage: -```cs +```csharp using Microsoft.Data.SqlClient; using Azure.Identity; @@ -214,11 +287,11 @@ Console.WriteLine("ServerVersion: {0}", connection.ServerVersion); Console.WriteLine("State: {0}", connection.State); ``` -### SqlBatch API +#### SqlBatch API Example usage: -```cs +```csharp using Microsoft.Data.SqlClient; class Program @@ -265,7 +338,7 @@ class Program } ``` -## 5.2 Target Platform Support +### 5.2 Target platform support - .NET Framework 4.6.2+ (Windows x86, Windows x64) - .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -273,6 +346,8 @@ class Program Full release notes, including dependencies, are available in the GitHub Repository: [5.2 Release Notes](https://github.com/dotnet/SqlClient/tree/main/release-notes/5.2). +## Release notes for Microsoft.Data.SqlClient 5.1 + ### Breaking changes in 5.1 - Dropped support for .NET Core 3.1. [#1704](https://github.com/dotnet/SqlClient/pull/1704) [#1823](https://github.com/dotnet/SqlClient/pull/1823) @@ -284,18 +359,18 @@ Full release notes, including dependencies, are available in the GitHub Reposito - Added `ServerCertificate` setting for `Encrypt=Mandatory` or `Encrypt=Strict`. [#1822](https://github.com/dotnet/SqlClient/pull/1822) [Read more](#server-certificate) - Added Windows Arm64 support when targeting .NET Framework. [#1828](https://github.com/dotnet/SqlClient/pull/1828) -### Server Certificate +#### Server certificate -The default value of the `ServerCertificate` connection setting is an empty string. When `Encrypt` is set to `Mandatory` or `Strict`, `ServerCertificate` can be used to specify a path on the file system to a certificate file to match against the server's TLS/SSL certificate. The certificate specified must be an exact match to be valid. The accepted certificate formats are `PEM`, `DER`, and `CER`. Here's a usage example: +The default value of the `ServerCertificate` connection setting is an empty string. When `Encrypt` is set to `Mandatory` or `Strict`, `ServerCertificate` can be used to specify a path on the file system to a certificate file to match against the server's TLS/SSL certificate. The certificate specified must be an exact match to be valid. The accepted certificate formats are `PEM`, `DER`, and `CER`. Here's a usage example: - ```cs - "Data Source=...;Encrypt=Strict;ServerCertificate=C:\\certificates\\server.cer" - ``` +```csharp +"Data Source=...;Encrypt=Strict;ServerCertificate=C:\\certificates\\server.cer" +``` -## 5.1 Target platform support +### 5.1 Target platform support - .NET Framework 4.6.2+ (Windows x86, Windows x64) -- .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Windows Azure Resource Manager, Linux, macOS) +- .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Azure Resource Manager, Linux, macOS) - .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) Full release notes, including dependencies, are available in the GitHub Repository: [5.1 Release Notes](https://github.com/dotnet/SqlClient/tree/main/release-notes/5.1). @@ -305,9 +380,8 @@ Full release notes, including dependencies, are available in the GitHub Reposito ### Breaking changes in 5.0 - Dropped support for .NET Framework 4.6.1 [#1574](https://github.com/dotnet/SqlClient/pull/1574) -- Added a dependency on the [Microsoft.SqlServer.Server](https://github.com/dotnet/SqlClient/tree/main/src/Microsoft.SqlServer.Server) package. This new dependency may cause namespace conflicts if your application references that namespace and still has package references (direct or indirect) to System.Data.SqlClient from .NET Core. -- Dropped classes from the `Microsoft.Data.SqlClient.Server` namespace and replaced them with supported types from the [Microsoft.SqlServer.Server](https://github.com/dotnet/SqlClient/tree/main/src/Microsoft.SqlServer.Server) package.[#1585](https://github.com/dotnet/SqlClient/pull/1585). -The affected classes and enums are: +- Added a dependency on the [Microsoft.SqlServer.Server](https://github.com/dotnet/SqlClient/tree/main/src/Microsoft.SqlServer.Server) package. This new dependency might cause namespace conflicts if your application references that namespace and still has package references (direct or indirect) to System.Data.SqlClient from .NET Core. +- Dropped classes from the `Microsoft.Data.SqlClient.Server` namespace and replaced them with supported types from the [Microsoft.SqlServer.Server](https://github.com/dotnet/SqlClient/tree/main/src/Microsoft.SqlServer.Server) package.[#1585](https://github.com/dotnet/SqlClient/pull/1585). The affected classes and enums are: - Microsoft.Data.SqlClient.Server.IBinarySerialize -> Microsoft.SqlServer.Server.IBinarySerialize - Microsoft.Data.SqlClient.Server.InvalidUdtException -> Microsoft.SqlServer.Server.InvalidUdtException - Microsoft.Data.SqlClient.Server.SqlFacetAttribute -> Microsoft.SqlServer.Server.SqlFacetAttribute @@ -327,66 +401,66 @@ The affected classes and enums are: - Added SqlDataSourceEnumerator. [#1430](https://github.com/dotnet/SqlClient/pull/1430), [Read more](#sql-data-source-enumerator-support) - Added a new AppContext switch to suppress insecure TLS warnings. [#1457](https://github.com/dotnet/SqlClient/pull/1457), [Read more](#suppress-insecure-tls-warnings) -### TDS 8.0 enhanced security +#### TDS 8.0 enhanced security To use TDS 8.0, specify Encrypt=Strict in the connection string. Strict mode disables TrustServerCertificate (always treated as False in Strict mode). HostNameInCertificate has been added to help some Strict mode scenarios. TDS 8.0 begins and continues all server communication inside a secure, encrypted TLS connection. New Encrypt values have been added to clarify connection encryption behavior. `Encrypt=Mandatory` is equivalent to `Encrypt=True` and encrypts connections during the TDS connection negotiation. `Encrypt=Optional` is equivalent to `Encrypt=False` and only encrypts the connection if the server tells the client that encryption is required during the TDS connection negotiation. -For more information on encrypting connections to the server, see [Encryption and certificate validation](encryption-and-certificate-validation.md). +For more information on encrypting connections to the server, see [Encryption and certificate validation in Microsoft.Data.SqlClient](encryption-and-certificate-validation.md). `HostNameInCertificate` can be specified in the connection string when using aliases to connect with encryption to a server that has a server certificate with a different name or alternate subject name than the name used by the client to identify the server (DNS aliases, for example). Example usage: `HostNameInCertificate=MyDnsAliasName` -### Server SPN +#### Server SPN When connecting in an environment that has unique domain/forest topography, you might have specific requirements for Server SPNs. The ServerSPN/Server SPN and FailoverServerSPN/Failover Server SPN connection string settings can be used to override the autogenerated server SPNs used during integrated authentication in a domain environment -### Support for SQL aliases +#### Support for SQL aliases Users can configure Aliases by using the SQL Server Configuration Manager. These aliases are stored in the Windows registry and are already supported when targeting .NET Framework. This release brings support for aliases when targeting .NET or .NET Core on Windows. -### SQL Data Source Enumerator support +#### SQL data source enumerator support Provides a mechanism for enumerating all available instances of SQL Server within the local network. -```cs +```csharp using Microsoft.Data.Sql; -static void Main() - { - // Retrieve the enumerator instance and then the data. - SqlDataSourceEnumerator instance = - SqlDataSourceEnumerator.Instance; - System.Data.DataTable table = instance.GetDataSources(); - - // Display the contents of the table. - DisplayData(table); - - Console.WriteLine("Press any key to continue."); - Console.ReadKey(); - } - - private static void DisplayData(System.Data.DataTable table) - { - foreach (System.Data.DataRow row in table.Rows) - { - foreach (System.Data.DataColumn col in table.Columns) - { - Console.WriteLine("{0} = {1}", col.ColumnName, row[col]); - } - Console.WriteLine("============================"); - } - } +static void Main() + { + // Retrieve the enumerator instance and then the data. + SqlDataSourceEnumerator instance = + SqlDataSourceEnumerator.Instance; + System.Data.DataTable table = instance.GetDataSources(); + + // Display the contents of the table. + DisplayData(table); + + Console.WriteLine("Press any key to continue."); + Console.ReadKey(); + } + + private static void DisplayData(System.Data.DataTable table) + { + foreach (System.Data.DataRow row in table.Rows) + { + foreach (System.Data.DataColumn col in table.Columns) + { + Console.WriteLine("{0} = {1}", col.ColumnName, row[col]); + } + Console.WriteLine("============================"); + } + } ``` -### Suppress insecure TLS warnings +#### Suppress insecure TLS warnings A security warning is output on the console if the TLS version less than 1.2 is used to negotiate with the server. This warning could be suppressed on SQL connection while `Encrypt = false` by enabling the following AppContext switch on the application startup: -```cs +```csharp Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning ``` -## 5.0 Target platform support +### 5.0 Target platform support - .NET Framework 4.6.2+ (Windows x86, Windows x64) - .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -400,19 +474,18 @@ Full release notes, including dependencies, are available in the GitHub Reposito ### New features in 4.1 -### Introduce Attestation Protocol None +#### Introduce attestation protocol None -A new attestation protocol called `None` is allowed in the connection string. This protocol allows users to forgo enclave attestation for `VBS` enclaves. When this protocol is set, the enclave attestation URL property is optional. +A new attestation protocol called `None` is allowed in the connection string. This protocol allows users to forgo enclave attestation for `VBS` enclaves. When this protocol is set, the enclave attestation URL property is optional. Connection string example: -```cs +```csharp //Attestation protocol NONE with no URL "Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;" - ``` -### 4.1 Target Platform Support +### 4.1 Target platform support - .NET Framework 4.6.1+ (Windows x86, Windows x64) - .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -433,36 +506,36 @@ Full release notes, including dependencies, are available in the GitHub Reposito ### New features in 4.0 -### Encrypt default value set to true +#### Encrypt default value set to true -The default value of the `Encrypt` connection setting has been changed from `false` to `true`. With the growing use of cloud databases and the need to ensure those connections are secure, it's time for this backwards-compatibility-breaking change. +The default value of the `Encrypt` connection setting has been changed from `false` to `true`. With the growing use of cloud databases and the need to ensure those connections are secure, it's time for this backward-compatibility-breaking change. -### Ensure connections fail when encryption is required +#### Ensure connections fail when encryption is required In scenarios where client encryption libraries were disabled or unavailable, it was possible for unencrypted connections to be made when Encrypt was set to true or the server required encryption. -### App Context Switch for using System default protocols +#### App Context Switch for using System default protocols TLS 1.3 isn't supported by the driver; therefore, it has been removed from the supported protocols list by default. Users can switch back to forcing use of the Operating System's client protocols, by enabling the following App Context switch: - `Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols` +`Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols` -### Enable optimized parameter binding +#### Enable optimized parameter binding Microsoft.Data.SqlClient introduces a new `SqlCommand` API, `EnableOptimizedParameterBinding` to improve performance of queries with large number of parameters. This property is disabled by default. When set to `true`, parameter names aren't sent to the [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] instance when the command is executed. -```cs +```csharp public class SqlCommand { public bool EnableOptimizedParameterBinding { get; set; } } ``` -### Remove configurable retry logic safety switch +#### Remove configurable retry logic safety switch The App Context switch "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" is no longer required to use the configurable retry logic feature. The feature is now supported in production. The default behavior of the feature continues to be a non-retry policy, which client applications need to override to enable retries. -### SqlLocalDb shared instance support +#### SqlLocalDb shared instance support SqlLocalDb shared instances are now supported when using Managed SNI. @@ -471,13 +544,13 @@ SqlLocalDb shared instances are now supported when using Managed SNI. - `(localdb)\` - `(localdb)\.\` (*newly added support) -### `GetFieldValueAsync` and `GetFieldValue` support for `XmlReader`, `TextReader`, `Stream` types +#### `GetFieldValueAsync` and `GetFieldValue` support for `XmlReader`, `TextReader`, `Stream` types `XmlReader`, `TextReader`, `Stream` types are now supported when using `GetFieldValueAsync` and `GetFieldValue`. Example usage: -```cs +```csharp using (SqlConnection connection = new SqlConnection(connectionString)) { using (SqlCommand command = new SqlCommand(query, connection)) @@ -497,7 +570,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) } ``` -### 4.0 Target Platform Support +### 4.0 Target platform support - .NET Framework 4.6.1+ (Windows x86, Windows x64) - .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -511,11 +584,11 @@ Full release notes, including dependencies, are available in the GitHub Reposito - 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) - `User Id` connection property now requires `Client Id` instead of `Object Id` for **User-Assigned Managed Identity** [#1010](https://github.com/dotnet/SqlClient/pull/1010) [Read more](#azure-identity-dependency-introduction) -- `SqlDataReader` now returns a `DBNull` value instead of an empty `byte[]`. Legacy behavior can be enabled by setting `AppContext` switch **Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior** [#998](https://github.com/dotnet/SqlClient/pull/998) [Read more](#enabling-row-version-null-behavior) +- `SqlDataReader` now returns a `DBNull` value instead of an empty `byte[]`. Legacy behavior can be enabled by setting `AppContext` switch **Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior** [#998](https://github.com/dotnet/SqlClient/pull/998) [Read more](#enable-row-version-null-behavior). ### New features in 3.0 -### Configurable Retry Logic +#### Configurable retry logic 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: @@ -525,7 +598,7 @@ Once the .NET AppContext switch is enabled, a retry logic policy can be defined New public APIs are introduced in `SqlConnection` and `SqlCommand` for registering a custom `SqlRetryLogicBaseProvider` implementation: -```cs +```csharp public SqlConnection { public SqlRetryLogicBaseProvider RetryLogicProvider; @@ -535,7 +608,6 @@ public SqlCommand { public SqlRetryLogicBaseProvider RetryLogicProvider; } - ``` API Usage examples can be found here: @@ -583,61 +655,66 @@ Here's a simple example of using the new configuration sections in configuration Alternatively, applications can implement their own provider of the `SqlRetryLogicBaseProvider` base class, and register it with `SqlConnection`/`SqlCommand`. -### Event Counters +#### Event counters The following counters are now available for applications targeting .NET Core 3.1+ and .NET Standard 2.1+: -|Name|Display name|Description| -|-------------------------|-----------------|-----------------| -|**active-hard-connections**|Actual active connections currently made to servers|The number of connections currently open to database servers.| -|**hard-connects**|Actual connection rate to servers|The number of connections per second being opened to database servers.| -|**hard-disconnects**|Actual disconnection rate from servers|The number of disconnects per second being made to database servers.| -|**active-soft-connects**|Active connections retrieved from the connection pool|The number of already-open connections being consumed from the connection pool.| -|**soft-connects**|Rate of connections retrieved from the connection pool|The number of connections per second being consumed from the connection pool.| -|**soft-disconnects**|Rate of connections returned to the connection pool|The number of connections per second being returned to the connection pool.| -|**number-of-non-pooled-connections**|Number of connections not using connection pooling|The number of active connections that aren't pooled.| -|**number-of-pooled-connections**|Number of connections managed by the connection pool|The number of active connections managed the connection pooling infrastructure.| -|**number-of-active-connection-pool-groups**|Number of active unique connection strings|The number of active, unique connection pool groups. This counter is based on the number of unique connection strings found in the AppDomain.| -|**number-of-inactive-connection-pool-groups**|Number of unique connection strings waiting for pruning|The number of unique connection pool groups marked for pruning. This counter is based on the number of unique connection strings found in the AppDomain.| -|**number-of-active-connection-pools**|Number of active connection pools|The total number of connection pools.| -|**number-of-inactive-connection-pools**|Number of inactive connection pools|The number of inactive connection pools with no recent activity and waiting to be disposed.| -|**number-of-active-connections**|Number of active connections|The number of active connections currently in use.| -|**number-of-free-connections**|Number of ready connections in the connection pool|The number of open connections available for use in the connection pools.| -|**number-of-stasis-connections**|Number of connections currently waiting to be ready|The number of connections currently awaiting completion of an action and which are unavailable for use by the application.| -|**number-of-reclaimed-connections**|Number of reclaimed connections from GC|The number of connections reclaimed through garbage collection where `Close` or `Dispose` wasn't called by the application. **Note** Not explicitly closing or disposing connections hurts performance.| +| Name | Display name | Description | +| --- | --- | --- | +| **active-hard-connections** | Actual active connections currently made to servers | The number of connections currently open to database servers. | +| **hard-connects** | Actual connection rate to servers | The number of connections per second being opened to database servers. | +| **hard-disconnects** | Actual disconnection rate from servers | The number of disconnects per second being made to database servers. | +| **active-soft-connects** | Active connections retrieved from the connection pool | The number of already-open connections being consumed from the connection pool. | +| **soft-connects** | Rate of connections retrieved from the connection pool | The number of connections per second being consumed from the connection pool. | +| **soft-disconnects** | Rate of connections returned to the connection pool | The number of connections per second being returned to the connection pool. | +| **number-of-non-pooled-connections** | Number of connections not using connection pooling | The number of active connections that aren't pooled. | +| **number-of-pooled-connections** | Number of connections managed by the connection pool | The number of active connections managed the connection pooling infrastructure. | +| **number-of-active-connection-pool-groups** | Number of active unique connection strings | The number of active, unique connection pool groups. This counter is based on the number of unique connection strings found in the AppDomain. | +| **number-of-inactive-connection-pool-groups** | Number of unique connection strings waiting for pruning | The number of unique connection pool groups marked for pruning. This counter is based on the number of unique connection strings found in the AppDomain. | +| **number-of-active-connection-pools** | Number of active connection pools | The total number of connection pools. | +| **number-of-inactive-connection-pools** | Number of inactive connection pools | The number of inactive connection pools with no recent activity and waiting to be disposed. | +| **number-of-active-connections** | Number of active connections | The number of active connections currently in use. | +| **number-of-free-connections** | Number of ready connections in the connection pool | The number of open connections available for use in the connection pools. | +| **number-of-stasis-connections** | Number of connections currently waiting to be ready | The number of connections currently awaiting completion of an action and which are unavailable for use by the application. | +| **number-of-reclaimed-connections** | Number of reclaimed connections from GC | The number of connections reclaimed through garbage collection where `Close` or `Dispose` wasn't called by the application. **Note** Not explicitly closing or disposing connections hurts performance. | 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. For more information, see [Retrieve event counter values](event-counters.md#retrieve-event-counter-values). -```cmd +```console dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 collect ``` -### Azure Identity dependency introduction +#### Azure Identity dependency introduction **Microsoft.Data.SqlClient** now depends on the **Azure.Identity** library to acquire tokens for "Active Directory Managed Identity/MSI" and "Active Directory Service Principal" authentication modes. This change brings the following changes to the public surface area: -- **Breaking Change** - The "User ID" connection property now requires "Client ID" instead of "Object ID" for "User-Assigned Managed Identity". -- **Public API** +- **Breaking change** + + The "User ID" connection property now requires "Client ID" instead of "Object ID" for "User-Assigned Managed Identity". + +- **Public API** + New read-only public property: `SqlAuthenticationParameters.ConnectionTimeout` -- **Dependency** + +- **Dependency** + Azure.Identity v1.3.0 -### Event tracing improvements in SNI.dll +#### Event tracing improvements in SNI.dll `Microsoft.Data.SqlClient.SNI` (.NET Framework dependency) and `Microsoft.Data.SqlClient.SNI.runtime` (.NET Core/Standard dependency) versions have been updated to `v3.0.0-preview1.21104.2`. Event tracing in SNI.dll is no longer enabled through a client application. Subscribing a session to the **Microsoft.Data.SqlClient.EventSource** provider through tools like `xperf` or `perfview` is sufficient. For more information, see [Event tracing support in Native SNI](enable-eventsource-tracing.md#event-tracing-support-in-native-sni). -### Enabling row version null behavior +#### Enable row version null behavior `SqlDataReader` returns a `DBNull` value instead of an empty `byte[]`. To enable the legacy behavior, you must enable the following AppContext switch on application startup: **"Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior"** -### Microsoft Entra default authentication support +#### Microsoft Entra default authentication support [!INCLUDE [entra-id](../../includes/entra-id-hard-coded.md)] -This PR introduces a new SQL Authentication method, **Active Directory Default**. This authentication mode widens the possibilities of user authentication with Microsoft Entra ID, extending login solutions to the client environment, Visual Studio Code, Visual Studio, Azure CLI etc. +This PR introduces a new SQL Authentication method, **Active Directory Default**. This authentication mode widens the possibilities of user authentication with Microsoft Entra ID, extending login solutions to the client environment, Visual Studio Code, Visual Studio, Azure CLI, etc. With this authentication mode, the driver acquires a token by passing "[DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential)" from the Azure Identity library to acquire an access token. This mode attempts to use these credential types to acquire an access token in the following order: @@ -656,18 +733,18 @@ With this authentication mode, the driver acquires a token by passing "[DefaultA > InteractiveBrowserCredential is disabled in the driver implementation of "Active Directory Default", and "Active Directory Interactive" is the only option available to acquire a token using MFA/Interactive authentication. -> Further customization options are not available at the moment. +> Further customization options aren't available at the moment. -### Custom master key store provider registration enhancements +#### Custom master key store provider registration enhancements Microsoft.Data.SqlClient now offers more control of where master key store providers are accessible in an application to better support multitenant applications and their use of column encryption/decryption. The following APIs are introduced to allow registration of custom master key store providers on instances of `SqlConnection` and `SqlCommand`: -```cs +```csharp public class SqlConnection { public void RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary customProviders) } -public class SqlCommand +public class SqlCommand { public void RegisterColumnEncryptionKeyStoreProvidersOnCommand(IDictionary customProviders) } @@ -675,9 +752,9 @@ public class SqlCommand The static API on `SqlConnection`, `SqlConnection.RegisterColumnEncryptionKeyStoreProviders`, used to register custom master key store providers globally, continues to be supported. The column encryption key cache maintained globally only applies to globally registered providers. -#### Column master key store provider registration precedence +##### Column master key store provider registration precedence -The built-in column master key store providers that are available for the Windows Certificate Store, CNG Store and CSP are preregistered. No providers should be registered on the connection or command instances if one of the built-in column master key store providers is needed. +The built-in column master key store providers that are available for the Windows Certificate Store, CNG Store, and CSP are preregistered. No providers should be registered on the connection or command instances if one of the built-in column master key store providers is needed. Custom master key store providers can be registered with the driver at three different layers. The global level is as it currently is. The new per-connection and per-command level registrations are empty initially and can be set more than once. @@ -687,7 +764,7 @@ The precedences of the three registrations are as follows: - If the per-command registration is empty, the per-connection registration is checked if it isn't empty. - If the per-connection registration is empty, the global registration is checked. -Once any key store provider is found at a registration level, the driver does **NOT** fall back to the other registrations to search for a provider. If providers are registered but the proper provider isn't found at a level, an exception is thrown containing only the registered providers in the registration checked. +Once any key store provider is found at a registration level, the driver **doesn't** fall back to the other registrations to search for a provider. If providers are registered but the proper provider isn't found at a level, an exception is thrown containing only the registered providers in the registration checked. #### Column encryption key cache precedence @@ -695,7 +772,7 @@ The driver doesn't cache the column encryption keys (CEKs) for custom key store A new API has also been introduced on the `SqlColumnEncryptionKeyStoreProvider` base class to set the cache time to live: -```cs +```csharp public abstract class SqlColumnEncryptionKeyStoreProvider { // The default value of Column Encryption Key Cache Time to Live is 0. @@ -705,7 +782,7 @@ public abstract class SqlColumnEncryptionKeyStoreProvider } ``` -### IP Address preference +#### IP address preference A new connection property `IPAddressPreference` is introduced to specify the IP address family preference to the driver when establishing TCP connections. If `Transparent Network IP Resolution` (in .NET Framework) or `Multi Subnet Failover` is set to `true`, this setting has no effect. There are the three accepted values for this property: @@ -718,7 +795,7 @@ A new connection property `IPAddressPreference` is introduced to specify the IP - **UsePlatformDefault** - The driver tries IP addresses in the order received from the DNS resolution response. -### 3.0 Target Platform Support +### 3.0 Target platform support - .NET Framework 4.6.1+ (Windows x86, Windows x64) - .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -730,25 +807,23 @@ Full release notes, including dependencies, are available in the GitHub Reposito ### New features in 2.1 -### Cross-Platform support for Always Encrypted +#### Cross-platform support for Always Encrypted Microsoft.Data.SqlClient v2.1 extends support for Always Encrypted on the following platforms: -| Support Always Encrypted | Support Always Encrypted with Secure Enclave | Target Framework | Microsoft.Data.SqlClient Version | Operating System | -|:--|:--|:--|:--:|:--:| +| Support Always Encrypted | Support Always Encrypted with Secure Enclave | Target framework | Microsoft.Data.SqlClient Version | Operating system | +| --- | --- | --- | ---: | ---: | | Yes | Yes | .NET Framework 4.6+ | 1.1.0+ | Windows | | Yes | Yes | .NET Core 2.1+ | 2.1.0+1 | Windows, Linux, macOS | | Yes | No2 | .NET Standard 2.0 | 2.1.0+ | Windows, Linux, macOS | | Yes | Yes | .NET Standard 2.1+ | 2.1.0+ | Windows, Linux, macOS | -> [!NOTE] -> 1 Before Microsoft.Data.SqlClient version v2.1, Always Encrypted is only supported on Windows. -> -> 2 Always Encrypted with secure enclaves isn't supported on .NET Standard 2.0. +1 Before Microsoft.Data.SqlClient version v2.1, Always Encrypted is only supported on Windows. +2 Always Encrypted with secure enclaves isn't supported on .NET Standard 2.0. - + -### Microsoft Entra Device Code Flow authentication +#### Microsoft Entra Device Code Flow authentication Microsoft.Data.SqlClient v2.1 provides support for "Device Code Flow" authentication with MSAL.NET. Reference documentation: [OAuth2.0 Device Authorization Grant flow](/azure/active-directory/develop/v2-oauth2-device-code) @@ -767,9 +842,9 @@ public class ActiveDirectoryAuthenticationProvider } ``` - + -### Microsoft Entra managed identity authentication +#### Microsoft Entra managed identity authentication Microsoft.Data.SqlClient v2.1 introduces support for Microsoft Entra authentication using [managed identities](/azure/active-directory/managed-identities-azure-resources/overview). @@ -780,7 +855,7 @@ The following authentication mode keywords are supported: Connection string examples: -```cs +```csharp // For System Assigned Managed Identity "Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; Initial Catalog={db};" @@ -794,9 +869,9 @@ Connection string examples: "Server={serverURL}; Authentication=Active Directory Managed Identity; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};" ``` - + -### Microsoft Entra Interactive authentication enhancements +#### Microsoft Entra Interactive authentication enhancements Microsoft.Data.SqlClient v2.1 adds the following APIs to customize the **Microsoft Entra Interactive** authentication experience: @@ -817,79 +892,81 @@ public class ActiveDirectoryAuthenticationProvider } ``` -### `SqlClientAuthenticationProviders` configuration section +#### `SqlClientAuthenticationProviders` configuration section -Microsoft.Data.SqlClient v2.1 introduces a new configuration section, `SqlClientAuthenticationProviders` (a clone of the existing `SqlAuthenticationProviders`). The existing configuration section, `SqlAuthenticationProviders`, is still supported for backwards compatibility when the appropriate type is defined. +Microsoft.Data.SqlClient v2.1 introduces a new configuration section, `SqlClientAuthenticationProviders` (a clone of the existing `SqlAuthenticationProviders`). The existing configuration section, `SqlAuthenticationProviders`, is still supported for backward compatibility when the appropriate type is defined. The new section allows application config files to contain both a SqlAuthenticationProviders section for System.Data.SqlClient and a SqlClientAuthenticationProviders section for Microsoft.Data.SqlClient. - + -### Microsoft Entra authentication using an application client ID +#### Microsoft Entra authentication using an application client ID Microsoft.Data.SqlClient v2.1 introduces support for passing a user-defined application client ID to the Microsoft Authentication Library. Application Client ID is used when authenticating with Microsoft Entra ID. The following new APIs are introduced: -1. A new constructor has been introduced in ActiveDirectoryAuthenticationProvider:\ -_[Applies to all .NET Platforms (.NET Framework, .NET Core, and .NET Standard)]_ +1. A new constructor has been introduced in ActiveDirectoryAuthenticationProvider: - ```csharp - public ActiveDirectoryAuthenticationProvider(string applicationClientId) - ``` + **Applies to**: *All .NET Platforms (.NET Framework, .NET Core, and .NET Standard)* - Usage: + ```csharp + public ActiveDirectoryAuthenticationProvider(string applicationClientId) + ``` - ```csharp - string APP_CLIENT_ID = ""; - SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID); - SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider); - - using (SqlConnection sqlConnection = new SqlConnection("")) - { - sqlConnection.Open(); - } - ``` + Usage: -2. A new configuration property has been introduced under `SqlAuthenticationProviderConfigurationSection` and `SqlClientAuthenticationProviderConfigurationSection`:\ -_[Applies to .NET Framework and .NET Core]_ + ```csharp + string APP_CLIENT_ID = ""; + SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID); + SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider); - ```csharp - internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection - { - ... - [ConfigurationProperty("applicationClientId", IsRequired = false)] - public string ApplicationClientId => this["applicationClientId"] as string; - } - - // Inheritance - internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection - { ... } - ``` - - Usage: - - ```xml - - -
- - - - - - - - -
- - - - ``` - -### Data Classification v2 support + using (SqlConnection sqlConnection = new SqlConnection("")) + { + sqlConnection.Open(); + } + ``` + +1. A new configuration property has been introduced under `SqlAuthenticationProviderConfigurationSection` and `SqlClientAuthenticationProviderConfigurationSection`: + + **Applies to**: *.NET Framework and .NET Core* + + ```csharp + internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection + { + ... + [ConfigurationProperty("applicationClientId", IsRequired = false)] + public string ApplicationClientId => this["applicationClientId"] as string; + } + + // Inheritance + internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection + { ... } + ``` + + Usage: + + ```xml + + +
+ + + + + + + + +
+ + + + ``` + +#### Data Classification v2 support Microsoft.Data.SqlClient v2.1 introduces support for Data Classification's "Sensitivity Rank" information. The following new APIs are now available: @@ -915,7 +992,7 @@ public enum SensitivityRank } ``` -### Session ID for an active `SqlConnection` +#### Session ID for an active `SqlConnection` Microsoft.Data.SqlClient v2.1 introduces a new `SqlConnection` property, `ServerProcessId`, on an active connection. @@ -927,7 +1004,7 @@ public class SqlConnection } ``` -### Trace Logging support in Native SNI +#### Trace logging support in native SNI Microsoft.Data.SqlClient v2.1 extends the existing `SqlClientEventSource` implementation to enable event tracing in SNI.dll. Events must be captured using a tool like Xperf. @@ -944,23 +1021,23 @@ EventSource.SendCommand(eventSource, (EventCommand)16384, null); EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null); ``` -### "Command Timeout" connection string property +#### "Command Timeout" connection string property -Microsoft.Data.SqlClient v2.1 introduces the "Command Timeout" connection string property to override the default of 30 seconds. The time out for individual commands can be overridden using the `CommandTimeout` property on the SqlCommand. +Microsoft.Data.SqlClient v2.1 introduces the "Command Timeout" connection string property to override the default of 30 seconds. The timeout for individual commands can be overridden using the `CommandTimeout` property on the SqlCommand. Connection string examples: `"Server={serverURL}; Initial Catalog={db}; Encrypt=True; Integrated Security=true; Command Timeout=60"` -### Removal of symbols from Native SNI +#### Removal of symbols from native SNI With Microsoft.Data.SqlClient v2.1, we've removed the symbols introduced in [v2.0.0](https://www.nuget.org/packages/Microsoft.Data.SqlClient.SNI/2.0.0) from [Microsoft.Data.SqlClient.SNI.runtime](https://www.nuget.org/packages/Microsoft.Data.SqlClient.SNI.runtime) NuGet starting with [v2.1.1](https://www.nuget.org/packages/Microsoft.Data.SqlClient.SNI.runtime/2.1.1). The public symbols are now published to Microsoft Symbols Server for tools like BinSkim that require access to public symbols. -### Source-Linking of Microsoft.Data.SqlClient symbols +#### Source-linking of Microsoft.Data.SqlClient symbols Starting with Microsoft.Data.SqlClient v2.1, Microsoft.Data.SqlClient symbols are source-linked and published to the Microsoft Symbols Server for an enhanced debugging experience without the need to download source code. -### 2.1 Target Platform Support +### 2.1 Target platform support - .NET Framework 4.6+ (Windows x86, Windows x64) - .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -976,7 +1053,7 @@ Full release notes, including dependencies, are available in the GitHub Reposito - Constants in the `SqlClientMetaDataCollectionNames` class have been updated to reflect changes in SQL Server. - The driver now performs Server Certificate validation when the target SQL Server enforces TLS encryption, which is the default for Azure connections. - `SqlDataReader.GetSchemaTable()` now returns an empty `DataTable` instead `null`. -- The driver now performs decimal scale rounding to match SQL Server behavior. For backwards compatibility, the previous behavior of truncation can be enabled using an AppContext switch. +- The driver now performs decimal scale rounding to match SQL Server behavior. For backward compatibility, the previous behavior of truncation can be enabled using an AppContext switch. - For .NET Framework applications consuming **Microsoft.Data.SqlClient**, the SNI.dll files previously downloaded to the `bin\x64` and `bin\x86` folders are now named `Microsoft.Data.SqlClient.SNI.x64.dll` and `Microsoft.Data.SqlClient.SNI.x86.dll` and are downloaded to the `bin` directory. - New connection string property synonyms replace old properties when fetching connection string from `SqlConnectionStringBuilder` for consistency. [Read More](#new-connection-string-property-synonyms) @@ -998,7 +1075,7 @@ Microsoft.Data.SqlClient.EventSource For more information, see how to [Enable event tracing in SqlClient](enable-eventsource-tracing.md). -#### Enabling managed networking on Windows +#### Enable managed networking on Windows A new AppContext switch, **"Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows"**, enables the use of a managed SNI implementation on Windows for testing and debugging purposes. This switch toggles the driver's behavior to use a managed SNI in .NET Core 2.1+ and .NET Standard 2.0+ projects on Windows, eliminating all dependencies on native libraries for the Microsoft.Data.SqlClient library. @@ -1006,11 +1083,11 @@ A new AppContext switch, **"Switch.Microsoft.Data.SqlClient.UseManagedNetworking AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true); ``` -See [AppContext Switches in SqlClient](appcontext-switches.md) for a full list of available switches in the driver. +See [AppContext switches in SqlClient](appcontext-switches.md) for a full list of available switches in the driver. -#### Enabling decimal truncation behavior +#### Enable decimal truncation behavior -The driver rounds the decimal data scale, by default, as is done by SQL Server. For backwards compatibility, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"** to **true**. +The driver rounds the decimal data scale, by default, as is done by SQL Server. For backward compatibility, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"** to **true**. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true); @@ -1018,10 +1095,10 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", tr #### New connection string property synonyms -New synonyms have been added for the following existing connection string properties to avoid spacing confusion around properties with more than one word. Old property names continue to be supported for backwards compatibility. But the new connection string properties are now included when fetching the connection string from [SqlConnectionStringBuilder](/dotnet/api/microsoft.data.sqlclient.sqlconnectionstringbuilder). +New synonyms have been added for the following existing connection string properties to avoid spacing confusion around properties with more than one word. Old property names continue to be supported for backward compatibility. But the new connection string properties are now included when fetching the connection string from [SqlConnectionStringBuilder](/dotnet/api/microsoft.data.sqlclient.sqlconnectionstringbuilder). -|Existing connection string property|New Synonym| -|-----------------------------------|-----------| +| Existing connection string property | New synonym | +| --- | --- | | ApplicationIntent | Application Intent | | ConnectRetryCount | Connect Retry Count | | ConnectRetryInterval | Connect Retry Interval | @@ -1033,20 +1110,20 @@ New synonyms have been added for the following existing connection string proper #### SqlBulkCopy RowsCopied property -The RowsCopied property provides read-only access to the number of rows that have been processed in the ongoing bulk copy operation. This value may not necessarily be equal to the final number of rows added to the destination table. +The RowsCopied property provides read-only access to the number of rows that have been processed in the ongoing bulk copy operation. This value might not necessarily be equal to the final number of rows added to the destination table. #### Connection open overrides The default behavior of SqlConnection.Open() can be overridden to disable the ten-second delay and automatic connection retries triggered by transient errors. -```cs +```csharp using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;")) { sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry); } ``` -> [!NOTE] +> [!NOTE] > This override can be applied to `SqlConnection.OpenAsync()` starting with Microsoft.Data.SqlClient v6.0.0. #### Username support for Active Directory Interactive mode @@ -1055,7 +1132,7 @@ A username can be specified in the connection string when using Microsoft Entra Set a username using the **User ID** or **UID** connection string property: -```cs +```csharp "Server=; Database=; Authentication=Active Directory Interactive; User Id=;Encrypt=True;" ``` @@ -1067,7 +1144,7 @@ Order hints can be provided to improve performance for bulk copy operations on t Microsoft.Data.SqlClient (.NET Core and .NET Standard) on Windows is now dependent on **Microsoft.Data.SqlClient.SNI.runtime**, replacing the previous dependency on **runtime.native.System.Data.SqlClient.SNI**. The new dependency adds support for the ARM platform along with the already supported platforms Arm64, x64, and x86 on Windows. -### 2.0 Target Platform Support +### 2.0 Target platform support - .NET Framework 4.6+ (Windows x86, Windows x64) - .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS) @@ -1083,16 +1160,16 @@ Full release notes, including dependencies, are available in the GitHub Reposito Always Encrypted is available starting in Microsoft SQL Server 2016. Secure enclaves are available starting in Microsoft SQL Server 2019. To use the enclave feature, connection strings should include the required attestation protocol and attestation URL. For example: -```cs +```csharp "Attestation Protocol=HGS;Enclave Attestation Url=" ``` For more information, see: -- [SqlClient support for Always Encrypted](sql/sqlclient-support-always-encrypted.md) +- [Using Always Encrypted with the Microsoft .NET Data Provider for SQL Server](sql/sqlclient-support-always-encrypted.md) - [Tutorial: Develop a .NET application using Always Encrypted with secure enclaves](sql/tutorial-always-encrypted-enclaves-develop-net-apps.md) -### 1.1 Target Platform Support +### 1.1 Target platform support - .NET Framework 4.6+ (Windows x86, Windows x64) - .NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS) @@ -1120,11 +1197,11 @@ Full release notes, including dependencies, are available in the GitHub Reposito - **Authentication** - Active Directory Password authentication mode. -### Data Classification +#### Data Classification Data Classification brings a new set of APIs exposing read-only Data Sensitivity and Classification information about objects retrieved via SqlDataReader when the underlying source supports the feature and contains metadata about [data sensitivity and classification](../../relational-databases/security/sql-data-discovery-and-classification.md). See the sample application at [Data Discovery and Classification in SqlClient](https://github.com/dotnet/SqlClient/tree/master/release-notes/1.1). -```cs +```csharp public class SqlDataReader { public Microsoft.Data.SqlClient.DataClassification.SensitivityClassification SensitivityClassification @@ -1160,27 +1237,26 @@ namespace Microsoft.Data.SqlClient.DataClassification } ``` -### UTF-8 support +#### UTF-8 support UTF-8 support doesn't require any application code changes. These SqlClient changes optimize client-server communication when the server supports UTF-8 and the underlying column collation is UTF-8. See the UTF-8 section under [What's new in SQL Server 2019](../../sql-server/what-s-new-in-sql-server-2019.md). -### Always encrypted with secure enclaves +#### Always Encrypted with secure enclaves In general, existing documentation that uses System.Data.SqlClient on .NET Framework **and built-in column master key store providers** should now work with .NET Core, too. - [Develop using Always Encrypted with .NET Framework Data Provider](../../relational-databases/security/encryption/develop-using-always-encrypted-with-net-framework-data-provider.md) +- [Using Always Encrypted with the .NET Framework Data Provider for SQL Server](../../relational-databases/security/encryption/develop-using-always-encrypted-with-net-framework-data-provider.md) +- [Always Encrypted: Protect sensitive data and store encryption keys in the Windows certificate store](/azure/sql-database/sql-database-always-encrypted) - [Always Encrypted: Protect sensitive data and store encryption keys in the Windows certificate store](/azure/sql-database/sql-database-always-encrypted) +#### Authentication -### Authentication +Different authentication modes can be specified by using the **Authentication** connection string option. For more information, see the [documentation for SqlAuthenticationMethod](/dotnet/api/system.data.sqlclient.sqlauthenticationmethod?view=netframework-4.7.2&preserve-view=true). -Different authentication modes can be specified by using the _Authentication_ connection string option. For more information, see the [documentation for SqlAuthenticationMethod](/dotnet/api/system.data.sqlclient.sqlauthenticationmethod?view=netframework-4.7.2&preserve-view=true). +Custom key store providers, like the Azure Key Vault provider, need to be updated to support Microsoft.Data.SqlClient. Similarly, enclave providers also need to be updated to support Microsoft.Data.SqlClient. -> [!NOTE] -> Custom key store providers, like the Azure Key Vault provider, will need to be updated to support Microsoft.Data.SqlClient. Similarly, enclave providers will also need to be updated to support Microsoft.Data.SqlClient. -> Always Encrypted is only supported against .NET Framework and .NET Core targets. It isn't supported against .NET Standard since .NET Standard is missing certain encryption dependencies. +Always Encrypted is only supported against .NET Framework and .NET Core targets. It isn't supported against .NET Standard since .NET Standard is missing certain encryption dependencies. -### 1.0 Target Platform Support +### 1.0 Target platform support - .NET Framework 4.6+ (Windows x86, Windows x64) - .NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS) diff --git a/docs/connect/ado-net/sqlclient-driver-support-lifecycle.md b/docs/connect/ado-net/sqlclient-driver-support-lifecycle.md index daf9272c6bd..f372c9cfcfb 100644 --- a/docs/connect/ado-net/sqlclient-driver-support-lifecycle.md +++ b/docs/connect/ado-net/sqlclient-driver-support-lifecycle.md @@ -3,7 +3,7 @@ title: SqlClient driver support lifecycle description: Product support lifecycle information for the Microsoft.Data.SqlClient .NET library. author: cheenamalhotra ms.author: cmalhotra -ms.date: 06/19/2025 +ms.date: 08/19/2025 ms.service: sql ms.subservice: connectivity ms.topic: conceptual @@ -27,7 +27,8 @@ New stable (GA) releases are published every six months on a regular cadence beg | Version | Official Release Date | Latest Patch Version | Patch Release Date | Support Level | End of Support | |--|--|--|--|--|--| -| 6.0 | January 9, 2025 | 6.0.2 | April 25, 2025 | Current | - | +| 6.1 | August 14, 2025 | 6.1.1 | August 14, 2025 | LTS | August 14, 2028 | +| 6.0 | January 9, 2025 | 6.0.2 | April 25, 2025 | Current | February 14, 2026 | | 5.2 | February 28, 2024 | 5.2.3 | April 29, 2025 | Current | August 28, 2025 | | 5.1 | January 19, 2023 | 5.1.7 | April 25, 2025 | LTS | January 20, 2026 | @@ -53,6 +54,7 @@ New stable (GA) releases for `Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyV | Version | Official Release Date | Latest Patch Version | Patch Release Date | Support Level | End of Support | |--|--|--|--|--|--| +| 6.x | August 14, 2025 | 6.1.2 | August 19, 2025 | LTS | August 14, 2028 | | 5.x | February 2, 2024 | 5.1.0 | February 2, 2024 | LTS | February 3, 2027 | ### Out of support Azure Key Vault Provider releases