Migrar de System.Data.SqlClient a Microsoft. Data.SqlClient

Microsoft.Data.SqlClient es el proveedor admitido para las nuevas características de SQL Server en las aplicaciones .NET. Conserva el modelo de programación ADO.NET utilizado por System.Data.SqlClient, pero los paquetes, espacios de nombres, valores predeterminados y algunos tipos públicos difieren.

Trata la migración como una actualización del proveedor, no solo como un reemplazo del espacio de nombres.

Planear la migración

Antes de cambiar el código:

1. Registra las versiones de .NET, System.Data.SqlClientSQL Server y Microsoft SQL que soporta la aplicación.

2. Modos de autenticación, palabras clave de la cadena de conexión, certificados personalizados, proveedores de Always Encrypted, configuración de DbProviderFactories, tipos definidos por el usuario de SQL Server y uso de System.Data.SqlTypes.

3. Ejecuta las pruebas actuales de la aplicación y guarda una línea base para el comportamiento de conexión, consulta, transacción, reintento y rendimiento.

4. Buscar referencias directas y transitivas de paquetes:

   dotnet list package --include-transitive
   

Migra una aplicación o biblioteca de acceso a datos compartidos a la vez. No pases objetos específicos de proveedor entre código que aún usa System.Data.SqlClient y código que usa Microsoft.Data.SqlClient.

Cambia el paquete

Elimina una referencia explícita System.Data.SqlClient al paquete, si está presente:

dotnet remove package System.Data.SqlClient

Agregar Microsoft.Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Si Microsoft. Data.SqlClient 7.0 o posterior utiliza un modo de autenticación Microsoft Entra proporcionado por el controlador, también añade:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

Para la selección de versiones y paquetes, consulta Instalar, actualizar y desplegar Microsoft. Data.SqlClient.

Actualizar espacios de nombres

Sustituye el espacio de nombres principal del proveedor:

-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;

Actualizar nombres totalmente calificados, alias, código generado, registros de inyección de dependencias, cadenas de reflexión, configuración y dobles de prueba que se refieren a System.Data.SqlClient.

No sustituyas los espacios de nombres generales System.Data ni System.Data.Common. Microsoft.Data.SqlClientcontinúa usando tipos ADO.NET como CommandType, DbType, IsolationLevel, DataTable, DbConnection, y DbCommand de esos espacios de nombres.

Algunos tipos específicos de SQL Server se mueven a otros Microsoft.Data espacios de nombres:

En Microsoft.Data.SqlClient la versión 5.0 y posteriores, otros tipos de ejecución de lenguaje común (CLR) de SQL Server permanecen en Microsoft.SqlServer.Server. Actualice cada tipo a partir de los errores del compilador y de la referencia de la API de Microsoft.Data.SqlClient, en lugar de reemplazar todo el espacio de nombres.

Actualizar la configuración del marco .NET

Una aplicación que resuelve proveedores a través de DbProviderFactories podría requerir el registro de un proveedor en App.config o Web.config:

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

Código de actualización que solicite el nombre invariante del proveedor:

DbProviderFactory factory =
    DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");

No añadas esta configuración cuando la aplicación crea SqlConnection directamente y no use DbProviderFactories.

Revisar el cifrado y la validación de certificados

Microsoft. Data.SqlClient utiliza valores predeterminados más seguros que System.Data.SqlClient.

No establezcas Encrypt=false ni TrustServerCertificate=true como solución genérica de migración. Configura un certificado en el que el cliente confíe y usa un nombre de servidor que coincida con el certificado. Úsalo TrustServerCertificate=true solo en entornos de desarrollo controlados donde la validación no sea posible.

El cambio a SqlConnectionEncryptOption es compatible con el código fuente en asignaciones comunes mediante conversiones implícitas, pero es un cambio que rompe binarios. Recompila cada ensamblado que acceda a SqlConnectionStringBuilder.Encrypt.

Para más información, consulte Cifrado y validación de certificados.

Revisar cadenas de conexión

Microsoft. Data.SqlClient añade palabras clave y alias que System.Data.SqlClient no reconoce. Por ejemplo, acepta alias con espacios como Application Intent y Multi Subnet Failover.

No construyas una cadena de conexión con Microsoft.Data.SqlClient.SqlConnectionStringBuilder y luego la pases a System.Data.SqlClient. Durante una migración por etapas, mantén cada generador de cadenas de conexión asociado con su proveedor.

Revisa las palabras clave de autenticación, cifrado, reintentos, conmutación por error y certificados en relación con la sintaxis de cadenas de conexión.

Revisión del comportamiento de los parámetros

Parámetros de fecha y hora de la prueba explícitamente:

Especifica SqlDbType, longitud, precisión y escala para parámetros donde la inferencia tipo SQL Server puede cambiar los planes de consulta o el comportamiento de conversión. No lo uses AddWithValue como atajo de migración cuando se conoce el tipo de base de datos.

Consulta referencias de proveedores transitivos

La eliminación directa del paquete no garantiza que System.Data.SqlClient haya desaparecido. ¡Corre!

dotnet list package --include-transitive

Si ambos proveedores permanecen:

1. Identifica el paquete que trae System.Data.SqlClient.
2. Actualiza o reemplaza esa dependencia cuando sea posible.
3. Mantén los tipos propios del proveedor dentro del límite de dependencia cuando ambos deban mantenerse.
4. Usa alias explícitos en espacios de nombres solo como ayuda temporal. No pases una conexión, transacción, parámetro o lector de un proveedor a otro.

Presta especial atención a las bibliotecas de tipos CLR de SQL Server y a los entornos de acceso a datos antiguos que exponen tipos System.Data.SqlClient en sus API públicas.

Revisar el comportamiento de la globalización

Las versiones de .NET Framework y .NET anteriores a .NET 5 utilizan la globalización de Soporte Nacional de Lenguas (NLS) en Windows. Las versiones actuales de .NET utilizan por defecto Componentes Internacionales para Unicode (ICU) en Windows, Linux y macOS.

Esta diferencia de tiempo de ejecución puede cambiar algunas SqlString comparaciones. SQL Server utiliza el comportamiento de comparación de NLS. Si las comparaciones en el cliente SqlString deben coincidir con el comportamiento del servidor, prueba los valores afectados y consulta Globalization and ICU. Una aplicación puede usar NLS en lugar de UCI cuando sea necesario.

Microsoft.Data.SqlClient no admite el modo invariable de globalización.

Validar la aplicación migrada

Compila y prueba en cada framework objetivo y sistema operativo compatible.

Validar:

• Restauración de paquetes y salida publicada.
• Autenticación SQL, autenticación integrada de Windows y autenticación Microsoft Entra utilizada por la aplicación.
• Negociación de TLS, validación de certificados y análisis de la cadena de conexión.
• Agrupación de conexiones y actualización del token de acceso.
• Tipos de parámetros, valores nulos, precisión, comportamiento de escala, fecha y tiempo.
• Transacciones, cancelación, tiempos de espera, reintentos y conmutación por error.
• Siempre cifrado, tipos CLR de SQL Server, copia masiva, notificaciones de consulta y otras funciones específicas del proveedor utilizadas por la aplicación.
• Registros, contadores, rastreo y gestión de excepciones.

Ejecuta consultas representativas en todas las versiones compatibles del motor de base de datos. Una compilación exitosa no valida la seguridad de la conexión, las dependencias en tiempo de ejecución ni las conversiones de datos.

Contenido relacionado

• Espacio de nombres Microsoft.Data.SqlClient y compatibilidad
• Notas de la versión y actualizaciones de Microsoft.Data.SqlClient
• Portabilidad de la hoja de trucos en el repositorio SqlClient
• Referencia de la API de Microsoft.Data.SqlClient