Migration Code and APIs

Migration: code and APIs

Home / Migrate / Code

Change provider-specific types, not every namespace containing Sql.

Namespace map

These mappings apply to the 6.1/7.0 target lines in this guide and follow the MDS 5.0-and-newer layout.

Existing type or namespace	MDS equivalent
System.Data.SqlClient	Microsoft.Data.SqlClient
System.Data.Sql.SqlNotificationRequest	Microsoft.Data.Sql.SqlNotificationRequest
System.Data.Sql.SqlDataSourceEnumerator	Microsoft.Data.Sql.SqlDataSourceEnumerator
System.Data.SqlTypes.SqlFileStream	Microsoft.Data.SqlTypes.SqlFileStream
System.Data.OperationAbortedException	Microsoft.Data.OperationAbortedException
Microsoft.SqlServer.Server.SqlDataRecord / SqlMetaData	Microsoft.Data.SqlClient.Server.SqlDataRecord / SqlMetaData

Keep System.Data.SqlDbType, general System.Data/System.Data.Common types, and other System.Data.SqlTypes types such as SqlDecimal and SqlString. Apart from SqlDataRecord and SqlMetaData, types in Microsoft.SqlServer.Server remain there, including UDT attributes and IBinarySerialize. Do not move the entire namespace. MDS 4.x and older had different mappings; do not apply those historical mappings to these target versions.

Audit the boundaries

Update constructors, aliases, fully qualified names, exception handlers, reflection strings, configuration, and public signatures that expose SqlClient types. A handler for System.Data.SqlClient.SqlException does not catch Microsoft.Data.SqlClient.SqlException.

Obtain compatible versions of third-party libraries that expose or require a concrete provider. Where an abstraction such as DbConnection is used, verify the library actually accepts MDS rather than casting internally to SDS. Do not pass a transaction from one provider to a command from the other.

Provider-factory registration

If your application obtains connections through DbProviderFactories, change the provider invariant name to Microsoft.Data.SqlClient. Registration is not required simply to construct SqlConnection directly.

For .NET Framework, merge this into the application's existing App.config or Web.config, without duplicating the enclosing sections. The remove entry avoids a duplicate inherited MDS registration; it does not remove SDS.

<configuration>
  <system.data>
    <DbProviderFactories>
      <remove invariant="Microsoft.Data.SqlClient" />
      <add name="Microsoft SqlClient Data Provider"
           invariant="Microsoft.Data.SqlClient"
           description="Microsoft SqlClient Data Provider for SQL Server"
           type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
    </DbProviderFactories>
  </system.data>
</configuration>

For modern .NET, register at application startup before the first factory lookup:

System.Data.Common.DbProviderFactories.RegisterFactory(
    "Microsoft.Data.SqlClient",
    Microsoft.Data.SqlClient.SqlClientFactory.Instance);

Consumers can then call DbProviderFactories.GetFactory("Microsoft.Data.SqlClient"). Update any associated providerName configuration to the same invariant. See SqlClientFactory registration for more detail.

Compilation is necessary, not sufficient

Check	Action
SqlClientMetaDataCollectionNames.Parameters / ProcedureColumns	The old fields are absent; use the documented collection names "Parameters" / "ProcedureColumns" where needed.
Libraries built against MDS before 5.0	The Encrypt property changed from bool to SqlConnectionEncryptOption. Upgrade or rebuild affected libraries; binding redirects do not repair an incompatible member signature.
Boolean Encrypt source assignments	Implicit conversion remains available. Do not incorrectly describe every Boolean assignment as a compile error; review type inference and configuration binding too.
UDT/SQL CLR helper types	Review the Microsoft.SqlServer.Server package and target-framework dependencies. SqlDataRecord and SqlMetaData remain in Microsoft.Data.SqlClient.Server.
Custom authentication providers moving to 7.x	Add the required extension reference and rebuild affected provider assemblies; do not assume every moved type is forwarded.

An SDS-to-MDS namespace change and a pre-5.0-to-newer-MDS binary break are distinct problems. Rebuild your changed projects and update affected dependencies; do not demand recompilation of every unrelated binary.

Next: Security and authentication.

Sources: porting cheat sheet, 2.0 release notes, 5.0 release notes, 7.0 authentication migration.