Skip to content

Commit 7782382

Browse files
author
Jill Grant
authored
Merge pull request #29930 from arellegue/GAReleaseV52
Updates for Release 5.2
2 parents 43404a8 + c87becb commit 7782382

6 files changed

Lines changed: 164 additions & 10 deletions

‎docs/connect/ado-net/appcontext-switches.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The AppContext class allows SqlClient to provide new functionality while continu
2121

2222
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
2323

24-
Starting with Microsoft.Data.SqlClient 4.0, TLS 1.3 isn't supported by the driver and 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 setting the AppContext switch **"Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols"** to true:
24+
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:
2525

2626
```csharp
2727
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols", true);
@@ -33,7 +33,7 @@ Starting with version 5.0, TLS 1.3 is supported in TDS 8 connections without hav
3333

3434
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
3535

36-
Starting with Microsoft.Data.SqlClient 2.0, decimal data will be rounded by default, as is done by SQL Server. To enable the previous behavior of truncation, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"** to `true` at application startup:
36+
Starting with Microsoft.Data.SqlClient 2.0, decimal data is rounded by default, as is done by SQL Server. To enable the previous behavior of truncation, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"** to `true` at application startup:
3737

3838
```csharp
3939
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);
@@ -51,7 +51,7 @@ On Windows, SqlClient uses a native implementation of the SNI network interface
5151
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);
5252
```
5353

54-
This switch will toggle the driver's behavior to use a managed networking implementation 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. It's intended for testing and debugging purposes only.
54+
This switch toggles the driver's behavior to use a managed networking implementation 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. It is for testing and debugging purposes only.
5555

5656
> [!NOTE]
5757
> There are some known differences when compared to the native implementation. For example, the managed implementation does not support non-domain Windows Authentication.
@@ -83,7 +83,7 @@ For more information about setting these properties, see the documentation for [
8383

8484
## Enable a minimum timeout during login
8585

86-
[!INCLUDE [appliesto-netfx-xxxx-xxxx-md](../../includes/appliesto-netfx-xxxx-xxxx-md.md)]
86+
[!INCLUDE [appliesto-netfx-netcore-netst-md](../../includes/appliesto-netfx-netcore-netst-md.md)]
8787

8888
To prevent a login attempt from waiting indefinitely, you can set the AppContext switch **Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin** to `true` at application startup:
8989

‎docs/connect/ado-net/download-microsoft-sqlclient-data-provider.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Download Microsoft SqlClient Data Provider for SQL Server
33
description: Download page for ADO.NET and Microsoft SqlClient Data Provider for SQL Server.
44
author: David-Engel
55
ms.author: v-davidengel
6-
ms.date: 01/11/2023
6+
ms.date: 02/28/2024
77
ms.service: sql
88
ms.subservice: connectivity
99
ms.topic: conceptual
@@ -20,6 +20,7 @@ If you need to download the Microsoft.Data.SqlClient package for offline use, it
2020

2121
## Download stable versions of Microsoft SqlClient Data Provider for SQL Server
2222

23+
* [5.2.0](https://www.nuget.org/packages/Microsoft.Data.SqlClient/5.2.0)
2324
* [5.1.0](https://www.nuget.org/packages/Microsoft.Data.SqlClient/5.1.0)
2425
* [5.0.0](https://www.nuget.org/packages/Microsoft.Data.SqlClient/5.0.0)
2526
* [4.1.0](https://www.nuget.org/packages/Microsoft.Data.SqlClient/4.1.0)

‎docs/connect/ado-net/introduction-microsoft-data-sqlclient-namespace.md‎

Lines changed: 135 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Introduction to Microsoft.Data.SqlClient namespace
33
description: Learn about the Microsoft.Data.SqlClient namespace and how it's the preferred way to connect to SQL for .NET applications.
44
author: David-Engel
55
ms.author: v-davidengel
6-
ms.date: 04/19/2023
6+
ms.date: 02/28/2024
77
ms.service: sql
88
ms.subservice: connectivity
99
ms.topic: conceptual
@@ -20,6 +20,140 @@ There are a few differences in less-used APIs compared to System.Data.SqlClient
2020

2121
The Microsoft.Data.SqlClient API details can be found in the [.NET API Browser](/dotnet/api/microsoft.data.sqlclient).
2222

23+
## Release notes for Microsoft.Data.SqlClient 5.2
24+
25+
### New features in 5.2
26+
27+
- Added support of `SqlDiagnosticListener` on **.NET Standard**. [#1931](https://github.com/dotnet/SqlClient/pull/1931)
28+
- Added new property `RowsCopied64` to `SqlBulkCopy`. [#2004](https://github.com/dotnet/SqlClient/pull/2004) [Read more](#added-new-property-rowscopied64-to-sqlbulkcopy)
29+
- Added a new `AccessTokenCallBack` API to `SqlConnection`. [#1260](https://github.com/dotnet/SqlClient/pull/1260) [Read more](#added-new-property-accesstokencallback-to-sqlconnection)
30+
- Added support for the `SuperSocketNetLib` registry option for Encrypt on .NET on Windows. [#2047](https://github.com/dotnet/SqlClient/pull/2047)
31+
- Added `SqlBatch` support on .NET 6+ [#1825](https://github.com/dotnet/SqlClient/pull/1825), [#2223](https://github.com/dotnet/SqlClient/pull/2223) [Read more](#sqlbatch-api)
32+
- Added Workload Identity authentication support [#2159](https://github.com/dotnet/SqlClient/pull/2159), [#2264](https://github.com/dotnet/SqlClient/pull/2264)
33+
- Added Localization support on .NET [#2210](https://github.com/dotnet/SqlClient/pull/2110)
34+
- Added support for Georgian collation [#2194](https://github.com/dotnet/SqlClient/pull/2194)
35+
- Added support for Big Endian systems [#2170](https://github.com/dotnet/SqlClient/pull/2170)
36+
- Added .NET 8 support [#2230](https://github.com/dotnet/SqlClient/pull/2230)
37+
- 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)
38+
- Added the ability to generate debugging symbols in a separate package file [#2137](https://github.com/dotnet/SqlClient/pull/2137)
39+
40+
### Added new property `RowsCopied64` to SqlBulkCopy
41+
42+
SqlBulkCopy has a new property `RowsCopied64` which supports `long` value types.
43+
44+
**Note that the existing `SqlBulkCopy.RowsCopied` behavior is unchanged. When the value exceeds `int.MaxValue`, `RowsCopied` can return a negative number.**
45+
46+
Example usage:
47+
48+
```C#
49+
using (SqlConnection srcConn = new SqlConnection(srcConstr))
50+
using (SqlCommand srcCmd = new SqlCommand("select top 5 * from employees", srcConn))
51+
{
52+
srcConn.Open();
53+
using (DbDataReader reader = srcCmd.ExecuteReader())
54+
{
55+
using (SqlBulkCopy bulkcopy = new SqlBulkCopy(dstConn))
56+
{
57+
bulkcopy.DestinationTableName = dstTable;
58+
SqlBulkCopyColumnMappingCollection ColumnMappings = bulkcopy.ColumnMappings;
59+
60+
ColumnMappings.Add("EmployeeID", "col1");
61+
ColumnMappings.Add("LastName", "col2");
62+
ColumnMappings.Add("FirstName", "col3");
63+
64+
bulkcopy.WriteToServer(reader);
65+
long rowsCopied = bulkcopy.RowsCopied64;
66+
}
67+
}
68+
}
69+
```
70+
71+
### Added new property `AccessTokenCallBack` to SqlConnection
72+
73+
SqlConnection supports `TokenCredential` authentication by introducing a new `AccessTokenCallBack` property as a `Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>>` delegate to return a federated authentication access token.
74+
75+
Example usage:
76+
77+
```C#
78+
using Microsoft.Data.SqlClient;
79+
using Azure.Identity;
80+
81+
const string defaultScopeSuffix = "/.default";
82+
string connectionString = GetConnectionString();
83+
using SqlConnection connection = new SqlConnection(connectionString);
84+
85+
connection.AccessTokenCallback = async (authParams, cancellationToken) =>
86+
{
87+
var cred = new DefaultAzureCredential();
88+
string scope = authParams.Resource.EndsWith(defaultScopeSuffix) ? authParams.Resource : authParams.Resource + defaultScopeSuffix;
89+
AccessToken token = await cred.GetTokenAsync(new TokenRequestContext(new[] { scope }), cancellationToken);
90+
return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
91+
}
92+
93+
connection.Open();
94+
Console.WriteLine("ServerVersion: {0}", connection.ServerVersion);
95+
Console.WriteLine("State: {0}", connection.State);
96+
```
97+
98+
### SqlBatch API
99+
100+
Example usage:
101+
102+
```csharp
103+
using Microsoft.Data.SqlClient;
104+
105+
class Program
106+
{
107+
static void Main()
108+
{
109+
string str = "Data Source=(local);Initial Catalog=Northwind;"
110+
+ "Integrated Security=SSPI;Encrypt=False";
111+
RunBatch(str);
112+
}
113+
114+
static void RunBatch(string connString)
115+
{
116+
using var connection = new SqlConnection(connString);
117+
connection.Open();
118+
119+
var batch = new SqlBatch(connection);
120+
121+
const int count = 10;
122+
const string parameterName = "parameter";
123+
for (int i = 0; i < count; i++)
124+
{
125+
var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
126+
batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
127+
batch.BatchCommands.Add(batchCommand);
128+
}
129+
130+
// Optionally Prepare
131+
batch.Prepare();
132+
133+
var results = new List<int>(count);
134+
using (SqlDataReader reader = batch.ExecuteReader())
135+
{
136+
do
137+
{
138+
while (reader.Read())
139+
{
140+
results.Add(reader.GetFieldValue<int>(0));
141+
}
142+
} while (reader.NextResult());
143+
}
144+
Console.WriteLine(string.Join(", ", results));
145+
}
146+
}
147+
```
148+
149+
## 5.2 Target Platform Support
150+
151+
- .NET Framework 4.6.2+ (Windows x86, Windows x64)
152+
- .NET 6.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)
153+
- .NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)
154+
155+
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).
156+
23157
### Breaking changes in 5.1
24158

25159
- Dropped support for .NET Core 3.1. [#1704](https://github.com/dotnet/SqlClient/pull/1704) [#1823](https://github.com/dotnet/SqlClient/pull/1823)

‎docs/connect/ado-net/sql/azure-active-directory-authentication.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Describes how to use supported Microsoft Entra authentication modes
44
author: David-Engel
55
ms.author: v-davidengel
66
ms.reviewer: v-davidengel
7-
ms.date: 01/30/2024
7+
ms.date: 02/28/2024
88
ms.service: sql
99
ms.subservice: connectivity
1010
ms.topic: conceptual
@@ -51,6 +51,7 @@ When the application is connecting to Azure SQL data sources by using Microsoft
5151
| Active Directory Device Code Flow | Authenticate with a Microsoft Entra identity by using Device Code Flow mode | 2.1.0+ |
5252
| Active Directory Managed Identity, <br>Active Directory MSI | Authenticate using a Microsoft Entra system-assigned or user-assigned managed identity | 2.1.0+ |
5353
| Active Directory Default | Authenticate with a Microsoft Entra identity by using password-less and non-interactive mechanisms including managed identities, Visual Studio Code, Visual Studio, Azure CLI, etc. | 3.0.0+ |
54+
| Active Directory Workload Identity| Authenticate with a Microsoft Entra identity by using a federated User Assigned Managed Identity to connect to SQL Database from Azure client environments that have enabled support for Workload Identity. | 5.2.0+ |
5455

5556
<sup>1</sup> Before **Microsoft.Data.SqlClient** 2.0.0, `Active Directory Integrated`, and `Active Directory Interactive` authentication modes are supported only on .NET Framework.
5657

@@ -271,6 +272,22 @@ using (SqlConnection conn = new SqlConnection(ConnectionString)) {
271272
}
272273
```
273274

275+
## Using workload identity authentication
276+
277+
Available starting in version 5.2, like with managed identities, [workload identity](/azure/aks/workload-identity-overview) authentication mode uses the value of the User Id parameter in the connection string for its Client Id if specified. But unlike managed identity, WorkloadIdentityCredentialOptions defaults its value from environment variables: AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_FEDERATED_TOKEN_FILE. However, only the Client Id may be overridden by the connection string.
278+
279+
The following example demonstrates `Active Directory Workload Identity` authentication with a user-assigned managed identity with **Microsoft.Data.SqlClient v5.2 onwards**.
280+
281+
```cs
282+
// Use your own values for Server, Database, and User Id.
283+
// With Microsoft.Data.SqlClient v5.2+
284+
string ConnectionString = @"Server=demo.database.windows.net; Authentication=Active Directory Workload Identity; Encrypt=True; User Id=ClientIdOfManagedIdentity; Database=testdb";
285+
286+
using (SqlConnection conn = new SqlConnection(ConnectionString)) {
287+
conn.Open();
288+
}
289+
```
290+
274291
## Customizing Microsoft Entra authentication
275292

276293
Besides using the Microsoft Entra authentication built into the driver, **Microsoft.Data.SqlClient** 2.1.0 and later provide applications the option to customize Microsoft Entra authentication. The customization is based on the `ActiveDirectoryAuthenticationProvider` class, which is derived from the [`SqlAuthenticationProvider`](/dotnet/api/system.data.sqlclient.sqlauthenticationprovider) abstract class.

‎docs/connect/ado-net/sqlclient-driver-support-lifecycle.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: SqlClient driver support lifecycle
33
description: Product support lifecycle information for the Microsoft.Data.SqlClient .NET library.
44
author: David-Engel
55
ms.author: v-davidengel
6-
ms.date: 10/31/2023
6+
ms.date: 02/28/2024
77
ms.service: sql
88
ms.subservice: connectivity
99
ms.topic: conceptual
@@ -27,6 +27,7 @@ New stable (GA) releases are published every six months on a regular cadence beg
2727

2828
| Version | Official Release Date | Latest Patch Version | Patch Release Date | Support Level | End of Support |
2929
|--|--|--|--|--|--|
30+
| 5.2 | February 28, 2024 | - | - | Current | - |
3031
| 5.1 | January 19, 2023 | 5.1.5 | January 29, 2024 | LTS | January 20, 2026 |
3132
| 4.0 | November 18, 2021 | 4.0.5 | January 9, 2024 | LTS | November 19, 2024 |
3233
| 3.1 | March 30, 2022 | 3.1.5 | January 9, 2024 | LTS | March 30, 2025 |
@@ -72,6 +73,7 @@ Current releases are supported for three months after a subsequent Current or LT
7273

7374
|Database version&nbsp;&#8594;<br />&#8595; Driver Version|Azure SQL Database|Azure Synapse Analytics|Azure SQL Managed Instance|SQL Server 2022|SQL Server 2019|SQL Server 2017|SQL Server 2016|SQL Server 2014|SQL Server 2012|
7475
|---|---|---|---|---|---|---|---|---|---|
76+
|5.2|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes||
7577
|5.1|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes|
7678
|5.0|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes|
7779
|4.1|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes|Yes|

‎docs/includes/appliesto-netfx-netcore-netst-md.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
22
author: rwestMSFT
33
ms.author: randolphwest
4-
ms.date: 01/29/2024
4+
ms.date: 02/28/2024
55
ms.service: sql
66
ms.topic: include
77
---
88

9-
[!INCLUDE [applies-md](applies-md.md)] :::image type="icon" source="media/yes-icon.svg" border="false"::: .NET Framework :::image type="icon" source="media/yes-icon.svg" border="false"::: .NET Core :::image type="icon" source="media/yes-icon.svg" border="false"::: .NET Standard
9+
[!INCLUDE [applies-md](applies-md.md)] :::image type="icon" source="media/yes-icon.svg" border="false"::: .NET Framework :::image type="icon" source="media/yes-icon.svg" border="false"::: .NET :::image type="icon" source="media/yes-icon.svg" border="false"::: .NET Standard

0 commit comments

Comments
 (0)