Espacio de nombres Microsoft.Data.SqlClient y compatibilidad

El Microsoft.Data.SqlClient espacio de nombres contiene el proveedor de datos .NET compatible para bases de datos compatibles con SQL Server. Comenzó como una bifurcación de System.Data.SqlClient y conserva el conocido modelo de programación de ADO.NET, al tiempo que incorpora nuevas funcionalidades de SQL Server de forma independiente del entorno de ejecución de .NET.

Use Microsoft.Data.SqlClient para el desarrollo nuevo.

Instalar e importar el espacio de nombres

Añadir el paquete NuGet:

dotnet add package Microsoft.Data.SqlClient

Importar el espacio de nombres:

using Microsoft.Data.SqlClient;

La mayoría de las aplicaciones usan SqlConnection, SqlCommand, SqlParameter, SqlDataReader, y SqlTransaction. Para la superficie pública completa, véase la referencia de la API de Microsoft. Data.SqlClient.

Relación con ADO.NET

ADO.NET es el modelo de acceso a datos integrado en .NET. Define abstracciones independientes del proveedor en el espacio de nombres System.Data.Common, y Microsoft.Data.SqlClient proporciona las implementaciones concretas.

Microsoft. Data.SqlClient también ofrece APIs específicas de SQL Server tales como:

• SqlBulkCopy
• SqlConnectionStringBuilder
• SqlConfigurableRetryFactory
• SqlDependency
• Autenticación, cifrado y soporte de tipos de datos específicos de SQL Server

Programar contra las abstracciones ADO.NET cuando una biblioteca debe soportar múltiples proveedores de bases de datos. Utiliza los tipos SqlClient cuando una aplicación apunta a SQL Server y necesita funcionalidades específicas del proveedor, como autenticación Microsoft Entra, Always Encrypted, copia masiva, parámetros con valores de tabla o lógica de reintento configurable. Mantén el código específico del proveedor detrás de un límite de acceso a los datos si el resto de la aplicación debe permanecer independiente del proveedor.

Acceso en línea y sin conexión

El acceso en modo conectado mantiene la conexión abierta mientras se ejecuta un comando y mientras la aplicación lee sus resultados. Una petición típica sigue esta secuencia:

1. Crea un SqlConnection a partir de una cadena de conexión y ábrelo.
2. Crea una SqlCommand y añade los valores de SqlParameter.
3. Ejecute el comando.
4. Procesar un valor escalar, un conteo de filas afectadas o un SqlDataReader.
5. Deshazte del lector, el comando y la conexión.

Utiliza el acceso conectado para la mayoría de APIs web, servicios, trabajadores y aplicaciones de línea de comandos. SqlDataReader procesa filas en flujo y suele usar menos memoria que cargar el resultado completo en un DataSet.

El DataSet usa para copiar datos en un SqlDataAdapter o DataTable en memoria. La aplicación puede cerrar la conexión mientras lee o modifica los datos en memoria y luego volver a conectarse para enviar actualizaciones. Úsalo para vinculación de datos, relaciones y restricciones en memoria, ediciones offline que luego concilies o una aplicación existente construida alrededor de DataAdapters. Para nuevos servicios orientados a solicitudes, comienza con SqlCommand y SqlDataReader.

Vida útil del objeto y concurrencia

Abre y libera una SqlConnection para cada unidad de trabajo. El pooling de conexiones reutiliza la conexión física subyacente, así que no dejes una conexión global abierta durante toda la vida útil de una aplicación. Elimina conexiones, comandos, lectores, transacciones y objetos de copia masiva rápidamente. En código asíncrono, se utiliza await using para tipos que implementan IAsyncDisposable en el framework de destino, como SqlConnection y SqlDataReader en .NET, y ordinario using para tipos que implementan solo IDisposable, como SqlBulkCopy.

SqlConnection, SqlCommand, SqlDataReader, y SqlTransaction no soportan el uso simultáneo desde múltiples hilos. Asigna a cada operación concurrente su propia conexión y confía en la agrupación de conexiones. Múltiples Conjuntos de Resultados Activos (MARS) permite más de un conjunto activo de resultados en una conexión, pero no hace que los objetos SqlClient sean seguros para hilos.

Relación con System.Data.SqlClient

System.Data.SqlClient es el proveedor más antiguo que se incluye con .NET Framework y las versiones anteriores de .NET. Microsoft.Data.SqlClient Utiliza muchos de los mismos nombres de tipos, pero tiene paquetes, espacios de nombres, valores predeterminados, características y políticas de soporte diferentes.

No hagas referencia a ambos proveedores en el código de la solicitud nuevo. Los tipos con el mismo nombre de los dos paquetes no son intercambiables. Un System.Data.SqlClient.SqlConnection, por ejemplo, no puede pasarse donde se requiere un Microsoft.Data.SqlClient.SqlConnection.

La migración suele comenzar añadiendo el Microsoft.Data.SqlClient paquete y cambiando las referencias del espacio de nombres, pero también debes revisar el cifrado de la conexión, los parámetros, la configuración, las dependencias transitivas y el comportamiento en tiempo de ejecución. Sigue Migrar de System.Data.SqlClient a Microsoft. Data.SqlClient antes de desplegar.

Compatibilidad de versiones

La versión del paquete de controladores es independiente de la versión .NET de la aplicación y de la versión del motor de base de datos. Revisa los tres:

Para matrices actuales, véase ciclo de vida de soporte de controladores SqlClient.

Cambios específicos de la versión

Las versiones de drivers pueden añadir APIs, mover dependencias opcionales y cambiar valores predeterminados seguros. Revisa los cambios antes de cada actualización menor o mayor.

Algunos ejemplos son:

• La versión 4.0 cambió Encrypt para que pasara a ser true de forma predeterminada.
• La versión 5.0 introdujo SqlConnectionEncryptOption y Encrypt=Strict para TDS 8.0.
• La versión 5.2 incorporó SqlBatch en las plataformas de destino modernas de .NET compatibles.
• La versión 7.0 trasladó la autenticación de Microsoft Entra proporcionada por el controlador a Microsoft.Data.SqlClient.Extensions.Azure.

Consulta las novedades en Microsoft. Data.SqlClient para enlaces a notas de lanzamiento y un resumen de actualización.

Espacios de nombres y paquetes relacionados

Algunas características utilizan tipos fuera del espacio de nombres principal o paquetes opcionales.

No deduzcas los requisitos de los paquetes basándote únicamente en un espacio de nombres. Consulta el artículo sobre la característica y la información de dependencias del paquete NuGet correspondiente a la versión del controlador que utilices.

Contenido relacionado

• Instalar, actualizar y desplegar Microsoft. Data.SqlClient
• Migrar de System.Data.SqlClient a Microsoft. Data.SqlClient
• Novedades en Microsoft. Data.SqlClient
• Notas de la versión de Microsoft.Data.SqlClient