Introducción al espacio de nombres Microsoft.Data.SqlClient

Descargar ADO.NET

El espacio de nombres Microsoft.Data.SqlClient es básicamente una nueva versión del espacio de nombres System.Data.SqlClient. Microsoft.Data.SqlClient generalmente mantiene la misma API y la compatibilidad retroactiva con System.Data.SqlClient. Migrar de System.Data.SqlClient a Microsoft.Data.SqlClient es sencillo para la mayoría de las aplicaciones. Agregue una dependencia de NuGet en Microsoft.Data.SqlClient y actualice las referencias e instrucciones using a Microsoft.Data.SqlClient.

Hay algunas diferencias en las API menos usadas en comparación con System.Data.SqlClient que podrían afectar a algunas aplicaciones. Acerca de esas diferencias, consulte esta útil hoja de referencia rápida sobre portabilidad.

Referencia de API

Los detalles de la API Microsoft.Data.SqlClient se pueden encontrar en el explorador de la API de .NET.

Notas de la versión 7.0

Esta es la versión de disponibilidad general de Microsoft.Data.SqlClient 7.0, un hito importante para el proveedor de datos .NET para SQL Server. En esta versión se aborda el problema más votado en el historial del repositorio( al extraer las dependencias de Azure del paquete principal), se presenta la autenticación SSPI conectable, se agrega un enrutamiento mejorado para Azure y se proporcionan mejoras de rendimiento de lectura asincrónicas.

También se publicó como parte de este hito:

Publicado Microsoft.Data.SqlClient.Extensions.Abstractions 1.0.0. Consulte las notas de la versión.
Publicado Microsoft.Data.SqlClient.Extensions.Azure 1.0.0. Consulte las notas de la versión.
Publicada la versión 1.0.0 de Microsoft.Data.SqlClient.Internal.Logging. Consulte las notas de la versión.
Se ha publicado la nueva versión de Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider 7.0.0. Consulte las notas de la versión.

Cambios importantes en la versión 7.0

Dependencias de Azure eliminadas del paquete principal

Qué ha cambiado:

El paquete principal Microsoft.Data.SqlClient ya no depende de Azure.Core, Azure.Identityo de sus dependencias transitivas (por ejemplo, Microsoft.Identity.Client, Microsoft.Web.WebView2). La funcionalidad de autenticación de Azure Active Directory/Entra ID (ActiveDirectoryAuthenticationProvider y tipos relacionados) se ha extraído a un nuevo paquete Microsoft.Data.SqlClient.Extensions.Azure. (#1108, #3680, #3902, #3904, #3908, #3917, #3982, #3978, #3986)
Se presentan dos paquetes adicionales para admitir esta separación: Microsoft.Data.SqlClient.Extensions.Abstractions (tipos compartidos entre el controlador principal y las extensiones) y Microsoft.Data.SqlClient.Internal.Logging (infraestructura de seguimiento ETW compartida).
(3626, #3628, #3967, #4038)

Quién se beneficia:

Todos los usuarios se benefician de un paquete de núcleos significativamente más ligero. Anteriormente, la cadena de dependencias de Azure arrastró numerosos ensamblados incluso para aplicaciones que solo necesitaban conectividad básica de SQL Server. Este fue el problema abierto más votado en el repositorio.
Los usuarios que no usan la autenticación entra ID ya no llevan ensamblados relacionados con Azure en su salida de compilación.
Los usuarios que usan la autenticación entra ID ahora pueden administrar las versiones de dependencia de Azure independientemente del controlador principal.

Impacto:

Las aplicaciones que usan la autenticación de Id. de Entra (por ejemplo, ActiveDirectoryInteractive, ActiveDirectoryDefault, ActiveDirectoryManagedIdentity, etc.) ahora deben instalar el Microsoft.Data.SqlClient.Extensions.Azure paquete NuGet por separado:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure

No se requieren cambios de código más allá de agregar la referencia del paquete.
Si se usa un método de autenticación entra ID sin el paquete de Azure instalado, el controlador ahora proporciona un mensaje de error accionable que guía a los usuarios para instalar el paquete correcto.

Otros cambios importantes en la versión 7.0

Se revierte la visibilidad pública de las enumeraciones de interoperabilidad internas (IoControlCodeAccess y IoControlTransferType) que se hicieron públicas accidentalmente durante la fusión de proyectos. (3900)

Nuevas características de la versión 7.0

Autenticación conectable con SspiContextProvider

Qué ha cambiado:

Se agregó una propiedad pública SspiContextProvider en SqlConnection, completando el trabajo de extensibilidad de SSPI iniciado en la versión 6.1.0. Las aplicaciones ahora pueden proporcionar un proveedor de contexto SSPI personalizado para la autenticación integrada, lo que permite la negociación de tickets Kerberos personalizados y escenarios de autenticación de nombre de usuario y contraseña NTLM. (2253, #2494)

Quién se beneficia:

Los usuarios que se autentican entre dominios que no son de confianza, máquinas no unidas a un dominio o entornos multiplataforma en los que la configuración de la autenticación integrada es difícil.
Los usuarios que operan en contenedores y necesitan negociación manual de Kerberos sin implementar sidecars ni mecanismos externos de actualización de vales.
Usuarios que necesitan autenticación de nombre de usuario y contraseña NTLM en SQL Server, que el controlador no proporciona de forma nativa.

Impacto:

Las aplicaciones pueden establecer un SspiContextProvider personalizado en SqlConnection antes de abrir la conexión:

var connection = new SqlConnection(connectionString);
connection.SspiContextProvider = new MyKerberosProvider();
connection.Open();

El proveedor controla el intercambio de tokens de autenticación durante la autenticación integrada. El comportamiento de autenticación existente no cambia cuando no se establece ningún proveedor personalizado. Consulte SspiContextProvider_CustomProvider.cs para obtener una implementación de ejemplo.
Nota:SspiContextProvider es parte de la clave del grupo de conexiones. Asegúrese de que la implementación devuelve una identidad coherente por recurso.

Rendimiento de lectura asincrónica: multiplexación de paquetes (versión preliminar)

Qué ha cambiado:

Refinamiento continuo de multiplexación de paquetes con correcciones de errores y mejoras de estabilidad desde la versión 6.1.0, además de nuevos conmutadores de contexto de aplicación para control voluntario. (3534, #3537, #3605)

Quién se beneficia:

Aplicaciones que realizan lecturas asincrónicas grandes (ExecuteReaderAsync con grandes conjuntos de resultados, escenarios de streaming o recuperación masiva de datos).

Impacto:

La multiplexación de paquetes se implementa a través de dos interruptores de funciones opcionales.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);

Al establecer ambos interruptores en false, se habilita la nueva ruta de procesamiento asincrónica. De forma predeterminada, el controlador usa el comportamiento existente (compatible).

Compatibilidad mejorada con enrutamiento

Qué ha cambiado:

Se ha agregado compatibilidad con el enrutamiento mejorado, una característica de TDS que permite al servidor redirigir las conexiones a un servidor y una base de datos específicos durante el inicio de sesión. (3641, #3969, #3970, #3973)

Quién se beneficia:

Usuarios que se conectan a entornos de Azure que utilizan réplicas de lectura con nombre y equilibrio de carga basado en gateway.

Impacto:

El enrutamiento mejorado se negocia automáticamente durante el inicio de sesión cuando el servidor lo admite. No se requieren cambios en el código de la aplicación.

Compatibilidad con .NET 10

Qué ha cambiado:

Se han actualizado las canalizaciones y los conjuntos de pruebas para compilar el controlador mediante el SDK de .NET 10. (#3686)

Quién se beneficia:

Los desarrolladores que apuntan a .NET 10 desde el primer día.

Impacto:

SqlClient 7.0 compila y prueba en .NET 10, lo que garantiza la compatibilidad.

Eventos de diagnóstico fuertemente tipados en .NET Framework

Qué ha cambiado:

Habilitado SqlClientDiagnosticListener para SqlCommand en .NET Framework, cerrando una brecha de observabilidad de larga duración en la que los eventos de diagnóstico solo se emitían anteriormente en .NET Core. (3658)
Se incorporaron las 15 clases de eventos de diagnóstico fuertemente tipadas del Microsoft.Data.SqlClient.Diagnostics espacio de nombres (introducidas originalmente para .NET Core en 6.0) a .NET Framework como parte de la combinación del código base. Ambas plataformas ahora usan el mismo modelo de eventos fuertemente tipado. Los tipos cubren los eventos de comando, conexión y ciclo de vida de las transacciones:
- SqlClientCommandBefore, , SqlClientCommandAfter, SqlClientCommandError
- SqlClientConnectionOpenBefore, , SqlClientConnectionOpenAfter, SqlClientConnectionOpenError
- SqlClientConnectionCloseBefore, , SqlClientConnectionCloseAfter, SqlClientConnectionCloseError
- SqlClientTransactionCommitBefore, , SqlClientTransactionCommitAfter, SqlClientTransactionCommitError
- SqlClientTransactionRollbackBefore, , SqlClientTransactionRollbackAfter, SqlClientTransactionRollbackError
(3493)

Quién se beneficia:

Usuarios de .NET Framework que se suscriben a SqlClientDiagnosticListener eventos para la observabilidad, el seguimiento distribuido o la telemetría personalizada. Estos usuarios ahora tienen paridad con .NET Core, obteniendo IntelliSense, seguridad en tiempo de compilación y eliminando la necesidad de acceder a las cargas de diagnóstico a través de búsquedas de reflexión o diccionario.

Impacto:

En .NET Framework, SqlCommand ahora emite los mismos eventos de diagnóstico que solo estaban disponibles anteriormente en .NET Core. Los suscriptores a eventos DiagnosticListener (por ejemplo, Microsoft.Data.SqlClient.WriteCommandBefore) reciben objetos tipados estrictamente:

listener.Subscribe(new Observer<KeyValuePair<string, object?>>(kvp =>
{
    if (kvp.Value is SqlClientCommandBefore before)
    {
        Console.WriteLine($"Executing: {before.Command.CommandText}");
    }
}));

Los tipos implementan IReadOnlyList<KeyValuePair<string, object>> para garantizar la compatibilidad con versiones anteriores con código que itera sobre propiedades genéricamente.

Otras adiciones en la versión 7.0

Se ha agregado SqlConfigurableRetryFactory.BaselineTransientErrors la propiedad estática que expone la lista de códigos de error transitorios predeterminados como , ReadOnlyCollection<int>lo que facilita la extensión de la lista predeterminada con códigos de error específicos de la aplicación. (3903)
Se ha agregado el modificador Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault de contexto de la aplicación para establecer MultiSubnetFailover=true globalmente sin modificar las cadenas de conexión. (#3841)
Se ha agregado el cambio de contexto Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner de la aplicación para permitir que el cliente ignore la información del asociado de conmutación por error proporcionada por el servidor en los grupos de disponibilidad básica. (3625)
Extensión de características del Agente de usuario habilitada (participación a través de Switch.Microsoft.Data.SqlClient.EnableUserAgent). (3606)

Cambios en la versión 7.0

Desuso de `SqlAuthenticationMethod.ActiveDirectoryPassword`

Qué ha cambiado:

SqlAuthenticationMethod.ActiveDirectoryPassword (el flujo ROPC) ahora está marcado [Obsolete] y generará advertencias del compilador. Esto se alinea con el movimiento de Microsoft hacia la autenticación multifactor obligatoria. (#3671)

Quién se beneficia:

Los equipos se mueven hacia una autenticación más segura, sin contraseña o compatible con MFA.

Impacto:

Si usa Authentication=Active Directory Password, migre a una alternativa admitida:

Escenario	Autenticación recomendada
Aplicaciones interactivas o de escritorio	`Active Directory Interactive`
Servicio a servicio	`Active Directory Service Principal`
Cargas de trabajo hospedadas en Azure	`Active Directory Managed Identity`
Entornos de desarrollador/CI	`Active Directory Default`

Consulte Conexión a Azure SQL con autenticación de Microsoft Entra para obtener más información.

Soporte de la plataforma objetivo 7.0

.NET Framework 4.6.2+ (Windows x86, Windows x64, Windows ARM64)
.NET 8.0+ (Windows x86, Windows x64, Windows ARM, Windows ARM64, Linux, macOS)

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 7.0.

Notas de la versión 6.1

Nuevas características de la versión 6.1

Se ha agregado compatibilidad con tipos de datos vectoriales de SQL Server dedicados

Lo que ha cambiado:

Comunicaciones vectoriales optimizadas entre MDS y SQL Server 2025 (17.x), utilizando un formato binario personalizado sobre el protocolo TDS (3433, #3443).
Se ha reducido la carga de procesamiento en comparación con la compatibilidad existente con vectores basados en JSON.
Compatibilidad inicial con vectores de punto flotante de precisión única de 32 bits.

Quién se beneficia:

Las aplicaciones que mueven grandes conjuntos de datos vectoriales ven mejoras beneficiosas en los tiempos de procesamiento y los requisitos de memoria.
Las API específicas de vectores están listas para admitir representaciones numéricas futuras con una apariencia coherente.

Efecto:

Tiempos de transmisión y procesamiento reducidos para las operaciones vectoriales frente a JSON mediante SQL Server 2025 (17.x):
- Lecturas: Mejora de 50 veces
- Operaciones de escritura: mejora de aproximadamente 3,3 veces
- Copia masiva: mejora de 19 veces
- (Se observa con una columna vectorial de tamaño máximo de 1998 y 10 000 registros para cada operación).
Se ha mejorado la huella de memoria debido a la eliminación de la serialización/deserialización JSON y la sobrecarga en la representación de cadenas.
Para la compatibilidad hacia atrás con implementaciones anteriores de SQL Server Vector, las aplicaciones pueden seguir utilizando cadenas JSON para enviar o recibir datos vectoriales, aunque no ven ninguna de las mejoras de rendimiento mencionadas anteriormente.

Compatibilidad de destino de .NET Standard 2.0 revivida

Lo que ha cambiado:

Se ha devuelto la compatibilidad con .NET Standard 2.0 como destino (3381)
El soporte se quitó anteriormente en la versión 6.0, con la comunidad expresando preocupaciones.

Quién se beneficia:

Las bibliotecas que dependen de MDS podrían tener como destino sin problemas cualquiera de los marcos siguientes:
- .NET Standard 2.0
- .NET Framework 4.6.2 y versiones posteriores
- .NET 8.0
- .NET 9.0
Las aplicaciones deben seguir teniendo como destino los entornos de ejecución.
- La compatibilidad con la plataforma de destino de .NET Standard 2.0 de MDS no incluye una implementación real y no se puede usar con un entorno de ejecución.
- El proceso de compilación y publicación de una aplicación siempre debe elegir la implementación adecuada del entorno de ejecución de .NET/.NET Framework de MDS.
- No se admiten acciones de compilación o publicación personalizadas que intenten implementar incorrectamente el archivo DLL de referencia de .NET Standard 2.0 de MDS en tiempo de ejecución.

Efecto:

Las bibliotecas destinadas a .NET Standard 2.0 ya no reciben advertencias como:

warning NU1701: Package 'Microsoft.Data.SqlClient 6.0.2' was restored using '.NETFramework,Version=v4.6.1, .NETFramework,Version=v4.6.2, .NETFramework,Version=v4.7, .NETFramework,Version=v4.7.1, .NETFramework,Version=v4.7.2, .NETFramework,Version=v4.8, .NETFramework,Version=v4.8.1' instead of the project target framework '.NETStandard,Version=v2.0'. This package may not be fully compatible with your project.

Otras adiciones

Se ha agregado compatibilidad con mayúsculas y minúsculas especiales con puntos de conexión de Fabric. (3084)

Compatibilidad con la plataforma de destino 6.1

.NET Framework 4.6.2+ (Windows Arm64, Windows x86, Windows x64)
.NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 6.1.

Notas de la versión 6.0

Cambios importantes en la versión 6.0

Se ha eliminado el soporte para .NET Standard. #2386
Se eliminó la compatibilidad con .NET 6 #2927
Se eliminaron las referencias de UWP (UAP). #2483
Se eliminó el soporte para la depuración en el lado del cliente de SQL 2000 para la .NET Framework #2981, #2940

Nuevas características de la versión 6.0

Se ha agregado compatibilidad con el tipo de datos JSON #2916, #2892, #2891, #2880, #2882, #2829, #2830
Se ha agregado compatibilidad con .NET 9 #2946
Se ha agregado el tipo Microsoft.Data.SqlClient.Diagnostics.SqlClientDiagnostic en .NET. #2226
Se ha agregado el soporte para DateOnly y TimeOnly a DataTable como parámetro estructurado. #2258
Se ha agregado compatibilidad con SqlConnectionOverrides en OpenAsync() API #2433
Se agregó la localización en checo, polaco y turco #2987
Se ha agregado el objeto TokenCredential para beneficiarse del almacenamiento en caché de tokens en ActiveDirectoryAuthenticationProvider. #2380
Se agregó el archivo Léame al paquete NuGet #2826
Se habilitó la auditoría de paquetes NuGet a través del origen de auditoría NuGet.org #3024
Se ha agregado el ejemplo de código SqlCommand_BeginExecuteReader que faltaba #3009
Se agregó el seguimiento de ámbito para GenerateSspiClientContext. #2497, #2725

Compatibilidad con tipos de datos JSON

La compatibilidad con tipos de datos JSON ya está disponible en Microsoft.Data.SqlClient v6.0. En esta versión se presenta el tipo de SqlJson disponible como una extensión para System.Data.SqlDbTypes:

using System;
using System.Data.SqlTypes;
using System.Text.Json;

namespace Microsoft.Data.SqlTypes
{
    /// <summary>
    /// Represents the Json data type in SQL Server.
    /// </summary>
    public class SqlJson : INullable
    {
        /// <summary>
        /// Parameterless constructor. Initializes a new instance of the SqlJson class which
        /// represents a null JSON value.
        /// </summary>
        public SqlJson() { }

        /// <summary>
        /// Takes a <see cref="string"/> as input and initializes a new instance of the SqlJson class.
        /// </summary>
        /// <param name="jsonString"></param>
        public SqlJson(string jsonString) { }

        /// <summary>
        /// Takes a <see cref="JsonDocument"/> as input and initializes a new instance of the SqlJson class.
        /// </summary>
        /// <param name="jsonDoc"></param>
        public SqlJson(JsonDocument jsonDoc) { }

        /// <inheritdoc/>
        public bool IsNull => throw null;

        /// <summary>
        /// Represents a null instance of the <see cref="SqlJson"/> type.
        /// </summary>
        public static SqlJson Null { get { throw null; } }

        /// <summary>
        /// Gets the string representation of the JSON content of this <see cref="SqlJson" /> instance.
        /// </summary>
        public string Value { get ; }
    }
}

El tipo de datos JSON admite operaciones de lectura, escritura, streaming y copia masiva.

Introducción a SqlClientDiagnostics

Hay nuevos tipos disponibles en el Microsoft.Data.SqlClient.Diagnostics espacio de nombres que proporcionan una colección fuertemente tipada de pares clave-valor. Estos tipos se pueden capturar mediante el consumo de aplicaciones para recopilar eventos de diagnóstico emitidos por el controlador. Esta versión presenta los siguientes tipos:

SqlClientCommandBefore
SqlClientCommandAfter
SqlClientCommandError
SqlClientConnectionOpenBefore
SqlClientConnectionOpenAfter
SqlClientConnectionOpenError
SqlClientConnectionCloseBefore
SqlClientConnectionCloseAfter
SqlClientConnectionCloseError
SqlClientTransactionCommitBefore
SqlClientTransactionCommitAfter
SqlClientTransactionCommitError
SqlClientTransactionRollbackBefore
SqlClientTransactionRollbackAfter
SqlClientTransactionRollbackError

Se agregó compatibilidad con invalidaciones de conexión en la API OpenAsync()

El comportamiento predeterminado de SqlConnection.OpenAsync() se puede invalidar para deshabilitar el retraso de diez segundos y los reintentos de conexión automáticos desencadenados por errores transitorios.

using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"))
{
    await sqlConnection.OpenAsync(SqlConnectionOverrides.OpenWithoutRetry, cancellationToken);
}

Soporte para la plataforma objetivo 6.0

.NET Framework 4.6.2+ (Windows x86, Windows x64)
.NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Las notas completas de la versión 6.0, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la Versión 6.0.

Notas de la versión 5.2

Nuevas características de la versión 5.2

Se ha agregado compatibilidad con SqlDiagnosticListener en .NET Standard. #1931
Se ha agregado la nueva propiedad RowsCopied64 a SqlBulkCopy. N.º 2004 Más información
Se ha agregado una nueva API AccessTokenCallBack a SqlConnection. N.º 1260 Más información
Se ha agregado compatibilidad con la opción de registro SuperSocketNetLib para cifrar en .NET en Windows. #2047
Se ha agregado compatibilidad de SqlBatch con .NET 6+ n.º 1825, n.º 2223 Más información
Se ha agregado compatibilidad con la autenticación de identidad de cargas de trabajo #2159, #2264
Se ha agregado compatibilidad de localización en .NET #2210
Se ha agregado compatibilidad con la intercalación georgiana #2194
Se ha agregado compatibilidad con sistemas Big Endian #2170
Se ha agregado compatibilidad con .NET 8 #2230
Se ha agregado una versión explícita para las principales dependencias de la versión de .NET en System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0 y System.Diagnostics.DiagnosticSource 8.0.0 #2303
Se ha añadido la habilidad para generar símbolos de depuración en un archivo de paquete independiente #2137

Se ha agregado una nueva propiedad `RowsCopied64` a SqlBulkCopy

SqlBulkCopy tiene una nueva propiedad RowsCopied64 que admite long tipos de valor.

El comportamiento existente SqlBulkCopy.RowsCopied no cambia. Cuando el valor supera int.MaxValue, RowsCopied puede devolver un número negativo.

Ejemplo de uso:

    using (SqlConnection srcConn = new SqlConnection(srcConstr))
    using (SqlCommand srcCmd = new SqlCommand("select top 5 * from employees", srcConn))
    {
        srcConn.Open();
        using (DbDataReader reader = srcCmd.ExecuteReader())
        {
            using (SqlBulkCopy bulkcopy = new SqlBulkCopy(dstConn))
            {
                bulkcopy.DestinationTableName = dstTable;
                SqlBulkCopyColumnMappingCollection ColumnMappings = bulkcopy.ColumnMappings;

                ColumnMappings.Add("EmployeeID", "col1");
                ColumnMappings.Add("LastName", "col2");
                ColumnMappings.Add("FirstName", "col3");

                bulkcopy.WriteToServer(reader);
                long rowsCopied = bulkcopy.RowsCopied64;
            }
        }
    }

Se ha agregado una nueva propiedad `AccessTokenCallBack` a SqlConnection

SqlConnection admite la autenticación TokenCredential mediante la introducción de una nueva propiedad AccessTokenCallBack como un delegado Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>> para devolver un token de acceso de autenticación federada.

Ejemplo de uso:

using Microsoft.Data.SqlClient;
using Azure.Identity;

const string defaultScopeSuffix = "/.default";
string connectionString = GetConnectionString();
DefaultAzureCredential credential = new();
using SqlConnection connection = new(connectionString);

connection.AccessTokenCallback = async (authParams, cancellationToken) =>
{
    string scope = authParams.Resource.EndsWith(defaultScopeSuffix)
        ? authParams.Resource
        : $"{authParams.Resource}{defaultScopeSuffix}";
    AccessToken token = await credential.GetTokenAsync(
        new TokenRequestContext([scope]),
        cancellationToken);

    return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
}

connection.Open();
Console.WriteLine("ServerVersion: {0}", connection.ServerVersion);
Console.WriteLine("State: {0}", connection.State);

API SqlBatch

Ejemplo de uso:

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        string str = "Data Source=(local);Initial Catalog=Northwind;"
        + "Integrated Security=SSPI;Encrypt=False";
        RunBatch(str);
    }

    static void RunBatch(string connString)
    {
        using var connection = new SqlConnection(connString);
        connection.Open();

        var batch = new SqlBatch(connection);

        const int count = 10;
        const string parameterName = "parameter";
        for (int i = 0; i < count; i++)
        {
            var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
            batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
            batch.BatchCommands.Add(batchCommand);
        }

        // Optionally Prepare
        batch.Prepare();

        var results = new List<int>(count);
        using (SqlDataReader reader = batch.ExecuteReader())
        {
            do
            {
                while (reader.Read())
                {
                    results.Add(reader.GetFieldValue<int>(0));
                }
            } while (reader.NextResult());
        }
        Console.WriteLine(string.Join(", ", results));
    }
}

5.2 Compatibilidad con la plataforma de destino

.NET Framework 4.6.2+ (Windows x86, Windows x64)
.NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Las notas de la versión completas, incluidas las dependencias, están disponibles en el repositorio de GitHub de las notas de la versión 5.2.

Notas de la versión 5.1

Cambios importantes en la versión 5.1

Se ha eliminado la compatibilidad con .NET Core 3.1. N.º 1704 N.º 1823

Nuevas características de la versión 5.1

Se ha agregado compatibilidad con DateOnly y TimeOnly para el valor de SqlParameter y GetFieldValue. #1813
Se ha agregado compatibilidad con TLS 1.3 para .NET Core y SNI Native. #1821
Se ha agregado la configuración de ServerCertificate para Encrypt=Mandatory o Encrypt=Strict. N.º 1822 Más información
Se ha agregado compatibilidad con Windows Arm64 al tener como destino .NET Framework. #1828

Certificado de servidor

El valor predeterminado de la configuración de conexión de ServerCertificate es una cadena vacía. Cuando se establece Encrypt en Mandatory o Strict, se puede usar ServerCertificate para especificar una ruta de acceso en el sistema de archivos a un archivo de certificado para coincidir con el certificado TLS/SSL del servidor. El certificado especificado debe ser una coincidencia exacta para que sea válido. Los formatos de certificado permitidos son PEM, DER y CER. Presentamos un ejemplo de uso:

"Data Source=...;Encrypt=Strict;ServerCertificate=C:\\certificates\\server.cer"

5.1 Compatibilidad con la plataforma de destino

.NET Framework 4.6.2+ (Windows x86, Windows x64)
.NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Azure Resource Manager, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Las notas de la versión completas, incluidas las dependencias, están disponibles en el repositorio de GitHub de las notas de la versión 5.1.

Notas de la versión 5.0

Cambios importantes en la versión 5.0

Se ha quitado la compatibilidad con .NET Framework 4.6.1. #1574.
Se ha agregado una dependencia en el paquete Microsoft.SqlServer.Server. Esta nueva dependencia puede provocar conflictos de espacio de nombres si la aplicación hace referencia a ese espacio de nombres y todavía tiene referencias de paquete (directas o indirectas) a System.Data.SqlClient desde .NET Core.
Se han quitado las clases del espacio de nombres Microsoft.Data.SqlClient.Server y se han reemplazado por tipos admitidos del paquete Microsoft.SqlServer.Server. #1585. Las clases y enumeraciones afectadas son:
- Microsoft.Data.SqlClient.Server.IBinarySerialize:> Microsoft.SqlServer.Server.IBinarySerialize
- Microsoft.Data.SqlClient.Server.InvalidUdtException:> Microsoft.SqlServer.Server.InvalidUdtException
- Microsoft.Data.SqlClient.Server.SqlFacetAttribute:> Microsoft.SqlServer.Server.SqlFacetAttribute
- Microsoft.Data.SqlClient.Server.SqlFunctionAttribute:> Microsoft.SqlServer.Server.SqlFunctionAttribute
- Microsoft.Data.SqlClient.Server.SqlMethodAttribute-> Microsoft.SqlServer.Server.SqlMethodAttribute
- Microsoft.Data.SqlClient.Server.SqlUserDefinedAggregateAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute
- Microsoft.Data.SqlClient.Server.SqlUserDefinedTypeAttribute:> Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute
- (enumeración) Microsoft.Data.SqlClient.Server.DataAccessKind-> Microsoft.SqlServer.Server.DataAccessKind
- (enumeración) Microsoft.Data.SqlClient.Server.Format:> Microsoft.SqlServer.Server.Format
- (enumeración) Microsoft.Data.SqlClient.Server.SystemDataAccessKind-> Microsoft.SqlServer.Server.SystemDataAccessKind

Nuevas características de la versión 5.0

Se ha agregado compatibilidad con TDS8. Para usar TDS 8, los usuarios deben especificar Encrypt=Strict en la cadena de conexión. N.º 1608 Más información
Se ha agregado soporte para especificar el SPN del servidor y el SPN del servidor de respaldo en la conexión. N.º 1607 Más información
Se ha agregado compatibilidad con alias al establecer .NET Core en Windows como destino. N.º 1588 Más información
Se ha agregado SqlDataSourceEnumerator. #1430. Más información
Se ha agregado un nuevo conmutador AppContext para suprimir las advertencias de TLS inseguras. #1457. Más información

Seguridad mejorada de TDS 8.0

Para usar TDS 8.0, especifique Encrypt=Strict en la cadena de conexión. El modo strict deshabilita TrustServerCertificate (tratado siempre como False en el modo strict). Se ha agregado HostNameInCertificate para ayudar en algunos escenarios del modo strict. TDS 8.0 comienza y continúa toda la comunicación del servidor dentro de una conexión TLS segura y cifrada.

Se han agregado nuevos valores de Encrypt para aclarar el comportamiento del cifrado de la conexión. Encrypt=Mandatory equivale a Encrypt=True y cifra las conexiones durante la negociación de la conexión TDS. Encrypt=Optional equivale a Encrypt=False y solo cifra la conexión si el servidor indica al cliente que el cifrado es necesario durante la negociación de la conexión de TDS.

Para obtener más información sobre el cifrado de conexiones al servidor, consulte Cifrado y validación de certificados en Microsoft.Data.SqlClient.

HostNameInCertificate se puede especificar en la cadena de conexión cuando se usan alias para conectarse con cifrado a un servidor que tenga un certificado de servidor con un nombre diferente o un nombre de sujeto alternativo al nombre usado por el cliente para identificar el servidor (alias DNS, por ejemplo). Ejemplo de uso: HostNameInCertificate=MyDnsAliasName

SPN del servidor

Al conectarse en un entorno que tiene una topografía de dominio/bosque única, es posible que tenga requisitos específicos para los SPN de servidor. La configuración de las cadenas de conexión ServerSPN/SPN del servidor y FailoverServerSPN/SPN de conmutación por error del servidor puede utilizarse para invalidar los SPN de servidor generados automáticamente que se emplean durante la autenticación integrada en un entorno de dominio.

Compatibilidad con alias de SQL

Los usuarios pueden configurar alias con el Administrador de configuración de SQL Server. Estos alias se almacenan en el Registro de Windows y ya se admiten cuando el destino es .NET Framework. Esta versión ofrece compatibilidad con alias cuando se establecen .NET o .NET Core en Windows como destino.

Compatibilidad con el enumerador de orígenes de datos SQL

Proporciona un mecanismo para enumerar todas las instancias disponibles de SQL Server incluidas en la red local.

using Microsoft.Data.Sql;
static void Main()
  {
    // Retrieve the enumerator instance and then the data.
    SqlDataSourceEnumerator instance =
      SqlDataSourceEnumerator.Instance;
    System.Data.DataTable table = instance.GetDataSources();

    // Display the contents of the table.
    DisplayData(table);

    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
  }

  private static void DisplayData(System.Data.DataTable table)
  {
    foreach (System.Data.DataRow row in table.Rows)
    {
      foreach (System.Data.DataColumn col in table.Columns)
      {
        Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);
      }
      Console.WriteLine("============================");
    }
  }

Supresión de advertencias de TLS no seguro

Cuando se usa una versión de TLS inferior a la 1.2 para negociar con el servidor, se muestra una advertencia de seguridad en la consola. Esta advertencia se puede suprimir en la conexión SQL durante Encrypt = false al habilitar el interruptor de AppContext correspondiente al inicio de la aplicación.

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

Soporte para la plataforma de destino 5.0

.NET Framework 4.6.2+ (Windows x86, Windows x64)
.NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Las notas de la versión completas, incluidas las dependencias, están disponibles en el repositorio de GitHub de las notas de la versión 5.0.

Notas de la versión 4.1

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 4.1.

Nuevas características de la versión 4.1

Introducir el protocolo de atestación Ninguno

Se permite un nuevo protocolo de atestación denominado None en la cadena de conexión. Este protocolo permite a los usuarios prescindir de la atestación de enclaves para los enclaves VBS. Cuando se establece este protocolo, la propiedad URL de atestación de enclave es opcional.

Ejemplo de cadena de conexión:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

4.1 Compatibilidad con la plataforma de destino

.NET Framework 4.6.1+ (Windows x86, Windows x64)
.NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Notas de la versión 4.0

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 4.0.

Cambios importantes en la versión 4.0

Se ha cambiado la propiedad existente de cadena de conexión Encrypt a true de manera predeterminada. N.º 1210 Más información
El controlador ahora lanza SqlException reemplazando AggregateException para los modos de autenticación de Active Directory. N.º 1213
Se ha eliminado la propiedad de conexión Asynchronous Processing obsoleta de .NET Framework. N.º 1148
Se ha quitado el conmutador de seguridad Configurable Retry Logic. N.º 1254 Más información
Se ha eliminado la compatibilidad con .NET Core 2.1 N.º 1272.
[.NET Framework] No se produce una excepción si se proporciona un identificador de usuario en la cadena de conexión cuando se usa la autenticación de Active Directory Integrated#1359

Nuevas características de la versión 4.0

El valor predeterminado del cifrado está establecido en verdadero.

El valor predeterminado de la configuración de conexión Encrypt se ha cambiado de false a true. Con el creciente uso de bases de datos en la nube y la necesidad de asegurarse de que esas conexiones son seguras, es el momento de este cambio importante en la compatibilidad con versiones anteriores.

Asegurarse de que las conexiones no se pueden realizar cuando se requiere cifrado

En escenarios en los que las bibliotecas de cifrado de cliente estaban deshabilitadas o no estaban disponibles, era posible realizar conexiones sin cifrar cuando Encrypt se estableció en true o el servidor requería cifrado.

Cambio de contexto de aplicación para usar los protocolos predeterminados del sistema

El controlador no admite TLS 1.3; por tanto, se ha quitado de la lista de protocolos admitidos de forma predeterminada. Los usuarios pueden volver a forzar el uso de los protocolos de cliente del sistema operativo, habilitando el cambio de contexto de aplicación a continuación:

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Habilitación del enlace de parámetros optimizados

Microsoft.Data.SqlClient presenta una nueva API SqlCommand, EnableOptimizedParameterBinding, para mejorar el rendimiento de las consultas con un gran número de parámetros. Esta propiedad está deshabilitada de forma predeterminada. Si se establece en true, los nombres de parámetro no se envían a la instancia de SQL Server cuando se ejecuta el comando.

public class SqlCommand
{
    public bool EnableOptimizedParameterBinding { get; set; }
}

Eliminar el interruptor de seguridad de lógica de reintentos configurable

El cambio de contexto de aplicación "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" ya no es necesario para usar la característica lógica de reintento configurable. La característica ahora es compatible en producción. El comportamiento predeterminado de la característica seguirá siendo una directiva sin reintentos, que las aplicaciones cliente tendrán que invalidar para habilitar los reintentos.

Compatibilidad con instancias compartidas de SqlLocalDb

Ahora se admiten instancias compartidas de SqlLocalDb cuando se usa SNI administrado.

Escenarios posibles:
- (localdb)\. (se conecta a la instancia predeterminada de SqlLocalDb)
- (localdb)\<named instance>
- (localdb)\.\<shared instance name> (*compatibilidad recién agregada)

Compatibilidad con `GetFieldValueAsync<T>` y `GetFieldValue<T>` para los tipos `XmlReader`, `TextReader`, `Stream`

Ahora se admiten los tipos XmlReader, TextReader, Stream al usar GetFieldValueAsync<T> y GetFieldValue<T>.

Ejemplo de uso:

using (SqlConnection connection = new SqlConnection(connectionString))
{
    using (SqlCommand command = new SqlCommand(query, connection))
    {
        connection.Open();
        using (SqlDataReader reader = await command.ExecuteReaderAsync())
        {
            if (await reader.ReadAsync())
            {
                using (Stream stream = await reader.GetFieldValueAsync<Stream>(1))
                {
                    // Continue to read from stream
                }
            }
        }
    }
}

Compatibilidad con la plataforma de destino 4.0

.NET Framework 4.6.1+ (Windows x86, Windows x64)
.NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Notas de la versión 3.1

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 3.1.

Nuevas características de la versión 3.1

Se introdujo el protocolo de atestación 'None'.

Se permitirá un nuevo protocolo de atestación llamado None en la cadena de conexión. Este protocolo permitirá a los usuarios renunciar a la atestación de enclave para los enclaves VBS. Cuando se establece este protocolo, la propiedad URL de atestación de enclave es opcional.

Ejemplo de cadena de conexión:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

Compatibilidad con la plataforma de destino

.NET Framework 4.6.1+ (Windows x86, Windows x64)
.NET Core 3.1+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)

Notas de la versión 3.0

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 3.0.

Cambios importantes en la versión 3.0

La versión de .NET Framework mínima admitida ha aumentado a v4.6.1. .NET Framework v4.6.0 ya no se admite. N.º 899.
La propiedad de conexión User Id ahora requiere Client Id en lugar de Object Id para la identidad administrada asignada por el usuario. N.º 1010. Más información.
SqlDataReader ahora devuelve un valor DBNull en lugar de un byte[] vacío. El comportamiento heredado se puede habilitar estableciendo AppContextswitch Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998 Más información.

Nuevas características de la versión 3.0

Lógica de reintento configurable

Esta nueva función introduce soporte configurable para que las aplicaciones cliente puedan volver a intentar en caso de errores "transitorios" o "reintentables". La configuración se puede realizar mediante archivos de configuración de aplicación o código y se pueden aplicar operaciones de reintento para abrir una conexión o ejecutar un comando. Esta característica está deshabilitada de forma predeterminada y se encuentra actualmente en versión preliminar. Para habilitar esta compatibilidad, las aplicaciones cliente deben activar el siguiente interruptor de seguridad:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);

Una vez que se ha habilitado el modificador AppContext de .NET, se puede definir una directiva lógica de reintentos para SqlConnection y SqlCommand de forma independiente, o en conjunto mediante varias opciones de personalización.

Se han introducido nuevas API públicas en SqlConnection y SqlCommand para registrar una implementación de SqlRetryLogicBaseProvider personalizada:

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Aquí encontrará ejemplos de uso de API: .

using Microsoft.Data.SqlClient;

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.
class RetryLogicSample
{
    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1)
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report the execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not a good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open the general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is being created and other services are going to connect to it.
            RetryConnection(provider);
        }
        catch
        {
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void RetryConnection(SqlRetryLogicBaseProvider provider)
    {
        // Change this if you already have a database with the same name in your database.
        string dbName = "Invalid_DB_Open";

        // Create a connection to an invalid database.
        using var cnn = new SqlConnection(string.Format(CnnStringFormat, dbName));
        // 3. Assign the `provider` to the connection
        cnn.RetryLogicProvider = provider;
        Console.WriteLine($"Connecting to the [{dbName}] ...");
        // Manually execute the following command in SSMS to create the invalid database while the SqlConnection is attempting to connect to it.
        // >> CREATE DATABASE Invalid_DB_Open;
        Console.WriteLine($"Manually, run the 'CREATE DATABASE {dbName};' in the SQL Server before exceeding the {provider.RetryLogic.NumberOfTries} attempts.");
        // the connection tries to connect to the database 5 times
        Console.WriteLine("The first attempt, before getting into the retry logic.");
        cnn.Open();
        Console.WriteLine($"Connected to the [{dbName}] successfully.");

        cnn.Close();

        // Drop it after test
        ExecuteCommand(s_generalConnection, string.Format(DropDatabaseFormat, dbName));
        Console.WriteLine($"The [{dbName}] is removed.");
    }
}

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.

    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";
    private const string CreateDatabaseFormat = "CREATE DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1),
            AuthorizedSqlCondition = null,
            // error number 3702 : Cannot drop database "xxx" because it is currently in use.
            TransientErrors = new int[] {3702}
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open a general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is creating and other services are going to connect to it.
            RetryCommand(provider);
        }
        catch
        {
            s_generalConnection.Close();
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
        s_generalConnection.Close();
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void FindActiveSessions(SqlConnection cnn, string dbName)
    {
        using var cmd = cnn.CreateCommand();
        cmd.CommandText = "DECLARE @query NVARCHAR(max) = '';" + Environment.NewLine +
            $"SELECT @query = @query + 'KILL ' + CAST(spid as varchar(50)) + ';' FROM sys.sysprocesses WHERE dbid = DB_ID('{dbName}')" + Environment.NewLine +
            "SELECT @query AS Active_sessions;";
        var reader = cmd.ExecuteReader();
        if (reader.Read())
        {
            Console.ForegroundColor = ConsoleColor.Green;
            Console.Write($">> Execute the '{reader.GetString(0)}' command in SQL Server to unblock the running task.");
            Console.ResetColor();
        }
        reader.Close();
    }

var RetryLogicOption = new SqlRetryLogicOption()
{
    NumberOfTries = 5,
    // Declare the error number 102 as a transient error to apply the retry logic when it occurs.
    TransientErrors = new int[] { 102 },
    // When a SqlCommand executes out of a transaction, 
    // the retry logic will apply if it contains a 'select' keyword.
    AuthorizedSqlCondition = x => string.IsNullOrEmpty(x)
            || Regex.IsMatch(x, @"\b(SELECT)\b", RegexOptions.IgnoreCase),
    DeltaTime = TimeSpan.FromSeconds(1),
    MaxTimeInterval = TimeSpan.FromSeconds(60),
    MinTimeInterval = TimeSpan.FromSeconds(3)
};

También se han introducido nuevas secciones de configuración para realizar el mismo registro desde los archivos de configuración, sin necesidad de modificar el código existente:

<section name="SqlConfigurableRetryLogicConnection"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>

<section name="SqlConfigurableRetryLogicCommand"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

Este es un ejemplo sencillo del uso de las nuevas secciones de configuración en los archivos de configuración:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="SqlConfigurableRetryLogicConnection"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>
    <section name="SqlConfigurableRetryLogicCommand"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

    <section name="AppContextSwitchOverrides"
             type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/>
  </configSections>

  <!--Enable safety switch in .NET Core-->
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>

  <!--Retry method for SqlConnection-->
  <SqlConfigurableRetryLogicConnection retryMethod ="CreateFixedRetryProvider" numberOfTries ="3" deltaTime ="00:00:10" maxTime ="00:00:30"
                                    transientErrors="40615" />

  <!--Retry method for SqlCommand containing SELECT queries-->
  <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider" numberOfTries ="5" deltaTime ="00:00:10" maxTime ="00:01:10"
                                    authorizedSqlCondition="\b(SELECT)\b" transientErrors="102, 4060, 0"/>
</configuration>

Como alternativa, las aplicaciones pueden implementar su propio proveedor de la clase base SqlRetryLogicBaseProvider y registrarlo con SqlConnection/SqlCommand.

Contadores de eventos

Ahora están disponibles los siguientes contadores para las aplicaciones que tienen como destino .NET Core 3.1+ y .NET Standard 2.1+:

NOMBRE	Nombre para mostrar	Descripción
conexiones-activas-rígidas	Conexiones activas reales realizadas actualmente a servidores	Número de conexiones que están abiertas actualmente a servidores de bases de datos.
conexiones físicas	Velocidad de conexión real a los servidores	Número de conexiones por segundo que se abren a servidores de bases de datos.
desconexiones forzadas	Velocidad de desconexión real de los servidores	Número de desconexiones por segundo que se producen con servidores de bases de datos.
conexiones-activas-suaves	Conexiones activas recuperadas del grupo de conexiones	Número de conexiones ya abiertas que se consumen desde el grupo de conexiones.
soft-connects	Velocidad de las conexiones recuperadas del grupo de conexiones	Número de conexiones por segundo que se consumen desde el grupo de conexiones.
desconexiones suaves	Tasa de conexiones devueltas al grupo de conexiones	Número de conexiones por segundo que se devuelven al grupo de conexiones.
número-de-conexiones-no-agrupadas	Número de conexiones que no usan la agrupación de conexiones	Número de conexiones activas que no están agrupadas.
number-of-pooled-connections	Número de conexiones administradas por el grupo de conexiones	El número de conexiones activas gestionó la infraestructura de agrupación de conexiones.
número-de-grupos-activos-de-grupos-de-conexión-en-piscina	Número de cadenas de conexión únicas activas	Número de grupos de conexiones activos y únicos. Este contador depende del número de cadenas de conexión única que haya en el dominio de aplicación.
número-de-grupos-inactivos-del-pool-de-conexiones	Número de cadenas de conexión únicas a la espera de ser eliminadas	El número de conjuntos de grupos de conexiones únicas marcados para ser eliminados. Este contador depende del número de cadenas de conexión única que haya en el dominio de aplicación.
número-de-grupos-de-conexión-activos	Número de grupos de conexiones activas	El número total de grupos de conexiones.
número-de-pools-de-conexiones-inactivas	Número de grupos de conexiones inactivas	Número de grupos de conexiones inactivas sin actividad reciente y en espera de ser eliminadas.
número-de-conexiones-activas	Número de conexiones activas	Número de conexiones actualmente en uso.
número-de-conexiones-gratuitas	Número de conexiones listas en el grupo de conexiones	Número de conexiones abiertas que se pueden usar en los grupos de conexiones.
número-de-conexiones-de-estasis	Número de conexiones actualmente a la espera de estar listas	Número de conexiones actualmente a la espera de la finalización de una acción y que no están disponibles para su uso por parte de la aplicación.
número-de-conexiones-recuperadas	Número de conexiones reclamadas desde GC	Número de conexiones reclamadas mediante la recolección de basura en las que la aplicación no llamó a `Close` ni a `Dispose`. Nota: No cerrar o eliminar explícitamente las conexiones afecta el rendimiento.

Estos contadores se pueden usar con las herramientas de la CLI global de .NET Core: dotnet-counters y dotnet-trace en Windows o Linux y PerfView en Windows, con Microsoft.Data.SqlClient.EventSource como nombre del proveedor. Para obtener más información, vea Recuperación de valores del contador de eventos.

dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p
PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 collect

Introducción a la dependencia de Azure Identity

Microsoft.Data.SqlClient ahora depende de la biblioteca Azure.Identity para adquirir tokens para los modos de autenticación "Identidad administrada de Active Directory/MSI" y "Entidad de servicio de Active Directory". Este cambio conlleva los cambios siguientes en el área expuesta pública:

Cambio importante

La propiedad de conexión "User ID" ahora requiere "Client ID" en lugar de "Object ID" para la "Identidad administrada asignada por el usuario".
API pública

Nueva propiedad pública de solo lectura: SqlAuthenticationParameters.ConnectionTimeout
Dependencia

Azure.Identity v1.3.0

Mejoras de seguimiento de eventos en SNI.dll

Las versiones de Microsoft.Data.SqlClient.SNI (dependencia de .NET Framework) y Microsoft.Data.SqlClient.SNI.runtime (dependencia de .NET Core/Standard) se han actualizado a v3.0.0-preview1.21104.2. El seguimiento de eventos en SNI.dll ya no se habilita mediante una aplicación cliente. Basta con la suscripción de una sesión al proveedor Microsoft.Data.SqlClient.EventSource mediante herramientas como xperf o perfview. Para obtener más información, vea Compatibilidad con el seguimiento de eventos en SNI nativo.

Habilitar el comportamiento nulo de la versión de fila

SqlDataReader devuelve un valor DBNull en lugar de un byte[] vacío. Para habilitar el comportamiento heredado, debe habilitar el siguiente modificador de AppContext al iniciar la aplicación: "Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior" .

Compatibilidad con la autenticación predeterminada de Microsoft Entra

Nota:

Aunque Microsoft Entra ID es el nuevo nombre de Azure Active Directory (Azure AD), para evitar interrumpir los entornos existentes, Azure AD sigue estando en algunos elementos codificados de forma rígida como campos de interfaz de usuario, proveedores de conexiones, códigos de error y cmdlets. En este artículo, los dos nombres son intercambiables.

Esta PR introduce un nuevo método de autenticación SQL: Active Directory Default. Este modo de autenticación amplía las posibilidades de autenticación de usuario con microsoft Entra ID, ampliando las soluciones de inicio de sesión al entorno de cliente, Visual Studio Code, Visual Studio, la CLI de Azure, etc.

Con este modo de autenticación, el controlador adquiere un token al pasar "DefaultAzureCredential" desde la biblioteca Azure Identity para adquirir un token de acceso. Este modo intenta usar estos tipos de credenciales para adquirir un token de acceso en el orden siguiente:

EnvironmentCredential
- Habilita la autenticación con Microsoft Entra ID usando cliente y secreto, o nombre de usuario y contraseña, con los detalles configurados en las siguientes variables de entorno: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (más información)
ManagedIdentityCredential
- Intenta la autenticación de Microsoft Entra ID mediante una identidad administrada que se ha asignado al entorno de implementación. El "Id. de cliente" de la "identidad administrada asignada por el usuario" se lee desde la propiedad de conexión "Id. de usuario".
SharedTokenCacheCredential
- Realiza la autenticación mediante tokens en la caché local compartida entre aplicaciones de Microsoft.
VisualStudioCredential
- Permite la autenticación con Microsoft Entra ID mediante los datos de Visual Studio
VisualStudioCodeCredential
- Permite la autenticación con Microsoft Entra ID mediante los datos de Visual Studio Code.
AzureCliCredential
- Habilita la autenticación con Microsoft Entra ID mediante la CLI de Azure para obtener un token de acceso.

InteractiveBrowserCredential está deshabilitado en la implementación del controlador de "Valor predeterminado de Active Directory", y "Active Directory interactivo" es la única opción disponible para adquirir un token mediante MFA o la autenticación interactiva.

Las opciones de personalización adicionales no están disponibles en este momento.

Mejoras en la funcionalidad del registro de proveedores personalizados de almacenamiento de claves maestras

Microsoft.Data.SqlClient ahora ofrece más control sobre el acceso a los proveedores de almacenamiento de claves maestras en una aplicación para brindar mejor soporte a las aplicaciones de multitenencia y su uso del cifrado y descifrado de columnas. Se han introducido las API siguientes para permitir el registro de proveedores personalizados de almacén de claves maestras en instancias de SqlConnection y SqlCommand:

public class SqlConnection
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}
public class SqlCommand
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnCommand(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}

Se sigue admitiendo la API estática en SqlConnection (SqlConnection.RegisterColumnEncryptionKeyStoreProviders) para registrar globalmente proveedores personalizados de almacenamiento de claves maestras. La caché de claves de cifrado de columnas mantenida globalmente solo se aplica a los proveedores registrados globalmente.

Precedencia en el registro de proveedores de almacenamiento de claves maestras por columna

Los proveedores integrados del almacén de claves maestras de columnas disponibles para el Almacén de certificados de Windows, el almacén CNG y el CSP están preregistrados. No se debe registrar ningún proveedor en las instancias de conexión o de comando si se necesita uno de los proveedores integrados para el almacenamiento de claves maestras de columna.

Los proveedores personalizados de almacén de claves maestras se pueden registrar con el controlador en tres niveles diferentes. El nivel global es tal como está actualmente. Los nuevos registros de nivel por conexión y por comando están vacíos inicialmente y se pueden establecer más de una vez.

Las precedencias de los tres registros son las siguientes:

El registro por comando se comprueba si no está vacío.
Si el registro por comando está vacío, el registro por conexión se comprueba si no está vacío.
Si el registro por conexión está vacío, se comprueba el registro global.

Una vez que se encuentra cualquier proveedor de almacén de claves en un nivel de registro, el controlador no vuelve a los demás registros para buscar un proveedor. Si los proveedores están registrados, pero no se encuentra el proveedor adecuado en un nivel, se produce una excepción que contiene únicamente los proveedores registrados en el registro comprobado.

Precedencia de la caché de claves para el cifrado de columnas

El controlador no almacena en caché las claves de cifrado de columna (CEK) de los proveedores personalizados de almacén de claves registrados con las nuevas API de nivel de instancia. Los proveedores de almacén de claves deben implementar su propia memoria caché para aumentar el rendimiento. El controlador deshabilita esta caché local de claves de cifrado de columna implementadas por los proveedores personalizados de almacén de claves si la instancia del proveedor de almacén de claves está registrada en el controlador en el nivel global.

También se ha introducido una nueva API en la clase base SqlColumnEncryptionKeyStoreProvider para establecer el período de vida de la caché:

public abstract class SqlColumnEncryptionKeyStoreProvider
{
    // The default value of Column Encryption Key Cache Time to Live is 0.
    // Provider's local cache is disabled for globally registered providers.
    // Custom key store provider implementation must include column encryption key cache to provide caching support to locally registered providers.
    public virtual TimeSpan? ColumnEncryptionKeyCacheTtl { get; set; } = new TimeSpan(0);
}

Preferencia de dirección IP

Se ha introducido una nueva propiedad de conexión IPAddressPreference para indicar la preferencia de familia de direcciones IP al controlador al establecer conexiones TCP. Si Transparent Network IP Resolution (en .NET Framework) o Multi Subnet Failover se establecen en true, esta configuración no tiene ningún efecto. Existen tres valores aceptados para esta propiedad:

IPv4First
- Este es el valor predeterminado. El controlador usa primero direcciones IPv4 resueltas. Si no es posible conectarse correctamente a ninguna de ellas, prueba con direcciones IPv6 resueltas.
IPv6First
- El controlador usa primero direcciones IPv6 resueltas. Si no es posible conectarse correctamente a ninguna de ellas, prueba con direcciones IPv4 resueltas.
UsePlatformDefault
- El controlador prueba las direcciones IP en el orden en que se recibieron de la respuesta de resolución DNS.

Compatibilidad con la plataforma de destino 3.0

.NET Framework 4.6.1+ (Windows x86, Windows x64)
.NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Notas de la versión 2.1

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 2.1.

Nuevas características de la versión 2.1

Compatibilidad multiplataforma con Always Encrypted

Microsoft.Data.SqlClient v2.1 amplía la compatibilidad con Always Encrypted en las siguientes plataformas:

Compatibilidad con Always Encrypted	Compatibilidad de Always Encrypted con enclaves seguros	Framework de destino	Versión de Microsoft.Data.SqlClient	Sistema operativo
Sí	Sí	.NET Framework 4.6+	1.1.0+	Windows
Sí	Sí	.NET Core 2.1+	2.1.0+¹	Windows, Linux, macOS
Sí	No²	.NET Standard 2.0	2.1.0+	Windows, Linux, macOS
Sí	Sí	.NET Standard 2.1+	2.1.0+	Windows, Linux, macOS

¹ Antes de la versión 2.1 de Microsoft.Data.SqlClient, Always Encrypted solo se admite en Windows.
² Siempre cifrado con enclaves seguros no es compatible con .NET Standard 2.0.

Autenticación del flujo de código de dispositivo de Microsoft Entra

Microsoft.Data.SqlClient v2.1 proporciona compatibilidad para la autenticación "flujo de código de dispositivo" con MSAL.NET. Documentación de referencia: Flujo de concesión de autorización de dispositivo de OAuth 2.0

Ejemplo de cadena de conexión:

Server=<server>.database.windows.net; Authentication=Active Directory Device Code Flow; Database=Northwind;Encrypt=True

La siguiente API permite personalizar el mecanismo de devolución de llamada del flujo de código del dispositivo:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetDeviceCodeFlowCallback(Func<DeviceCodeResult, Task> deviceCodeFlowCallbackMethod)
}

Autenticación de identidad gestionada por Microsoft Entra

Microsoft.Data.SqlClient v2.1 incluye compatibilidad con la autenticación de Microsoft Entra mediante identidades administradas.

Se admiten las siguientes palabras clave de modo de autenticación:

Identidad administrada de Active Directory
MSI de Active Directory (para la compatibilidad entre controladores de MS SQL)

Ejemplos de cadena de conexión:

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; Initial Catalog={db};"

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

Mejoras en la autenticación interactiva de Microsoft Entra

Microsoft.Data.SqlClient v2.1 agrega las siguientes API para personalizar la experiencia de autenticación de Microsoft Entra interactivo:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken, Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void ClearUserTokenCache();
}

Sección de configuración `SqlClientAuthenticationProviders`

Microsoft.Data.SqlClient v2.1 presenta una nueva sección de configuración, SqlClientAuthenticationProviders (un clon de SqlAuthenticationProviders existente). La sección de configuración existente, SqlAuthenticationProviders, sigue siendo compatible retroactivamente cuando se define el tipo adecuado.

La nueva sección permite que los archivos de configuración de la aplicación contengan una sección SqlAuthenticationProviders para System.Data.SqlClient y una sección SqlClientAuthenticationProviders section para Microsoft.Data.SqlClient.

Autenticación de Microsoft Entra mediante un Id. de cliente de aplicación

Microsoft.Data.SqlClient v2.1 incluye compatibilidad para pasar un identificador de cliente de aplicación definido por el usuario a la Biblioteca de autenticación de Microsoft. El Id. de cliente de aplicación se usa al autenticarse con Microsoft Entra ID.

Se introdujeron las siguientes API nuevas:

Se ha introducido un nuevo constructor en ActiveDirectoryAuthenticationProvider:

Se aplica a: Todas las plataformas de .NET (.NET Framework, .NET Core y .NET Standard)

public ActiveDirectoryAuthenticationProvider(string applicationClientId)

Uso:

string APP_CLIENT_ID = "<GUID>";
SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID);
SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider);

using (SqlConnection sqlConnection = new SqlConnection("<connection_string>"))
{
    sqlConnection.Open();
}

Se ha introducido una nueva propiedad de configuración en SqlAuthenticationProviderConfigurationSection y SqlClientAuthenticationProviderConfigurationSection:

Se aplica a: .NET Framework y .NET Core

internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
{
    ...
    [ConfigurationProperty("applicationClientId", IsRequired = false)]
    public string ApplicationClientId => this["applicationClientId"] as string;
}

// Inheritance
internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
{ ... }

Uso:

<configuration>
    <configSections>
        <section name="SqlClientAuthenticationProviders"
                         type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
    </configSections>
    <SqlClientAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

<!--or-->

<configuration>
    <configSections>
        <section name="SqlAuthenticationProviders"
                         type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
    </configSections>
    <SqlAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

Compatibilidad con la clasificación de datos v2

Microsoft.Data.SqlClient v2.1 incluye compatibilidad con la información de "rango de confidencialidad" de la clasificación de datos. Ahora están disponibles las siguientes API nuevas:

public class SensitivityClassification
{
    public SensitivityRank SensitivityRank;
}

public class SensitivityProperty
{
    public SensitivityRank SensitivityRank;
}

public enum SensitivityRank
{
    NOT_DEFINED = -1,
    NONE = 0,
    LOW = 10,
    MEDIUM = 20,
    HIGH = 30,
    CRITICAL = 40
}

Identificador de sesión para una sesión activa `SqlConnection`

Microsoft.Data.SqlClient v2.1 introduce una nueva propiedad SqlConnection, ServerProcessId, en una conexión activa.

public class SqlConnection
{
    // Returns the session ID (SPID) of the active connection.
    public int ServerProcessId;
}

Compatibilidad con el registro de rastreo en SNI nativo

Microsoft.Data.SqlClient v2.1 amplía la implementación de SqlClientEventSource existente para habilitar el seguimiento de eventos en SNI.dll. Los eventos deben capturarse con una herramienta como Xperf.

El seguimiento se puede habilitar mediante el envío de un comando a SqlClientEventSource como se muestra a continuación:

// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);

// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);

// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);

Propiedad "Tiempo de espera del comando" de la cadena de conexión

Microsoft.Data.SqlClient v2.1 introduce la propiedad de la cadena de conexión "Tiempo de espera del comando" para reemplazar el valor predeterminado de 30 segundos. El tiempo de espera de los comandos individuales se puede invalidar mediante la CommandTimeout propiedad en SqlCommand.

Ejemplos de cadena de conexión:

"Server={serverURL}; Initial Catalog={db}; Encrypt=True; Integrated Security=true; Command Timeout=60"

Eliminación de símbolos de SNI nativo

Con Microsoft.Data.SqlClient v2.1, hemos quitado los símbolos introducidos en v2.0.0 del paquete NuGet Microsoft.Data.SqlClient.SNI.runtime a partir de la versión v2.1.1. Los símbolos públicos se publican ahora en el servidor de símbolos de Microsoft para herramientas como BinSkim que requieren acceso a símbolos públicos.

Enlace de origen de símbolos de Microsoft.Data.SqlClient

A partir de Microsoft.Data.SqlClient v2.1, los símbolos de Microsoft.Data.SqlClient se vinculan por código fuente y se publican en el servidor de símbolos de Microsoft para una experiencia de depuración mejorada sin necesidad de descargar el código fuente.

2.1 Compatibilidad con la plataforma de destino

.NET Framework 4.6+ (Windows x86, Windows x64)
.NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Notas de la versión 2.0

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 2.0.

Cambios importantes en la versión 2.0

El modificador de acceso de la interfaz del proveedor de enclave SqlColumnEncryptionEnclaveProvider ha cambiado de public a internal.
Las constantes de la clase SqlClientMetaDataCollectionNames se han actualizado para reflejar los cambios en SQL Server.
El controlador realiza ahora la validación del certificado de servidor cuando el servidor SQL Server de destino aplica el cifrado TLS, que es el valor predeterminado para las conexiones de Azure.
SqlDataReader.GetSchemaTable() ahora devuelve un elemento DataTable vacío en lugar de null.
El controlador ahora realiza el redondeo de la escala decimal para que coincida con el comportamiento de SQL Server. Para asegurar la compatibilidad con versiones anteriores, el comportamiento previo de truncamiento puede ser habilitado mediante un conmutador AppContext.
En el caso de las aplicaciones de .NET Framework que consumen Microsoft.Data.SqlClient, los archivos SNI.dll descargados previamente en las carpetas bin\x64 y bin\x86 ahora se denominan Microsoft.Data.SqlClient.SNI.x64.dll y Microsoft.Data.SqlClient.SNI.x86.dll, y se descargan en el directorio bin.
Para mantener la consistencia, los nuevos sinónimos de propiedades de la cadena de conexión reemplazan a las propiedades anteriores cuando se recupera la cadena de conexión de SqlConnectionStringBuilder. Más información

Nuevas características de la versión 2.0

En Microsoft.Data.SqlClient 2.0 se han incorporado las características nuevas siguientes.

Resistencia ante errores de DNS

Ahora, el controlador copia en caché las direcciones IP de todas las conexiones correctas a un punto de conexión de SQL Server que admite la característica. Si se produce un error de resolución de DNS durante un intento de conexión, el controlador intenta establecer una conexión mediante una dirección IP copiada en caché para ese servidor, si existe.

Seguimiento de EventSource

Esta versión introduce la posibilidad de capturar registros de seguimiento de eventos para la depuración de aplicaciones. Para capturar estos eventos, las aplicaciones cliente deben escuchar eventos de la implementación de EventSource de SqlClient:

Microsoft.Data.SqlClient.EventSource

Para obtener más información, vea cómo habilitar el seguimiento de eventos en SqlClient.

Habilitación de redes administradas en Windows

Un nuevo modificador de AppContext "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows" permite el uso de una implementación de SNI administrada en Windows con fines de prueba y depuración. Este interruptor alterna el comportamiento del controlador para usar un SNI administrado en los proyectos de .NET Core 2.1+ y .NET Standard 2.0+ en Windows, eliminando todas las dependencias de las bibliotecas nativas para la biblioteca Microsoft.Data.SqlClient.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

Consulte Modificadores de AppContext en SqlClient para obtener una lista completa de los modificadores disponibles en el controlador.

Habilitación del comportamiento de truncamiento decimal

El controlador redondea la escala de datos decimal de forma predeterminada, tal y como lo hace SQL Server. Para obtener compatibilidad con versiones anteriores, puede establecer el conmutador de AppContext "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" en true.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Nuevos sinónimos de la propiedad de cadena de conexión

Se han agregado sinónimos nuevos para las siguientes propiedades de cadena de conexión existentes para evitar la confusión causada por el espaciado en propiedades con más de una palabra. Los nombres de propiedad antiguos siguen siendo compatibles con versiones anteriores. Pero las nuevas propiedades de cadena de conexión ahora se incluyen al capturar la cadena de conexión de SqlConnectionStringBuilder.

Propiedad existente de cadena de conexión	Nuevo sinónimo
Intención de aplicación	Intención de la aplicación
ConnectRetryCount	Recuento de reintentos de conexión
IntervaloDeReintentoDeConexión	Intervalo de reintentos de conexión
Periodo de Bloqueo del Pool	Período de bloqueo de la piscina
Conjuntos de Resultados Activos Múltiples	Conjuntos de resultados activos múltiples (MARS)
MultiSubnetFailover	Conmutación por error de varias subredes
TransparentNetworkIPResolution	Resolución de IP de red transparente
TrustServerCertificate	Confianza en el Certificado del Servidor

Propiedad RowsCopied de SqlBulkCopy

La propiedad RowsCopied proporciona acceso de solo lectura al número de filas que se han procesado en la operación de copia masiva en curso. Este valor podría no ser necesariamente igual al número final de filas agregadas a la tabla de destino.

Sobrescrituras de apertura de conexión

El comportamiento predeterminado de SqlConnection.Open() se puede invalidar para deshabilitar el retraso de diez segundos y los reintentos de conexión automática que desencadenan los errores transitorios.

using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"))
{
    sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry);
}

Nota:

Esta sobrescritura se puede aplicar a SqlConnection.OpenAsync() a partir de Microsoft.Data.SqlClient v6.0.0.

Soporte para nombres de usuario en el modo interactivo de Active Directory

Se puede especificar un nombre de usuario en la cadena de conexión cuando se usa el modo interactivo de autenticación de Microsoft Entra para .NET Framework y .NET Core

Establezca un nombre de usuario mediante la propiedad de cadena de conexión User ID o UID:

"Server=<server name>; Database=<db name>; Authentication=Active Directory Interactive; User Id=<username>;Encrypt=True;"

Sugerencias de orden para SqlBulkCopy

Se pueden proporcionar sugerencias de orden para mejorar el rendimiento de las operaciones de copia masiva en tablas con índices agrupados. Para obtener más información, vea la sección Operaciones de copia masiva.

Cambios de dependencia de SNI

Microsoft.Data.SqlClient (.NET Core y .NET Standard) en Windows ahora depende de Microsoft.Data.SqlClient.SNI.runtime, reemplazando la dependencia anterior en runtime.native.System.Data.SqlClient.SNI. La nueva dependencia agrega compatibilidad con la plataforma ARM junto con las plataformas ya admitidas Arm64, x64 y x86 en Windows.

Compatibilidad con la plataforma de destino 2.0

.NET Framework 4.6+ (Windows x86, Windows x64)
.NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Notas de la versión 1.1

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 1.1.

Nuevas características de la versión 1.1

Siempre Cifrado con enclaves seguros

Always Encrypted está disponible a partir de Microsoft SQL Server 2016. Los enclaves seguros están disponibles a partir de Microsoft SQL Server 2019. Para usar la característica de enclaves, las cadenas de conexión deben incluir el protocolo de atestación y la dirección URL de atestación necesarios. Por ejemplo:

"Attestation Protocol=HGS;Enclave Attestation Url=<attestation_url_for_HGS>"

Para más información, consulte:

1.1 Compatibilidad con la plataforma de destino

.NET Framework 4.6+ (Windows x86, Windows x64)
.NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Linux, macOS)

Notas de la versión 1.0

La versión inicial del espacio de nombres Microsoft.Data.SqlClient ofrece más funcionalidades que el espacio de nombres System.Data.SqlClient existente.

Las notas completas de la versión, incluidas las dependencias, están disponibles en el repositorio de GitHub: Notas de la versión 1.0.

Nuevas características de la versión 1.0

Nuevas características de System.Data.SqlClient en .NET Framework 4.7.2

Clasificación de datos: disponible en Azure SQL Database y Microsoft SQL Server 2019.
Compatibilidad con UTF-8: disponible en Microsoft SQL Server 2019.

Nuevas características de System.Data.SqlClient en .NET Core 2.2

Clasificación de datos: disponible en Azure SQL Database y Microsoft SQL Server 2019.
Compatibilidad con UTF-8: disponible en Microsoft SQL Server 2019.
Autenticación: modo de autenticación de contraseña de Active Directory.

Clasificación de datos

La clasificación de datos proporciona un nuevo conjunto de API que exponen información de clasificación y confidencialidad de los datos de solo lectura de los objetos recuperados a través de SqlDataReader cuando el origen subyacente admite la característica y contiene metadatos de confidencialidad y clasificación de datos. Vea la aplicación de ejemplo en Detección y clasificación de datos en SqlClient.

public class SqlDataReader
{
    public Microsoft.Data.SqlClient.DataClassification.SensitivityClassification SensitivityClassification
}

namespace Microsoft.Data.SqlClient.DataClassification
{
    public class ColumnSensitivity
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.SensitivityProperty> SensitivityProperties
    }
    public class InformationType
    {
        public string Id
        public string Name
    }
    public class Label
    {
        public string Id
        public string Name
    }
    public class SensitivityClassification
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.ColumnSensitivity> ColumnSensitivities
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.InformationType> InformationTypes
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.Label> Labels
    }
    public class SensitivityProperty
    {
        public Microsoft.Data.SqlClient.DataClassification.InformationType InformationType
        public Microsoft.Data.SqlClient.DataClassification.Label Label
    }
}

Compatibilidad con UTF-8

La compatibilidad con UTF-8 no requiere hacer ningún cambio en el código de la aplicación. Estos cambios de SqlClient optimizan la comunicación entre el cliente y el servidor cuando el servidor admite UTF-8 y la intercalación de columna subyacente es UTF-8. Consulte la sección UTF-8 en Novedades de SQL Server 2019.

Siempre Cifrado con enclaves seguros

En general, la documentación existente que usa System.Data.SqlClient en .NET Framework y los proveedores de almacenamiento de claves maestras de columna integradas ahora deben trabajar también con .NET Core.

Autenticación

Se pueden especificar diferentes modos de autenticación mediante la opción de cadena de conexión Autenticación. Para obtener más información, consulte la documentación de SqlAuthenticationMethod.

Los proveedores de almacén de claves personalizados, como el proveedor de Azure Key Vault, deben actualizarse para admitir Microsoft.Data.SqlClient. Del mismo modo, los proveedores de enclave también deben actualizarse para admitir Microsoft.Data.SqlClient.

Always Encrypted solo se admite en los destinos de .NET Framework y .NET Core. No se admite en .NET Standard, ya que carece de ciertas dependencias de cifrado.

Compatibilidad con la plataforma de destino 1.0

.NET Framework 4.6+ (Windows x86, Windows x64)
.NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS)
.NET Standard 2.0+ (Windows x86, Windows x64, Linux, macOS)

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-03-25

Compartir a través de

Introducción al espacio de nombres Microsoft.Data.SqlClient

Referencia de API

Notas de la versión 7.0

Cambios importantes en la versión 7.0

Dependencias de Azure eliminadas del paquete principal

Otros cambios importantes en la versión 7.0

Nuevas características de la versión 7.0

Autenticación conectable con SspiContextProvider

Rendimiento de lectura asincrónica: multiplexación de paquetes (versión preliminar)

Compatibilidad mejorada con enrutamiento

Compatibilidad con .NET 10

Eventos de diagnóstico fuertemente tipados en .NET Framework

Otras adiciones en la versión 7.0

Cambios en la versión 7.0

Desuso de SqlAuthenticationMethod.ActiveDirectoryPassword

Soporte de la plataforma objetivo 7.0

Notas de la versión 6.1

Nuevas características de la versión 6.1

Se ha agregado compatibilidad con tipos de datos vectoriales de SQL Server dedicados

Compatibilidad de destino de .NET Standard 2.0 revivida

Otras adiciones

Compatibilidad con la plataforma de destino 6.1

Notas de la versión 6.0

Cambios importantes en la versión 6.0

Nuevas características de la versión 6.0

Compatibilidad con tipos de datos JSON

Introducción a SqlClientDiagnostics

Se agregó compatibilidad con invalidaciones de conexión en la API OpenAsync()

Soporte para la plataforma objetivo 6.0

Notas de la versión 5.2

Nuevas características de la versión 5.2

Se ha agregado una nueva propiedad RowsCopied64 a SqlBulkCopy

Se ha agregado una nueva propiedad AccessTokenCallBack a SqlConnection

API SqlBatch

5.2 Compatibilidad con la plataforma de destino

Notas de la versión 5.1

Cambios importantes en la versión 5.1

Nuevas características de la versión 5.1

Certificado de servidor

5.1 Compatibilidad con la plataforma de destino

Notas de la versión 5.0

Cambios importantes en la versión 5.0

Nuevas características de la versión 5.0

Seguridad mejorada de TDS 8.0

SPN del servidor

Compatibilidad con alias de SQL

Compatibilidad con el enumerador de orígenes de datos SQL

Supresión de advertencias de TLS no seguro

Soporte para la plataforma de destino 5.0

Notas de la versión 4.1

Nuevas características de la versión 4.1

Introducir el protocolo de atestación Ninguno

4.1 Compatibilidad con la plataforma de destino

Notas de la versión 4.0

Cambios importantes en la versión 4.0

Nuevas características de la versión 4.0

El valor predeterminado del cifrado está establecido en verdadero.

Asegurarse de que las conexiones no se pueden realizar cuando se requiere cifrado

Cambio de contexto de aplicación para usar los protocolos predeterminados del sistema

Habilitación del enlace de parámetros optimizados

Eliminar el interruptor de seguridad de lógica de reintentos configurable

Compatibilidad con instancias compartidas de SqlLocalDb

Compatibilidad con GetFieldValueAsync<T> y GetFieldValue<T> para los tipos XmlReader, TextReader, Stream

Compatibilidad con la plataforma de destino 4.0

Notas de la versión 3.1

Nuevas características de la versión 3.1

Se introdujo el protocolo de atestación 'None'.

Compatibilidad con la plataforma de destino

Notas de la versión 3.0

Cambios importantes en la versión 3.0

Nuevas características de la versión 3.0

Lógica de reintento configurable

Contadores de eventos

Introducción a la dependencia de Azure Identity

Mejoras de seguimiento de eventos en SNI.dll

Habilitar el comportamiento nulo de la versión de fila

Compatibilidad con la autenticación predeterminada de Microsoft Entra

Mejoras en la funcionalidad del registro de proveedores personalizados de almacenamiento de claves maestras

Precedencia en el registro de proveedores de almacenamiento de claves maestras por columna

Desuso de `SqlAuthenticationMethod.ActiveDirectoryPassword`

Se ha agregado una nueva propiedad `RowsCopied64` a SqlBulkCopy

Se ha agregado una nueva propiedad `AccessTokenCallBack` a SqlConnection

Compatibilidad con `GetFieldValueAsync<T>` y `GetFieldValue<T>` para los tipos `XmlReader`, `TextReader`, `Stream`

Sección de configuración `SqlClientAuthenticationProviders`

Identificador de sesión para una sesión activa `SqlConnection`