Microsoft. Data.SqlClient para SQL Server

Descargar ADO.NET

Microsoft. Data.SqlClient es el proveedor de datos .NET compatible para SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics y base de datos SQL en Microsoft Fabric. Se distribuye como un paquete NuGet, evoluciona de forma independiente al tiempo de ejecución .NET y se reemplaza System.Data.SqlClient para nuevos desarrollos. Úsalo para abrir conexiones, ejecutar comandos, procesar resultados, gestionar transacciones, cargar datos en masa y emplear funciones específicas de SQL Server de aplicaciones .NET.

Elija el punto de partida.

• Para configurar un proyecto y ejecutar tu primera consulta, empieza con Empezar con el controlador SqlClient.
• Para añadir el controlador a un proyecto .NET, ve a Descargar Microsoft. Data.SqlClient.
• Para conectarte a Azure SQL con autenticación sin contraseña, empieza con la autenticación Microsoft Entra y las cadenas de conexión.
• Para hacer que una aplicación existente sea resistente a fallos transitorios, ve a Lógica de reintento configurable y Alta disponibilidad y recuperación ante desastres.
• Para mover conjuntos de datos grandes de forma eficiente, ve a operaciones de copia masiva.
• Para migrar desde System.Data.SqlClient, comienza con Introducción a Microsoft.Data.SqlClient.
• Para diagnosticar un problema de conexión o consulta, consulta la guía de solución de problemas de SqlClient y activa el rastreo de fuentes de eventos.

Línea base de producción para Azure SQL

Utiliza este fragmento como punto de partida para una ruta de acceso a datos de Azure SQL orientada a producción. Lee los nombres del servidor y de la base de datos desde IConfiguration, por lo que los valores provienen de los proveedores de configuración que el host tenga configurados (appsettings.json, variables de entorno, Azure App Configuration, configuración respaldada por Key Vault, etc.). La configuración combina Seguridad de la capa de transporte (TLS), identidad administrada, resiliencia de las conexiones inactivas, reintento de la conexión inicial mediante lógica de reintento configurable (CRL) con registro estructurado, reintento en el nivel de comando para errores transitorios que se producen durante la consulta y recuperación rápida del grupo de conmutación por error.

Para mayor seguridad y para soportar la configuración en diferentes entornos, mantén la información de conexión fuera de tu código. En producción, almacena la información de conexión en el sistema de configuración de tu aplicación y usa Azure Key Vault para valores sensibles. Para obtener más información, consulte Proteger la información de conexión.

El fragmento de C# en este artículo omite directivas using y envolvimientos de clase para mayor brevedad.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Este fragmento se aplica a cualquier punto de conexión de SQL Motor de base de datos configurado para la autenticación de Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, Base de datos SQL de Microsoft Fabric y SQL Server 2022 y versiones posteriores en Azure Virtual Machines o habilitado por Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict selecciona el cifrado TDS 8.0. Requiere Microsoft. Data.SqlClient 5.0 y versiones posteriores, y un servidor que soporta TDS 8.0 (SQL Server 2022 y versiones posteriores, Azure SQL Database, Azure SQL Managed Instance y base de datos SQL en Microsoft Fabric). Vuelve a SqlConnectionEncryptOption.Mandatory cuando te conectas a servidores antiguos.

ConnectRetryCount y ConnectRetryInterval habilitan la resiliencia de la conexión inactiva: después de que Open() se complete correctamente, el controlador vuelve a conectar de forma transparente una conexión inactiva interrumpida en el siguiente comando que se ejecute. No reintentan el Open() inicial. Los reintentos de conexión inicial provienen del proveedor openRetry asignado a SqlConnection.RetryLogicProvider. Ambas características son complementarias.

El evento Retrying de cada proveedor se activa antes de cada reintento e incluye el número de reintentos, el retraso antes del siguiente intento y las excepciones observadas hasta el momento. Rediríjalo a ILogger o a su canalización de telemetría para que el bucle de reintento siga siendo visible en producción.

Establezca MultiSubnetFailover = true cuando el destino sea Azure SQL Database, Azure SQL Managed Instance, una base de datos SQL de Microsoft Fabric, un oyente de grupo de disponibilidad o una instancia de clúster de conmutación por error. Selecciona una ruta de código para conexiones en paralelo que intenta establecer conexiones TCP con todas las direcciones IP resueltas en paralelo y usa la primera conexión que se establece correctamente, evitando el recorrido secuencial y lento por cada IP que, de otro modo, podría ralentizar esas conexiones. En objetivos de IP único, la configuración es segura. MultiSubnetFailover no se soporta cuando se conecta a una instancia nombrada, a través de un protocolo distinto a TCP, o a una instancia configurada con más de 64 direcciones IP. Tampoco puedes usarlo con el reflejo de bases de datos, que está obsoleto en todas las versiones compatibles de SQL Server. Use en su lugar los grupos de disponibilidad de Always On. Para más información, consulte Alta disponibilidad y recuperación ante desastres y Desactivar la resolución IP transparente de red.

Si el objetivo es Azure SQL Database sin servidor con la pausa automática activada, aumenta ConnectTimeout a al menos 60 segundos. Una base de datos en pausa automática se reanuda en el primer Open() y ese primer Open() puede fallar con el error 40613 mientras la base de datos se reanuda. El error 40613 está en la lista de errores transitorios incorporada, así que openRetry lo intenta de nuevo. Los tiempos de espera del cliente se manifiestan como el error -2, el cual no figura en esa lista, así que openRetry no rescatará a un Open() que agote el tiempo de espera a mitad de la reanudación. Cada intento de conexión debe durar lo suficiente para permitir la reanudación. Para más información, consulta la pausa automática y la reanudación automática.

El reintento en el nivel de comando queda a decisión de quien llama, para cada comando. Adjunte commandRetry a SqlCommand.RetryLogicProvider solo cuando sea seguro volver a ejecutar el comando: lecturas, MERGE protegidas por una clave natural, operaciones de inserción o actualización mediante un procedimiento almacenado y otras operaciones idempotentes. El proveedor de comandos incorporado omite el reintento cuando una transacción está activa, por lo que las transacciones de varias sentencias deben reintentarse mediante código de aplicación que pueda reabrir la transacción. La configuración TransientErrors reemplaza la lista de errores integrada del controlador; para ampliar la línea base integrada, use SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 y posteriores).

Para obtener más información sobre cada parte de esta configuración, consulte:

• Cadenas de conexión
• Autenticación de Microsoft Entra
• Cifrado y validación de certificados
• Lógica de reintento configurable
• Alta disponibilidad y recuperación ante desastres

Características clave

• Soporte moderno para .NET: Funciona en las versiones actuales de .NET y .NET Framework. Para el desglose por versión, véase Ciclo de vida de Soporte.
• Cifrado por defecto: conexiones cifradas TLS con Encrypt=true como predeterminadas. Establezca Encrypt=Strict para el cifrado TDS 8.0 en Microsoft.Data.SqlClient 5.0 y versiones posteriores.
• Autenticación de Microsoft Entra ID: conexiones sin contraseña con identidad administrada, principal de servicio, autenticación interactiva, autenticación integrada, cadena de credenciales predeterminada y flujos de token de acceso.
• Kerberos y NTLM: autenticación integrada de Windows para Active Directory local y entornos heredados.
• Always Encrypted: cifrado del lado cliente para columnas confidenciales, con enclaves seguros opcionales para operaciones en contexto.
• Copia en bloque: inserciones de alto rendimiento con SqlBulkCopy.
• Resistencia de la conexión: Reintentos de conexión incorporados (ConnectRetryCount y ConnectRetryInterval), además de lógica de reintento configurable y opcional para conexiones y comandos.
• Tipos de datos enriquecidos de SQL Server: datetimeoffset, sql_variant, JSON, vectoriales, espaciales, XML y parámetros con valores en tabla.
• Diagnóstico: rastreo de fuentes de eventos, contadores de diagnóstico, estadísticas de proveedores y una guía dedicada a la resolución de problemas.

Get started

Configuración y conexión

Autenticar y asegurar

Recuperar y actualizar datos

Tipos de datos

Fiabilidad y diagnóstico

Características de SQL Server

Referencia y recursos

Contenido relacionado

• Microsoft. Data.SqlClient en GitHub
• Microsoft. Data.SqlClient en NuGet
• Notas de lanzamiento
• Resumen de ADO.NET
• Módulos de conexión para Microsoft SQL Database