diff --git a/BUILDGUIDE.md b/BUILDGUIDE.md index fe98596d61..67d7a955d0 100644 --- a/BUILDGUIDE.md +++ b/BUILDGUIDE.md @@ -4,7 +4,7 @@ This document provides all the necessary details to build the driver and run tes ## Visual Studio Pre-Requisites -This project should be ideally built with Visual Studio 2017+ for the best compatibility. Use either of the two environments with their required set of compoenents as mentioned below: +This project should be built with Visual Studio 2019+ for the best compatibility. The required set of components are provided in the below file: - **Visual Studio 2019** with imported components: [VS19Components](/tools/vsconfig/VS19Components.vsconfig) Once the environment is setup properly, execute the desired set of commands below from the _root_ folder to perform the respective operations: @@ -106,6 +106,7 @@ Manual Tests require the below setup to run: |------|--------|-------------------| |TCPConnectionString | Connection String for a TCP enabled SQL Server instance. | `Server={servername};Database={Database_Name};Trusted_Connection=True;`
OR `Data Source={servername};Initial Catalog={Database_Name};Integrated Security=True;`| |NPConnectionString | Connection String for a Named Pipes enabled SQL Server instance.| `Server=\\{servername}\pipe\sql\query;Database={Database_Name};Trusted_Connection=True;`
OR
`Data Source=np:{servername};Initial Catalog={Database_Name};Integrated Security=True;`| +|TCPConnectionStringHGSVBS | (Optional) Connection String for a TCP enabled SQL Server with Host Guardian Service (HGS) attestation protocol configuration. | `Server=tcp:{servername}; Database={Database_Name}; UID={UID}; PWD={PWD}; Attestation Protocol = HGS; Enclave Attestation Url = {AttestationURL};`| |AADAuthorityURL | (Optional) Identifies the OAuth2 authority resource for `Server` specified in `AADPasswordConnectionString` | `https://login.windows.net/`, where `` is the tenant ID of the Azure Active Directory (Azure AD) tenant | |AADPasswordConnectionString | (Optional) Connection String for testing Azure Active Directory Password Authentication. | `Data Source={server.database.windows.net}; Initial Catalog={Azure_DB_Name};Authentication=Active Directory Password; User ID={AAD_User}; Password={AAD_User_Password};`| |AADSecurePrincipalId | (Optional) The Application Id of a registered application which has been granted permission to the database defined in the AADPasswordConnectionString. | {Application ID} | @@ -204,9 +205,9 @@ Tests can be built and run with custom Target Frameworks. See the below examples ``` ```bash -> msbuild /t:BuildTestsNetCore /p:TargetNetCoreVersion=netcoreapp3.0 +> msbuild /t:BuildTestsNetCore /p:TargetNetCoreVersion=netcoreapp3.1 # Build the tests for custom TargetFramework (.NET Core) -# Applicable values: netcoreapp2.1 | netcoreapp2.2 | netcoreapp3.0 +# Applicable values: netcoreapp2.1 | netcoreapp2.2 | netcoreapp3.1 | netcoreapp5.0 ``` ### Running Tests: @@ -216,9 +217,9 @@ Tests can be built and run with custom Target Frameworks. See the below examples # Use above property to run Functional Tests with custom TargetFramework (.NET Framework) # Applicable values: net46 (Default) | net461 | net462 | net47 | net471 net472 | net48 -> dotnet test /p:TargetNetCoreVersion=netcoreapp3.0 ... +> dotnet test /p:TargetNetCoreVersion=netcoreapp3.1 ... # Use above property to run Functional Tests with custom TargetFramework (.NET Core) -# Applicable values: netcoreapp2.1 | netcoreapp2.2 | netcoreapp3.0 +# Applicable values: netcoreapp2.1 | netcoreapp2.2 | netcoreapp3.1 | netcoreapp5.0 ``` ## Using Managed SNI on Windows @@ -256,7 +257,7 @@ There may be times where connection cannot be made to SQL Server, we found below - Clear Docker images to create clean image from time-to-time, and clear docker cache if needed by running `docker system prune` in Command Prompt. -- If you face `sni.dll not found` errors when debugging, try updating below properties in netcore\Microsoft.Data.SqlClient.csproj file and try again: +- If you face `Microsoft.Data.SqlClient.SNI.dll not found` errors when debugging, try updating the below properties in the netcore\Microsoft.Data.SqlClient.csproj file and try again: ```xml Unix false diff --git a/CHANGELOG.md b/CHANGELOG.md index c9dc431b85..409e175eed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,31 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) -## [Preview Release 2.0.0-preview4.20142.4 ] - 2020-05-21 +## [Stable Release 2.0.0] - 2020-06-16 + +### Added +- Added internal driver support to provide resiliency to DNS failures [#594](https://github.com/dotnet/SqlClient/pull/594) +- Added support for `Active Directory Integrated`, `Active Directory Interactive` and `Active Directory Service Principal` authentication mode for .NET Core and .NET Standard [#560](https://github.com/dotnet/SqlClient/pull/560) +- Added support for `Active Directory Service Principal` authentication mode for .NET Framework [#560](https://github.com/dotnet/SqlClient/pull/560) +- Added support for optional `ORDER` hints in `SqlBulkCopy` for improved performance [#540](https://github.com/dotnet/SqlClient/pull/540) + +### Fixed +- Fixed `SqlSequentialStream` multipacket read stalling issue in .NET Core [#603](https://github.com/dotnet/SqlClient/pull/603) +- Fixed code page issue for Kazakh collation in SQL Server [#584](https://github.com/dotnet/SqlClient/pull/584) +- Fixed stalled application issues when end of stream is reached [#577](https://github.com/dotnet/SqlClient/pull/577) +- Fixed driver behavior to not throw exception for invalid configuration file [#573](https://github.com/dotnet/SqlClient/pull/573) +- Fixed Object null reference issue when failover partner is set [#588](https://github.com/dotnet/SqlClient/pull/588) +- Fixed `applicationintent` connection string property issue [#585](https://github.com/dotnet/SqlClient/pull/585) + +### Changes +- Raise warning message when insecure TLS protocols are in use [#591](https://github.com/dotnet/SqlClient/pull/591) + +### Breaking Changes +- Modified enclave provider interface `SqlColumnEncryptionEnclaveProvider` to be internal [#602](https://github.com/dotnet/SqlClient/pull/602) - _This change is not likely to impact customer applications since secure enclaves is a relatively new feature and they would have had to implement their own enclave provider, which is not a trivial task_. +- Updated `SqlClientMetaDataCollectionNames` exposed constants by removing non-existing constants and adding new to the metadata collection [#580](https://github.com/dotnet/SqlClient/pull/580) + + +## [Preview Release 2.0.0-preview4.20142.4] - 2020-05-21 ### Added - 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** [#570](https://github.com/dotnet/SqlClient/pull/570) diff --git a/README.md b/README.md index 87db72ab54..4bf96a5f71 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,9 @@ The Microsoft.Data.SqlClient NuGet package is available on [NuGet.org](https://w ## SNI Package References -For the .NET Framework driver on Windows, a package reference to [Microsoft.Data.SqlClient.SNI](https://www.nuget.org/packages/Microsoft.Data.SqlClient.SNI/) loads `x64` and `x86` native `SNI.dll` libraries into the client's build directories. +For the .NET Framework driver on Windows, a package reference to [Microsoft.Data.SqlClient.SNI](https://www.nuget.org/packages/Microsoft.Data.SqlClient.SNI/) loads native `Microsoft.Data.SqlClient.SNI.x64.dll` and `Microsoft.Data.SqlClient.SNI.x86.dll` libraries into the client's build directories. -For the .NET Core driver on Windows, a package reference to [runtime.native.System.Data.SqlClient.sni](https://www.nuget.org/packages/runtime.native.System.Data.SqlClient.sni/) loads `arm64`, `x64` and `x86` native `SNI.dll` libraries into the client's build directories. +For the .NET Core driver on Windows, a package reference to [Microsoft.Data.SqlClient.SNI.runtime](https://www.nuget.org/packages/Microsoft.Data.SqlClient.SNI.runtime/) loads `arm`, `arm64`, `x64` and `x86` native `Microsoft.Data.SqlClient.SNI.dll` libraries into the client's build directories. ## Helpful Links @@ -48,9 +48,10 @@ We thank you for your continuous support in improving the SqlClient library! - Wraith ([@Wraith2](https://github.com/Wraith2)) - Erik Ejlskov Jensen ([@ErikEJ](https://github.com/ErikEJ)) +- Simon Cropp ([@SimonCropp](https://github.com/SimonCropp)) - Stefán Jökull Sigurðarson ([@stebet](https://github.com/stebet)) -- Stephen Toub ([@stephentoub](https://github.com/stephentoub)) - Shay Rojansky ([@roji](https://github.com/roji)) +- Stephen Toub ([@stephentoub](https://github.com/stephentoub)) - Rasmus Melchior Jacobsen ([@rmja](https://github.com/rmja)) - Phillip Haydon ([@phillip-haydon](https://github.com/phillip-haydon)) - Robin Sue ([@Suchiman](https://github.com/Suchiman)) diff --git a/release-notes/2.0/2.0.0.md b/release-notes/2.0/2.0.0.md new file mode 100644 index 0000000000..a4c2af4b10 --- /dev/null +++ b/release-notes/2.0/2.0.0.md @@ -0,0 +1,211 @@ +# Release Notes + +## Microsoft.Data.SqlClient 2.0.0 released 16 June 2020 + +This update brings the below changes over the previous release: + +### Added +- Added internal driver support to provide resiliency to DNS failures [#594](https://github.com/dotnet/SqlClient/pull/594) +- Added support for `Active Directory Integrated`, `Active Directory Interactive` and `Active Directory Service Principal` authentication mode for .NET Core and .NET Standard [#560](https://github.com/dotnet/SqlClient/pull/560) +- Added support for `Active Directory Service Principal` authentication mode for .NET Framework [#560](https://github.com/dotnet/SqlClient/pull/560) +- Added support for optional `ORDER` hints in `SqlBulkCopy` for improved performance [#540](https://github.com/dotnet/SqlClient/pull/540) + +### Fixed +- Fixed `SqlSequentialStream` multipacket read stalling issue in .NET Core [#603](https://github.com/dotnet/SqlClient/pull/603) +- Fixed code page issue for Kazakh collation in SQL Server [#584](https://github.com/dotnet/SqlClient/pull/584) +- Fixed stalled application issues when end of stream is reached [#577](https://github.com/dotnet/SqlClient/pull/577) +- Fixed driver behavior to not throw exception for invalid configuration file [#573](https://github.com/dotnet/SqlClient/pull/573) +- Fixed Object null reference issue when failover partner is set [#588](https://github.com/dotnet/SqlClient/pull/588) +- Fixed `applicationintent` connection string property issue [#585](https://github.com/dotnet/SqlClient/pull/585) + +### Changes +- Raise warning message when insecure TLS protocols are in use [#591](https://github.com/dotnet/SqlClient/pull/591) + +### Breaking Changes +- Modified enclave provider interface `SqlColumnEncryptionEnclaveProvider` to be internal [#602](https://github.com/dotnet/SqlClient/pull/602) - _This change is not likely to impact customer applications since secure enclaves is a relatively new feature and they would have had to implement their own enclave provider, which is not a trivial task_. +- Updated `SqlClientMetaDataCollectionNames` exposed constants by removing non-existing constants and adding new to the metadata collection [#580](https://github.com/dotnet/SqlClient/pull/580) + +## New features in v2.0 + +New features over the 1.1 release of Microsoft.Data.SqlClient: +- [Additional Active Directory authentication modes](#additional-active-directory-authentication-modes) +- [EventSource tracing support](#eventSource-tracing-support) +- [SNI dependency changes](#sni-dependency-changes) +- [Enable Managed networking on Windows](#enable-managed-networking-on-windows) +- [Enable decimal truncation behavior conditionally](#enable-decimal-truncation-behavior-conditionally) +- [New connection string property synonyms](#new-connection-string-property-synonyms) +- [SqlBulkCopy RowsCopied property](#sqlbulkcopy.rowscopied-property) +- [Connection Open Overrides](#connection-open-overrides) +- [Username support for Active Directory Interactive mode](#username-support-for-active-directory-interactive-mode) +- [Order Hints for SqlBulkCopy](#order-hints-for-sqlbulkcopy) + + +### Additional Active Directory authentication modes +This release brings parity of Active Directory authentication modes supported for .NET Framework and .NET Core applications. With the 2.0 stable release, the following authentication modes are supported for **Microsoft.Data.SqlClient**: + +|Authentication mechanism | .NET Framework 4.6+ | .NET Core 2.1+ | .NET Standard 2.0+| +|------|--------|--------|--------| +|Active Directory Password | Yes | Yes | Yes | +|Active Directory Integrated | Yes | **Yes**1 | **Yes**1 | +|Active Directory Interactive | Yes | **Yes**1 | **Yes**1 | +|**Active Directory Service Principal**1 | **Yes**1 | **Yes**1 | **Yes**1 | + +_1 New authentication mode starting with Microsoft.Data.SqlClient v2.0_ + +#### Active Directory Service Principal +This authentication mode uses Active Directory Service Principal to connect to an Azure SQL Database using the client ID and secret of a service principal identity. Service principal authentication involves setting up an App registration with a secret, granting permissions to the App in the Azure SQL Database instance, then connecting with a connection string like the following: + +`Server=tcp:.database.windows.net;Database=;Authentication=Active Directory Service Principal;User Id=;Password=;` + +### EventSource tracing support +This release introduces support for capturing EventSource trace logs for debugging applications. In order to capture these traces, client applications must listen to events from SqlClient's EventSource implementation: + +"Microsoft.Data.SqlClient.EventSource" + +Supported Event Keywords are: + +| Keyword Name | Value | Description | +| ------------ | ----- | ----------- | +| ExecutionTrace | 1 | Turns on capturing Start/Stop events before and after command execution. | +| Trace | 2 | Turns on capturing basic application flow trace events. | +| Scope | 4 | Turns on capturing enter and exit events | +| NotificationTrace | 8 | Turns on capturing `SqlNotification` trace events | +| NotificationScope | 16 | Turns on capturing `SqlNotification` scope enter and exit events | +| PoolerTrace | 32 | Turns on capturing connection pooling flow trace events. | +| PoolerScope | 64 | Turns on capturing connection pooling scope trace events. | +| AdvancedTrace | 128 | Turns on capturing advanced flow trace events. | +| AdvancedTraceBin | 256 | Turns on capturing advanced flow trace events with additional information. | +| CorrelationTrace | 512 | Turns on capturing correlation flow trace events. | +| StateDump | 1024 | Turns on capturing full state dump of `SqlConnection` | +| SNITrace | 2048 | Turns on capturing flow trace events from Managed Networking implementation (only applicable in .NET Core) | +| SNIScope | 4096 | Turns on capturing scope events from Managed Networking implementation (only applicable in .NET Core) | +||| + + +### Enable managed networking on Windows +This release introduces a new AppContext switch, "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", that enables the use of Managed SNI on Windows for testing and debugging purposes. This switch will toggle the driver's behavior to use Managed SNI in .NET Core 2.1+ and .NET Standard 2.0+ projects on Windows. Using the managed SNI implementation eliminates the dependency on the native Microsoft.Data.SqlClient.SNI binaries for a fully managed stack. + +To set the switch from app startup, specify: + +```cs +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true); +``` +> [NOTE] **Known differences when compared to Native SNI.dll**: Managed SNI does not support non-domain Windows Authentication. + + +### Enable decimal truncation behavior conditionally +Starting with v2.0.0-preview3, 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](https://docs.microsoft.com/en-us/dotnet/api/system.appcontext?view=netframework-4.8) switch "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" to "true". + +To set the switch at application startup, specify: + +```cs +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true); +``` + +### New Connection string property synonyms + +The below connection properties can be interchangeably used with the new synonyms to avoid spacing confusion and for an enhanced user experience. + +|Existing connection string property|New Synonym| +|-----------------------------------|-----------| +| ApplicationIntent | Application Intent | +| ConnectRetryCount | Connect Retry Count | +| ConnectRetryInterval | Connect Retry Interval | +| PoolBlockingPeriod | Pool Blocking Period | +| MultipleActiveResultSets | Multiple Active Result Sets | +| MultiSubnetFailover | Multiple Subnet Failover | +| TransparentNetworkIPResolution | Transparent Network IP Resolution | +| TrustServerCertificate | Trust Server Certificate | + +> [Note] This is not a breaking change. Old properties will continue to be supported for backwards compatibility. + + +#### SqlBulkCopy.RowsCopied property + +This property provides read-only access to the number of rows processed in the ongoing bulk copy operation. Note that this value is not necessarily equal to the 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. + +```csharp +using SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"); +sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry); +``` + +#### Username support for Active Directory Interactive mode + +A username can now be specified in the connection string when using Azure Active Directory Interactive authentication mode for both .NET Framework and .NET Core targeted applications. + +Set a username using the **User ID** or **UID** connection string property: + +``` +"Server=; Database=; Authentication=Active Directory Interactive; User Id=;" +``` + +#### Order hints for SqlBulkCopy + +Bulk copy operations offer significant performance advantages over other methods for loading data into a SQL Server table. Performance can be further enhanced by using order hints. Specifying order hints for your bulk copy operations can lower the insertion time of sorted data into tables with clustered indexes. + +By default, the bulk insert operation assumes the incoming data is unordered. SQL Server forces an intermediate sort of this data before bulk loading it. If you know that your incoming data is already sorted, you can use order hints to tell the bulk copy operation about the sort order of any destination columns that are part of a clustered index. + + +#### SNI dependency changes + +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. + + +## 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.0.0 +- Microsoft.Identity.Client 4.14.0 +- Microsoft.IdentityModel.Protocols.OpenIdConnect 5.6.0 +- Microsoft.IdentityModel.JsonWebTokens 5.6.0 + +#### .NET Core 2.1 + +- Microsoft.Data.SqlClient.SNI.runtime 2.0.0 +- 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.14.0 +- Microsoft.IdentityModel.Protocols.OpenIdConnect 5.6.0 +- Microsoft.IdentityModel.JsonWebTokens 5.6.0 + +#### .NET Core 3.1 + +- Microsoft.Data.SqlClient.SNI.runtime 2.0.0 +- 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.14.0 +- Microsoft.IdentityModel.Protocols.OpenIdConnect 5.6.0 +- Microsoft.IdentityModel.JsonWebTokens 5.6.0 + +#### .NET Standard + +- Microsoft.Data.SqlClient.SNI.runtime 2.0.0 +- 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.14.0 +- Microsoft.IdentityModel.Protocols.OpenIdConnect 5.6.0 +- Microsoft.IdentityModel.JsonWebTokens 5.6.0 diff --git a/release-notes/2.0/2.0.md b/release-notes/2.0/2.0.md index a50abbaaf4..57ab9b4f80 100644 --- a/release-notes/2.0/2.0.md +++ b/release-notes/2.0/2.0.md @@ -1,5 +1,11 @@ # Microsoft.Data.SqlClient 2.0 Releases +The following Microsoft.Data.SqlClient 2.0 stable releases have been shipped: + +| Release Date | Version | Notes | +| :-- | :-- | :--: | +| 2020/06/16 | 2.0.0 | [release notes](2.0.0.md) | + The following Microsoft.Data.SqlClient 2.0 preview releases have been shipped: | Release Date | Version | Notes | diff --git a/release-notes/2.0/README.md b/release-notes/2.0/README.md index a50abbaaf4..57ab9b4f80 100644 --- a/release-notes/2.0/README.md +++ b/release-notes/2.0/README.md @@ -1,5 +1,11 @@ # Microsoft.Data.SqlClient 2.0 Releases +The following Microsoft.Data.SqlClient 2.0 stable releases have been shipped: + +| Release Date | Version | Notes | +| :-- | :-- | :--: | +| 2020/06/16 | 2.0.0 | [release notes](2.0.0.md) | + The following Microsoft.Data.SqlClient 2.0 preview releases have been shipped: | Release Date | Version | Notes | diff --git a/release-notes/README.md b/release-notes/README.md index 829f2a2822..1986a536cb 100644 --- a/release-notes/README.md +++ b/release-notes/README.md @@ -1,6 +1,6 @@ # Microsoft.Data.SqlClient Release Notes -The latest stable release is [Microsoft.Data.SqlClient 1.1](1.1). +The latest stable release is [Microsoft.Data.SqlClient 2.0](2.0). ## Release Information