-
Notifications
You must be signed in to change notification settings - Fork 292
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.
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 exeception 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.