-
Notifications
You must be signed in to change notification settings - Fork 286
Frequently Asked Questions
It is! https://github.com/dotnet/SqlClient
The existing library will remain. PRs to the System.Data.SqlClient library will be ported to Microsoft.Data.SqlClient as relevant. Bugs and security issues which are deemed important will continue to be fixed in System.Data.SqlClient.
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 Core applications.
Second, there are a few new features in Microsoft.Data.SqlClient which will not be backported to System.Data.SqlClient. Those features are Data Classification Support, UTF-8 support for .Net Framework, and Always Encrypted support for .NET Core.
Issues should be opened under this GitHub repository.
The package supports .NET Framework 4.6 and up, .NET Core 2.1 and up, and .NET Standard 2.0 and up. 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 but we aren't there yet.
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. But there are still a few things left to do.
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 not able to open a connection which was working in 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's time for this backwards-compatibility-breaking change.
This is for security. 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 a 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 has been encouraging us for years to change the default behavior of client drivers to be secure by default and we have resisted, knowing that it is a breaking change for most 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.