Frequently Asked Questions
It is! https://github.com/dotnet/SqlClient
The System.Data.SqlClient library in the .NET Core repository is the source for the System.Data.SqlClient NuGet package. (It is distinctly different from System.Data.SqlClient in .NET Framework.) While technically supported for backwards compatibility, it has been in maintenance mode since 2019, having been based out of .NET Core 3.1, which is itself no longer supported. It will remain available on NuGet.org.
Add the Nuget package to your project, then update your references and using statements. Refer: porting-cheat-sheet.md
There are two primary changes:
First, since this is an application level package, for .NET Framework any updates to the library will need to be shipped in an application update, rather than coming from Windows Update. This matches the existing behavior for .NET/.NET Core applications.
Second, new features are being introduced in Microsoft.Data.SqlClient which will not be backported to System.Data.SqlClient. Features like Data Classification Support, UTF-8 support for .NET Framework, Always Encrypted support for .NET/.NET Core, TDS 8 support, and many new Azure Active Directory authentication options.
Issues should be opened under this GitHub repository.
Starting in version 1.0, the package supports .NET Framework 4.6 and up, .NET Core 2.1 and up, and .NET Standard 2.0 and up. As frameworks go out of support, they will be dropped from subsequent versions of Microsoft.Data.SqlClient. For earlier framework support please continue to use System.Data.SqlClient.
7. Can I use Microsoft.Data.SqlClient and System.Data.SqlClient at the same time / in the same application?
Yes. The libraries can reside side by side just like any other library, but since they contain the same class names this could cause confusion. We recommend porting entirely to one or the other if possible.
No. This brings the existing two code bases (one for System.Data.SqlClient in .NET Framework and one for System.Data.SqlClient in .NET Core) into a single package for distribution. There are still divergent code bases underneath Microsoft.Data.SqlClient which are compiled into the different supported targets. The .NET Framework code base compiles into the binaries in the package which support .NET Framework targets and the .NET Core code base compiles into the binaries in the package which support .NET Core and .NET Standard targets. When you add the NuGet package to your application, the package provides the appropriate binary for your application's defined target.
The long-term goal is to merge the code bases. Progress has been made, but there is still some remaining code split.
10. Why is there still feature disparity between .NET Framework targets and .NET Core/Standard targets?
To understand this, you need to understand where the code for .NET Core came from. When .NET Core first came out several years ago, the code for SqlClient was brought over from .NET Framework and a lot of changes were made to make it cross-platform and to fit into the functionality available in .NET Core at that time. The code bases continued to diverge from there with Framework seeing the majority of new feature work.
We've been porting SqlClient feature changes from the Framework code to the Core code to bring the targets up to feature parity. The latest versions largely have feature parity, but you may still find a few minor differences.
The Microsoft.Data.SqlClient NuGet package includes a number of DLLs supporting different .NET targets and different runtime platforms. If you are getting a PlatformNotSupported Exception when you don't think you should be, it ultimately means your application is not loading the appropriate DLL. There could be a number of reasons for this. The NuGet package structure and infrastructure around referencing and loading referenced NuGet packages includes logic that allows a package to contain multiple DLLs which implement support for different .NET and platform targets. Meaning a different DLL for .NET Framework, .NET Core, .NET Standard, Windows, Linux, etc. The NuGet infrastructure will automatically reference and load the appropriate DLL based on your application's needs.
If your application loads a DLL from a NuGet package directly, it bypasses all this logic and probably loads the incorrect DLL. The DLL in the NuGet package under lib/netstandard2.0/Microsoft.Data.SqlClient.dll is basically the fallback DLL for any unsupported target and simply throws the PlatformNotSupported exception for any call. This is a nicer exception than what you would otherwise get when running on a platform that does not have a DLL built for it. Ultimately, you want to use the NuGet package reference infrastructure or you would have to implement all this target framework and platform support logic yourself when determining which DLL to load.
Additionally, the NuGet package contains all the dependency information for the SqlClient library and facilitates the downloading and referencing of dependencies. If you reference and load an individual DLL manually, it is up to you to ensure all dependencies are also available to the SqlClient library.
12. I have upgraded Microsoft.Data.SqlClient to version 4.0.0, but am not able to open a connection which was working in a previous version.
Microsoft.Data.SqlClient.SqlException (0x80131904): A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
---> System.ComponentModel.Win32Exception (0x80090325): The certificate chain was issued by an authority that is not trusted and similar exceptions might be seen due to this breaking change.
Starting from v4.0.0 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 was time for this backwards-compatibility-breaking change.
This is consistent with security best practices. Similar to http/https, if the client starts with allowing non-encrypted connections, it will always be susceptible to MITM attacks. Even if the server is configured to require encryption, there can be an MITM altering the server's response to say it doesn't require encryption. The MITM can then proxy the connection. client <-plain text-> MITM <-encrypted-> server = the connection is compromised.
Security advisors have been encouraging us for some time to consider changing the default behavior of client drivers to be secure by default, while acknowledging that it is a breaking change for many users. It's easy enough for developers to add Encrypt = false to all their connection strings, if they need to. We just want to make sure they understand the choice they are making and they are making it deliberately. With cloud computing becoming more and more common, it's not safe to leave the default value of Encrypt equal to false. With this latest major version bump, the timing was right to make this change.