Skip to content

Latest commit

 

History

History
355 lines (274 loc) · 19.7 KB

2.1.0.md

File metadata and controls

355 lines (274 loc) · 19.7 KB
Raw

Release Notes

Microsoft.Data.SqlClient 2.1.0 released 19 November 2020

This update brings the below changes over the previous release:

Added

  • Microsoft.Data.SqlClient symbols are now source-linked #789 [Read more]
  • Added an API to clear cached access tokens from the token provider #800
  • Added SqlFacetAttribute implementation #757

Fixed

  • Fixed InvalidOperationException and NotSupportedException errors due to WriteAsync collisions #796
  • Fixed incorrect Settings.Async flag in ExecuteXmlReaderAsync #782
  • Fixed a regression in Windows Integrated authentication when using managed networking #777
  • Fixed Bulk Copy Async deadlock issues with custom IDataReader when using SqlDataReader internally #779
  • Fixed a serialization issue with SqlException in .NET Core #780

Changes

  • Updated versions of Microsoft.IdentityModel package dependencies #794

Summary of changes in 2.1

All changes in Microsoft.Data.SqlClient v2.1 since v2.0:

Added

  • Added support for Always Encrypted on all supported platforms for .NET Standard 2.0 #756 [Read more]
  • Added support for Always Encrypted with secure enclaves on Unix for .NET Core 2.1+ and on all supported platforms for .NET Standard 2.1+ #676 [Read more]
  • Added support for Azure Active Directory Device Code Flow authentication #597 [Read more]
  • Added support for Azure Active Directory Managed Identity authentication #730 [Read more]
  • Added APIs to enable customizing the UI for "Active Directory Interactive" authentication #597 Read more
  • Added support to provide a user-defined application client ID when using Active Directory authentication #740 [Read more]
  • Added Sensitivity Rank support in Sensitivity Classification information #626 [Read more]
  • Added support to obtain ServerProcessId() (SPID) information on an active SqlConnection instance #660 [Read more]
  • Added support for a new Configuration Section, SqlClientAuthenticationProviders (duplicate of existing SqlAuthenticationProviders), to allow co-existence of configurations for both drivers, "System.Data.SqlClient" and "Microsoft.Data.SqlClient" #702 [Read more]
  • Added TraceLogging in Native SNI to extend SqlClientEventSource support #650 [Read more]
  • Updated Microsoft.Data.SqlClient.SNI (.NET Framework dependency) and Microsoft.Data.SqlClient.SNI.runtime (.NET Core/Standard dependency) version to v2.1.0 with trace logging implementation #705
  • Added the "Command Timeout" connection string property to set a default timeout for all commands executed with the connection #722 [Read more]
  • Microsoft.Data.SqlClient symbols are now source-linked #789 [Read more]
  • Added an API to clear cached access tokens from the token provider #800
  • Added SqlFacetAttribute implementation #757

Fixed

  • Fixed Enclave session cache issue with Azure Database #686
  • Fixed pooled connection re-use on access token expiry issue when using Active Directory authentication modes #635
  • Fixed transient fault handling for Pooled connections #637
  • Fixed SPN generation issue when no port is provided #629
  • Fixed missing null checks for SqlErrors in SqlException for .NET Framework implementation #698
  • Fixed unobserved exception issue when a timeout occurs before a faulted task completes with an exception #688 #773
  • Fixed an issue where the driver continues to prompt for credentials when using Azure Active Directory authentication and cached credentials should have been used #770
  • Fixed InvalidOperationException and NotSupportedException errors due to WriteAsync collisions #796
  • Fixed incorrect Settings.Async flag in ExecuteXmlReaderAsync #782
  • Fixed a regression in Windows Integrated authentication when using managed networking #777
  • Fixed Bulk Copy Async deadlock issues with custom IDataReader when using SqlDataReader internally #779
  • Fixed a serialization issue with SqlException in .NET Core #780

Changes

  • Performance improvements by fixing unnecessary allocations in EventSource implementation #684
  • Reverted changes to return empty DataTable from GetSchemaTable to return null as before. #696
  • Removed multiple CacheConnectionStringProperties calls when setting ConnectionString properties #683
  • Code improvements by checking for an inexact match only when no exact match is found for an embedded resource #668
  • Changed _SqlMetaData to lazy initialize hidden column map #521
  • Renamed internal string resource file and helpers for .NET Core implementation #671
  • Performance improvements by reworking ExecuteReaderAsync to minimize allocations #528
  • Performance improvements by moving DataReader caches to internal connection #499
  • Moved common files to shared folder between .NET Framework and .NET Core implementation #618 #625
  • Updated Microsoft.Data.SqlClient.SNI (.NET Framework dependency) and Microsoft.Data.SqlClient.SNI.runtime (.NET Core/Standard dependency) version to v2.1.1 and removed symbols from Microsoft.Data.SqlClient.SNI.runtime, which are now published to Microsoft Symbols Server #764 [Read more]
  • Updated Microsoft.Identity.Client dependency version to v4.21.1 #765
  • Performance improvements when establishing an encrypted channel by removing sync over async method calls #541
  • Performance improvements by replacing heap-allocated arrays with Spans #667
  • Moved common files to shared folder between .NET Framework and .NET Core implementation #734 #753
  • Updated versions of Microsoft.IdentityModel package dependencies #794

Cross-Platform support for Always Encrypted v1

Microsoft.Data.SqlClient v2.1 extends support for Always Encrypted on the following platforms:

Target Framework Platform New Feature support
.NET Framework v4.6+ Windows No changes
.NET Core 2.1+ All Operating Systems Yes, Support on Linux/MacOS
.NET Standard 2.0+ All Operating Systems Yes, Support on All Operating Systems

Cross-Platform support for Always Encrypted with Secure Enclaves

Microsoft.Data.SqlClient v2.1 extends support for Always Encrypted (including with secure enclaves) on the following platforms:

Target Framework Platform New Feature support
.NET Framework v4.6+ Windows No changes
.NET Core 2.1+ All Operating Systems Yes, Support on Linux/MacOS
.NET Standard 2.1+ All Operating Systems Yes, Support on All Operating Systems

Always Encrypted with secure enclaves is not supported on .NET Standard 2.0.

Azure Active Directory 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

Connection string example:

Server=<server>.database.windows.net; Authentication=Active Directory Device Code Flow; Database=Northwind;

The following API enables customization of the Device Code Flow callback mechanism:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetDeviceCodeFlowCallback(Func<DeviceCodeResult, Task> deviceCodeFlowCallbackMethod)
}

Azure Active Directory Managed Identity authentication

Microsoft.Data.SqlClient v2.1 introduces support for Azure Active Directory authentication using managed identities.

The following authentication mode keywords are supported:

  • Active Directory Managed Identity
  • Active Directory MSI (for cross MS SQL drivers compatibility)

Connection string examples:

// For System Assigned Managed Identity
"Server:{serverURL}; Authentication=Active Directory MSI; Initial Catalog={db};"

// For System Assigned Managed Identity
"Server:{serverURL}; Authentication=Active Directory Managed Identity; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server:{serverURL}; Authentication=Active Directory MSI; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server:{serverURL}; Authentication=Active Directory Managed Identity; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

Azure Active Directory Interactive authentication enhancements

Microsoft.Data.SqlClient v2.1 provides the following new APIs to enable customizations for the "Active Directory Interactive" authentication experience:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken, Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void ClearUserTokenCache();
}

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.

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.

Azure Active Directory 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, which will be used when authenticating with Azure Active Directory.

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)]
public ActiveDirectoryAuthenticationProvider(string applicationClientId)

Usage:

string APP_CLIENT_ID = "<GUID>";
SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID);
SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider);

using (SqlConnection sqlConnection = new SqlConnection("<connection_string>")
{
		sqlConnection.Open();
}
  1. A new configuration property has been introduced under SqlAuthenticationProviderConfigurationSection and SqlClientAuthenticationProviderConfigurationSection:
    [Applies to .NET Framework and .NET Core]
internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
{
		...
		[ConfigurationProperty("applicationClientId", IsRequired = false)]
		public string ApplicationClientId => this["applicationClientId"] as string;
}

// Inheritance
internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
{ ... }

Usage:

<configuration>
	<configSections>
		<section name="SqlClientAuthenticationProviders"
						 type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
	</configSections>
	<SqlClientAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

<!--or-->

<configuration>
	<configSections>
		<section name="SqlAuthenticationProviders"
						 type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
	</configSections>
	<SqlAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

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:

public class SensitivityClassification
{
  public SensitivityRank SensitivityRank;
}

public class SensitivityProperty
{
  public SensitivityRank SensitivityRank;
}

public enum SensitivityRank
{
    NOT_DEFINED = -1,
    NONE = 0,
    LOW = 10,
    MEDIUM = 20,
    HIGH = 30,
    CRITICAL = 40
}

Server Process Id for an active SqlConnection

Microsoft.Data.SqlClient v2.1 introduces a new SqlConnection property, ServerProcessId, on an active connection.

public class SqlConnection
{
  // Returns the server process Id (SPID) of the active connection.
  public int ServerProcessId;
}

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.

Tracing can be enabled by sending a command to SqlClientEventSource as illustrated below:

// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);

// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);

// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);

"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 timeout for individual commands can be overridden using the CommandTimeout property on the SqlCommand.

Connection string examples:

"Server:{serverURL}; Initial Catalog={db}; Integrated Security=true; Command Timeout=60"

Removal of symbols from Native SNI

With Microsoft.Data.SqlClient v2.1, we've removed the symbols introduced in v2.0.0 from Microsoft.Data.SqlClient.SNI.runtime NuGet starting with v2.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

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.

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)
  • .NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)

Dependencies

.NET Framework

  • Microsoft.Data.SqlClient.SNI 2.1.1
  • Microsoft.Identity.Client 4.21.1
  • Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0
  • Microsoft.IdentityModel.JsonWebTokens 6.8.0

.NET Core 2.1

  • Microsoft.Data.SqlClient.SNI.runtime 2.1.1
  • Microsoft.Win32.Registry 4.7.0
  • System.Security.Principal.Windows 4.7.0
  • System.Text.Encoding.CodePages 4.7.0
  • System.Diagnostics.DiagnosticSource 4.7.0
  • System.Configuration.ConfigurationManager 4.7.0
  • System.Runtime.Caching 4.7.0
  • Microsoft.Identity.Client 4.21.1
  • Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0
  • Microsoft.IdentityModel.JsonWebTokens 6.8.0

.NET Core 3.1

  • Microsoft.Data.SqlClient.SNI.runtime 2.1.1
  • Microsoft.Win32.Registry 4.7.0
  • System.Security.Principal.Windows 4.7.0
  • System.Text.Encoding.CodePages 4.7.0
  • System.Diagnostics.DiagnosticSource 4.7.0
  • System.Configuration.ConfigurationManager 4.7.0
  • System.Runtime.Caching 4.7.0
  • Microsoft.Identity.Client 4.21.1
  • Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0
  • Microsoft.IdentityModel.JsonWebTokens 6.8.0

.NET Standard 2.0

  • Microsoft.Data.SqlClient.SNI.runtime 2.1.1
  • Microsoft.Win32.Registry 4.7.0
  • System.Buffers 4.5.1
  • System.Memory 4.5.4
  • System.Security.Principal.Windows 4.7.0
  • System.Text.Encoding.CodePages 4.7.0
  • Microsoft.Identity.Client 4.21.1
  • Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0
  • Microsoft.IdentityModel.JsonWebTokens 6.8.0

.NET Standard 2.1

  • Microsoft.Data.SqlClient.SNI.runtime 2.1.1
  • Microsoft.Win32.Registry 4.7.0
  • System.Buffers 4.5.1
  • System.Memory 4.5.4
  • System.Security.Principal.Windows 4.7.0
  • System.Text.Encoding.CodePages 4.7.0
  • Microsoft.Identity.Client 4.21.1
  • Microsoft.IdentityModel.Protocols.OpenIdConnect 6.8.0
  • Microsoft.IdentityModel.JsonWebTokens 6.8.0