Instalar, actualizar y desplegar Microsoft. Data.SqlClient

Microsoft. Data.SqlClient es el proveedor de datos .NET compatible para SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, base de datos SQL en Microsoft Fabric y Warehouse en Microsoft Fabric. El controlador se distribuye como paquetes NuGet independientemente del entorno de ejecución de .NET.

Elige una versión

Utiliza una versión de Disponibilidad General (GA) soportada para aplicaciones de producción.

Línea de lanzamiento Nivel de soporte Elíjalo cuando
7.0 Apoyo a Plazo Estándar (STS) Necesitas las funciones más recientes del controlador y puedes actualizar siguiendo el ciclo de lanzamientos habitual.
6.1 Soporte técnico a largo plazo (LTS) Prefieres un periodo de soporte más largo y no necesitas que se introduzcan funciones en la 7.0.

Para las versiones actuales de parches, fechas de soporte, frameworks objetivo y compatibilidad con bases de datos, consulta el ciclo de vida del soporte de drivers de SqlClient.

Instala el paquete central

Ejecuta el siguiente comando desde el directorio que contiene tu archivo de proyecto:

dotnet add package Microsoft.Data.SqlClient

El comando selecciona la última versión estable compatible con el proyecto. Para fijar una versión para compilaciones reproducibles, especifica la versión:

dotnet add package Microsoft.Data.SqlClient --version <version>

Restaurar dependencias y construir el proyecto:

dotnet restore
dotnet build

Importa el espacio de nombres del controlador en C#:

using Microsoft.Data.SqlClient;

Para aplicaciones nuevas, no hagas referencia al paquete o espacio de nombres antiguo System.Data.SqlClient . Para actualizar una aplicación existente, consulte Migrar de System.Data.SqlClient a Microsoft. Data.SqlClient.

Instalación con Visual Studio

  1. En Explorador de soluciones, haz clic derecho en el proyecto y selecciona Gestionar paquetes NuGet.
  2. En la pestaña Explorar , busca Microsoft.Data.SqlClient.
  3. Selecciona el paquete que pertenece a Microsoft.
  4. Selecciona una versión estable compatible y luego selecciona Instalar.

Para más información, consulte Instalar y gestionar paquetes en Visual Studio.

Añadir paquetes opcionales

Instala paquetes opcionales solo cuando tu aplicación utilice la función relacionada.

Package Añádelo cuando
Microsoft.Data.SqlClient.Extensions.Azure Microsoft. Data.SqlClient 7.0 o posterior utiliza un modo de autenticación Microsoft Entra proporcionado por el controlador, como Active Directory Default, Active Directory Interactive, o Active Directory Managed Identity.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Always Encrypted almacena claves maestras de columna en Azure Key Vault.

Para la autenticación Microsoft Entra con SqlClient 7.0 o posterior, ejecuta:

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

El paquete de núcleo 7.0 ya no incluye dependencias de Azure Identity. A partir de la versión 7.0.2, el controlador principal y los paquetes complementarios utilizan versiones alineadas. Haz referencia a la misma versión de Microsoft.Data.SqlClient y Microsoft.Data.SqlClient.Extensions.Azure. Las aplicaciones que no usan autenticación Microsoft Entra proporcionada por el controlador no necesitan el paquete de extensiones de Azure. Para la configuración de autenticación, consulte la autenticación Microsoft Entra.

Actualizar el controlador

Antes de actualizar:

  1. Lee las novedades de Microsoft.Data.SqlClient y las notas de la versión originales de cada una de las versiones por las que pasa la actualización.

  2. Revisa las referencias directas y transitivas del paquete de la aplicación.

    dotnet list package --include-transitive

  3. Actualiza la referencia del paquete.

    dotnet add package Microsoft.Data.SqlClient --version <version>

  4. Restaura, compila y ejecuta las pruebas de la aplicación.

  5. Prueba el establecimiento de conexión, autenticación, validación de certificados, agrupación de conexiones, conversiones de tipos de datos, transacciones y comportamiento de reintentos contra cada destino de base de datos soportado.

Las versiones principales y los parches pueden requerir cambios en la aplicación. Por ejemplo, la versión 4.0 habilitó el cifrado de forma predeterminada, la versión 5.0 cambió SqlConnectionStringBuilder.Encrypt de bool a SqlConnectionEncryptOption, y la versión 7.0 trasladó la autenticación de Microsoft Entra proporcionada por el controlador a un paquete independiente.

A partir de la versión 7.0.2, las versiones ensambladoras de Microsoft.Data.SqlClient.Extensions.Azure, , y Microsoft.Data.SqlClient.Internal.Logging cambiaron de 1.0.0.0 a 7.0.0.0Microsoft.Data.SqlClient.Extensions.Abstractions. Las aplicaciones de .NET Framework deben volver a compilarse con los paquetes alineados o agregar redirecciones de ensamblado. Las aplicaciones en la versión actual de .NET no se ven afectadas por este cambio en la identidad del ensamblado.

Comprender los frameworks de objetivos

Microsoft. Data.SqlClient 7.0 soporta aplicaciones en:

  • .NET Framework 4.6.2 o posterior en Windows.
  • .NET 8 o versiones posteriores soportaban versiones de Windows, Linux y macOS.

El paquete NuGet también contiene un recurso de compatibilidad .NET Standard 2.0 para bibliotecas. Una aplicación ejecutable debe dirigirse a un entorno de ejecución compatible con el .NET Framework o .NET. Que una biblioteca tenga como destino .NET Standard no significa que todos los entornos de ejecución que la consumen sean compatibles.

El paquete restaura sus dependencias gestionadas y nativas a través de NuGet. No copies ensamblajes individuales de controladores ni bibliotecas nativas de la Interfaz de Red SQL (SNI) entre aplicaciones.

Preparar la implementación

  1. Publicar para el mismo sistema operativo y arquitectura que se usan en producción. Para una implementación que depende del entorno:

    dotnet publish --configuration Release

    Para un despliegue específico del entorno de ejecución:

    dotnet publish --configuration Release --runtime <runtime-identifier>

  2. Despliega la salida completa de publicación. No selecciones solo Microsoft.Data.SqlClient.dll.

  3. Confirma que el objetivo tiene el tiempo de ejecución .NET requerido, a menos que publiques una aplicación autónoma.

  4. Probar el resultado publicado en el sistema operativo y la arquitectura de destino.

  5. Prueba todos los modos de autenticación usados en producción. La autenticación integrada, Kerberos, los certificados, la identidad gestionada y el acceso a Azure Key Vault dependen del entorno de despliegue.

  6. Escanear el grafo de dependencias resueltas en busca de vulnerabilidades conocidas y actualizar las líneas de paquetes compatibles cuando haya correcciones disponibles.

No es compatible el modo de globalización invariable. Para las cualificaciones actuales de la plataforma, véase Sistemas operativos soportados.

Instalación de paquetes fuera de línea

Descarga el paquete y sus dependencias desde NuGet.org, cópialos a un código fuente interno y restaura desde ese código. Para compilaciones reproducibles sin conexión, fija las versiones de los paquetes y conserva el conjunto completo de dependencias.

Contenido relacionado

  • Last updated on