Migrating from System.Data.SqlClient

Migrate from System.Data.SqlClient

Home / Migrate / Plan

A safe migration is more than a namespace replacement. Start with a dependency inventory, keep provider-specific objects on the correct side of library boundaries, and make security settings explicit.

This guide covers System.Data.SqlClient (SDS) to Microsoft.Data.SqlClient (MDS), with differences called out for the 6.1 and 7.0 release lines. The five pages include the migration actions, configuration examples, and compatibility checks needed for those targets. Microsoft Learn and official release notes provide deeper product reference; this is not an exhaustive binary API diff.

Separate three changes

Change	Review
SDS to MDS, same runtime and OS	Namespaces, provider identity, encryption defaults, APIs, dependencies, runtime behavior
.NET Framework to modern .NET	Framework support, configuration, globalization, deployment model
Windows to Linux/macOS	Authentication infrastructure, native dependencies, platform-specific features

Avoid combining all three in one cutover when they can be tested separately.

Before changing code

Choose a supported line and current patch in Releases and support. LTS can suit a longer servicing horizon; 7.x offers a smaller core dependency footprint when driver-provided Entra authentication is unnecessary. Choose based on your feature, support, and deployment needs, not a universal "best version."

Inventory applications, shared libraries, plugins, ORMs/providers, configuration sources, background jobs, and deployment targets. An ORM using MDS internally does not prove your own application has no SDS references.

Stop and assess: SQLCLR code using an in-process context connection is not a drop-in MDS migration. Keep that path on its supported in-box provider or redesign it separately. For LocalDB, FILESTREAM, distributed transactions, spatial libraries, or custom native components, check the exact feature/runtime/OS combination before committing to a platform move.

Five-step migration checklist

1. Plan: record the current and target provider/runtime/OS, package graph, authentication methods, baseline behavior, and rollback artifact.
2. Update code: follow Code and APIs, including exception handlers and provider-factory registration.
3. Secure connections: follow Security and authentication; exercise every identity and deployment environment.
4. Protect behavior: follow Runtime and compatibility; compare returned values and both sync/async paths.
5. Ship deliberately: follow Deployment and rollout; deploy the complete application and monitor the cutover.

Coexistence can be necessary during a staged migration, but SDS and MDS connections, transactions, parameters, exceptions, and pools are not interchangeable. Treat each boundary explicitly.

Need help now? Jump to Troubleshooting.

Next: Code and API changes.

Sources: official porting cheat sheet, SqlClient introduction.