You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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:
On Windows, SqlClient uses a native implementation of the SNI network interface by default. To enable the use of a managed SNI implementation, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows"** to `true` at application startup:
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 is intended for testing and debugging purposes only.
42
+
43
+
> [!NOTE]
44
+
> There are some known differences when compared to the native implementation. For example, the managed implementation does not support non-domain Windows Authentication.
Transparent Network IP Resolution (TNIR) is a revision of the existing MultiSubnetFailover feature. TNIR affects the connection sequence of the driver in the case where the first resolved IP of the hostname does not respond and there are multiple IPs associated with the hostname. TNIR interacts with MultiSubnetFailover to provide the following three connection sequences:<br />
51
+
* 0: One IP is attempted, followed by all IPs in parallel
TransparentNetworkIPResolution is enabled by default. MultiSubnetFailover is disabled by default. To disable TNIR, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString"** to `true` at application startup:
For more information about setting these properties, see the documentation for [SqlConnection.ConnectionString Property](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring).
To prevent a login attempt from hanging indefinitely, you can set the AppContext switch **Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin** to `true` at application startup:
By default, ReadAsync runs synchronously and blocks the calling thread on .NET Framework. To disable this blocking behavior, you can set the AppContext switch **Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking** to `false` at application startup:
[Event Tracing for Windows (ETW)](https://docs.microsoft.com/windows/win32/etw/event-tracing-portal) is an efficient kernel-level tracing facility that lets you log driver-defined events for debugging and testing purposes. SqlClient supports capturing ETW events at different informational levels. To begin capturing event traces, client applications should listen for events from SqlClient's EventSource implementation:
22
+
23
+
```
24
+
Microsoft.Data.SqlClient.EventSource
25
+
```
26
+
27
+
The current implementation supports the following Event Keywords:
28
+
29
+
| Keyword name | Value | Description |
30
+
| ------------ | ----- | ----------- |
31
+
| ExecutionTrace | 1 | Turns on capturing Start/Stop events before and after command execution. |
| StateDump | 1024 | Turns on capturing full state dump of `SqlConnection`|
42
+
| SNITrace | 2048 | Turns on capturing flow trace events from Managed Networking implementation (only applicable in .NET Core) |
43
+
| SNIScope | 4096 | Turns on capturing scope events from Managed Networking implementation (only applicable in .NET Core) |
44
+
|||
45
+
46
+
## Example
47
+
The following example enables event tracing for a data operation on the **AdventureWorks** sample database and displays the events in the console window.
For more information, see the following resources.
53
+
54
+
|Resource|Description|
55
+
|--------------|-----------------|
56
+
|[EventSource Class](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventsource)|Provides the ability to create ETW events.|
57
+
|[EventListener Class](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlistener)|Provides methods for enabling and disabling events from event sources.|
description: "Page that contains useful information regarding the driver."
4
-
ms.date: "09/30/2019"
4
+
ms.date: "06/15/2019"
5
5
dev_langs:
6
6
- "csharp"
7
7
- "vb"
@@ -24,7 +24,7 @@ For more information about the Microsoft SqlClient Data Provider for SQL Server
24
24
25
25
|Resource|Description|
26
26
|--------------|-----------------|
27
-
|[.Net CoreFX GitHub Repository](https://github.com/dotnet/corefx)|This repo contains the library implementation for .NET Core.|
27
+
|[.NET Runtime GitHub Repository](https://github.com/dotnet/runtime)|This repo contains the library implementation for .NET Core.|
28
28
|[Microsoft SqlClient Data Provider for SQL Server GitHub Repository](https://github.com/dotnet/SqlClient)|This repo contains the source code for the SqlClient driver.|
29
29
|[.NET API Browser](https://docs.microsoft.com/dotnet/api/)|This site contains .NET API information for the driver.|
Release notes are also available in the GitHub Repository: [2.0 Release Notes](https://github.com/dotnet/SqlClient/tree/master/release-notes/2.0).
21
+
22
+
### Breaking changes
23
+
24
+
- The access modifier for the enclave provider interface `SqlColumnEncryptionEnclaveProvider` has been changed from `public` to `internal`.
25
+
26
+
- Constants in the `SqlClientMetaDataCollectionNames` class have been updated to reflect changes in SQL Server.
27
+
28
+
- The driver will now perform Server Certificate validation when the target SQL Server enforces TLS encryption, which is the default for Azure connections.
29
+
30
+
-`SqlDataReader.GetSchemaTable()` now returns an empty `DataTable` instead `null`.
31
+
32
+
- 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.
33
+
34
+
- 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 will be downloaded to the `bin` directory.
35
+
36
+
### New features
37
+
38
+
#### DNS failure resiliency
39
+
40
+
The driver will now cache IP addresses from every successful connection to a SQL Server endpoint that supports the feature. If a DNS resolution failure occurs during a connection attempt, the driver will try establishing a connection using a cached IP address for that server, if any exists.
41
+
42
+
#### EventSource tracing
43
+
44
+
This release introduces support for capturing event trace logs for debugging applications. To capture these events, client applications must listen for events from SqlClient's EventSource implementation:
45
+
46
+
```
47
+
Microsoft.Data.SqlClient.EventSource
48
+
```
49
+
50
+
For more information, see how to [Enable event tracing in SqlClient](enable-eventsource-tracing.md).
51
+
52
+
#### Enabling managed networking on Windows
53
+
54
+
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 will toggle 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.
See [AppContext Switches in SqlClient](appcontext-switches.md) for a full list of available switches in the driver.
61
+
62
+
#### Enabling decimal truncation behavior
63
+
64
+
The decimal data scale will be rounded by the driver by default as is done by SQL Server. For backwards compatibility, you can set the AppContext switch **"Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"** to **true**.
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 will continue to be supported for backwards compatibility.
73
+
74
+
|Existing connection string property|New Synonym|
75
+
|-----------------------------------|-----------|
76
+
| ApplicationIntent | Application Intent |
77
+
| ConnectRetryCount | Connect Retry Count |
78
+
| ConnectRetryInterval | Connect Retry Interval |
79
+
| PoolBlockingPeriod | Pool Blocking Period |
80
+
| MultipleActiveResultSets | Multiple Active Result Sets |
| TransparentNetworkIPResolution | Transparent Network IP Resolution |
83
+
| TrustServerCertificate | Trust Server Certificate |
84
+
85
+
#### SqlBulkCopy RowsCopied property
86
+
87
+
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.
88
+
89
+
#### Connection open overrides
90
+
91
+
The default behavior of SqlConnection.Open() can be overridden to disable the ten-second delay and automatic connection retries triggered by transient errors.
> Note that this override can only be applied to SqlConnection.Open() and not SqlConnection.OpenAsync().
100
+
101
+
#### Username support for Active Directory Interactive mode
102
+
103
+
A username can be specified in the connection string when using Azure Active Directory Interactive authentication mode for both .NET Framework and .NET Core
104
+
105
+
Set a username using the **User ID** or **UID** connection string property:
106
+
107
+
```
108
+
"Server=<server name>; Database=<db name>; Authentication=Active Directory Interactive; User Id=<username>;"
109
+
```
110
+
111
+
#### Order hints for SqlBulkCopy
112
+
113
+
Order hints can be provided to improve performance for bulk copy operations on tables with clustered indexes. For more information, see the [bulk copy operations](sql/bulk-copy-order-hints.md) section.
114
+
115
+
#### SNI dependency changes
116
+
117
+
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.
17
118
18
119
## Release notes for Microsoft.Data.SqlClient 1.1.0
19
120
20
121
Release notes are also available in the GitHub Repository: [1.1 Release Notes](https://github.com/dotnet/SqlClient/tree/master/release-notes/1.1).
21
122
22
-
### New Features
123
+
### New features
23
124
24
125
#### Always Encrypted with secure enclaves
25
126
26
-
Always Encrypted is available starting in Microsoft SQL Server 2016. Secure enclaves are available starting in Microsoft SQL Server 2019. In order to use the enclave feature, connection strings should include the required attestation protocol and attestation URL. Examples:
127
+
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:
-[SqlClient support for Always Encrypted](sql/sqlclient-support-always-encrypted.md)
35
136
-[Tutorial: Develop a .NET application using Always Encrypted with secure enclaves](sql/tutorial-always-encrypted-enclaves-develop-net-apps.md)
@@ -57,7 +158,7 @@ Release notes are also available on the GitHub Repository: [1.0 Release Notes](h
57
158
58
159
### Data Classification
59
160
60
-
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).
161
+
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).
UTF-8 support does not require any application code changes. These SqlClient changes simply optimize the communication between the client and server when the server supports UTF-8 and the underlying column collation is UTF-8. See the UTF-8 section under [What'snewinSQLServer 2019 preview](../../sql-server/what-s-new-in-sql-server-ver15.md).
201
+
UTF-8 support does not 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'snewinSQLServer 2019 preview](../../sql-server/what-s-new-in-sql-server-ver15.md).
0 commit comments