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, base de datos SQL en Microsoft Fabric y Warehouse 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 o actualizar el controlador en un proyecto .NET, ve a Instalar, actualizar y desplegar 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, empieza con Migrar de System.Data.SqlClient 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.

Elección de una base de datos

Crea una base de datos o conéctate a una base de datos existente en una de las siguientes plataformas:

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
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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 se aplican durante el establecimiento inicial de la conexión y la recuperación de conexiones inactivas. Cuando ConnectRetryCount es mayor que cero, el conductor vuelve a intentar fallos transitorios cualificantes durante Open(). Después de que Open() se ejecute correctamente, el controlador también utiliza esta configuración para restablecer una conexión inactiva que se haya interrumpido cuando se ejecute el siguiente comando. El proveedor asignado a SqlConnection.RetryLogicProvider añade una política de retroceso exponencial configurable para Open(). Ten en cuenta ambas capas de reintentos cuando configures el recuento de intentos y el tiempo de espera de conexión.

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