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.

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 la base de datos desde IConfiguration, así que los valores provienen de los proveedores de configuración que el host conecta (appsettings.jsonvariables de entorno, Azure App Configuration, ajustes respaldados por Key Vault, etc.). La configuración combina Seguridad de la Capa de Transporte (TLS), identidad gestionada, resiliencia de conexión inactiva, reintento de conexión inicial mediante lógica de reintento configurable (CRL) con registro estructurado, reintento a nivel de comando para errores transitorios que se activan en medio de la consulta, y rápida recuperación en grupos de conmutación por conmutación.

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 using directivas 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 está dirigido a cualquier endpoint de SQL Motor de base de datos configurado para autenticación Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, base de datos SQL en Microsoft Fabric, y SQL Server 2022 y versiones posteriores en Azure Virtual Machines o habilitadas 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 habilitar la resiliencia de la conexión inactiva: Tras Open() el éxito, el controlador reconecta de forma transparente una conexión inactiva caída en el siguiente comando. No vuelven a intentar el archivo inicial Open(). Los intentos de conexión inicial provienen del openRetry proveedor asignado a SqlConnection.RetryLogicProvider. Ambas características son complementarias.

El Retrying evento en cada proveedor se activa antes de cada intento de reintento y lleva el recuento de intentos, el retraso antes del siguiente intento y las excepciones observadas hasta el momento. Enrutízalo a ILogger tu pipeline de telemetría para mantener visible el bucle de reintento en producción.

Establezca MultiSubnetFailover = true cuando el destino es Azure SQL Database, Azure SQL Managed Instance, base de datos SQL en Microsoft Fabric, un oyente de grupo de disponibilidad o una instancia de clúster de conmutación por fallo. Selecciona una ruta de código de conexión paralela que intenta conexiones TCP a todas las direcciones IP resueltas en paralelo y utiliza la primera conexión que tenga éxito, evitando la lenta caminata secuencial por IP que de otro modo podría bloquear 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 primero Open() puede fallar con 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 lado del cliente aparecen como error -2, que no está en esa lista, así que openRetry no rescatan ni Open() que se agoten a mitad de la reanudación. El intento de contacto individual debe ser lo suficientemente largo para cubrir el currículum. Para más información, consulta la pausa automática y la reanudación automática.

El reintento a nivel de comando es decisión del llamador, por comando. Adjuntar commandRetry solo SqlCommand.RetryLogicProvider cuando reproducir el comando es seguro: lecturas, MERGE protegidas por una llave natural, aceleraciones 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:

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. Configurado Encrypt=Strict para cifrado TDS 8.0 en Microsoft. Data.SqlClient 5.0 y 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 de Windows integrada para Active Directory local y escenarios heredados.
  • Always Encrypted: cifrado del lado cliente para columnas confidenciales, con enclaves seguros opcionales para operaciones en contexto.
  • Copia masiva: insertos de alto rendimiento con SqlBulkCopy.
  • Resiliencia de conexión: Reintentos de conexión integrados (ConnectRetryCount y ConnectRetryInterval) más lógica de reintentos configurable opt-in 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

Artículo Descripción
Introducción al controlador SqlClient Configura un proyecto, crea una base de datos, conéctate, consulta y añade resiliencia de conexión.
Información general sobre el controlador SqlClient Aprende cómo Microsoft. Data.SqlClient encaja en ADO.NET.
Descarga Microsoft. Data.SqlClient Instala el paquete NuGet y busca las versiones fuente.
Ciclo de vida de soporte técnico Revisa las versiones de controladores compatibles y las fechas de soporte.
Microsoft. Espacio de nombres Data.SqlClient Migra desde System.Data.SqlClient y revisa las diferencias en el espacio de nombres.

Configuración y conexión

Artículo Descripción
Conectarse a un origen de datos Abre y gestiona las conexiones a SQL Server y Azure SQL.
Cadenas de conexión Configura el servidor, la base de datos, la autenticación, el cifrado y el comportamiento de conexión.
Cifrado y validación de certificados Configura conexiones cifradas y validación de certificados de servidor.
Agrupación de conexiones a SQL Server Reutiliza las conexiones físicas de forma eficiente.
Eventos de conexión Responder al estado de la conexión y a los mensajes informativos.

Autenticar y asegurar

Artículo Descripción
Seguridad de SQL Server Revisa la autenticación, autorización y orientación sobre seguridad de aplicaciones.
Autenticación de Microsoft Entra Conéctate con la identidad gestionada, el principal de servicio, la contraseña y los flujos interactivos.
Proteger la información de conexión Mantén las credenciales y los ajustes de conexión fuera del código de la aplicación.
Siempre cifrado Proteger los valores sensibles de las columnas del sistema de bases de datos.
Always Encrypted con enclaves seguros Ejecuta operaciones ricas sobre datos cifrados con un enclave seguro.

Recuperar y actualizar datos

Artículo Descripción
Comandos y parámetros Ejecuta sentencias SQL parametrizadas y procedimientos almacenados.
DataAdapters y DataReaders Conjuntos de resultados de flujo o poblar estructuras de datos desconectadas.
Transacciones y simultaneidad Utiliza transacciones locales y distribuidas y controles de concurrencia.
Recuperar información del esquema de la base de datos Descubre colecciones de esquemas y restricciones.
Operaciones de copia masiva Carga grandes conjuntos de datos eficientemente con SqlBulkCopy.
Parámetros con valores de tabla Envía varias filas a una instrucción parametrizada o procedimiento almacenado.
Programación asincrónica Utiliza operaciones de conexión, comandos y datos asíncronas.
Conjuntos de resultados activos múltiples (MARS) Intercalar varios lotes en una sola conexión.

Tipos de datos

Artículo Descripción
Mapeos de tipos de datos ADO.NET Mapea los tipos de ejecución de lenguaje común a los tipos de proveedor y SQL Server.
Tipos de datos de SQL Server Trabaja con valores y System.Data.SqlTypes tipos específicos de SQL Server.
Datos JSON Envía y recupera el tipo de dato de SQL Serverjson.
Datos vectoriales Envía y recupera valores vectoriales.
Datos XML Lee, escribe y parametriza los valores XML.
Datos binarios y de gran valor Transmite y actualiza datos binarios, FILESTREAM y de gran valor.

Fiabilidad y diagnóstico

Artículo Descripción
Lógica de reintento configurable Intenta de nuevo fallos de conexión transitoria y comandos con políticas acotadas.
Alta disponibilidad y recuperación ante desastres Conéctate con los oyentes del grupo de disponibilidad y socios de failover.
Contadores diagnósticos Monitoriza las conexiones activas, las conexiones agrupadas y otras métricas de controladores.
Habilitar el rastreo de fuentes de eventos Captura eventos detallados de los conductores para el diagnóstico.
Trazado de datos Rastrear las operaciones y el acceso a datos de ADO.NET.
Guía de solución de problemas de SqlClient Diagnostica problemas comunes de conexión y controladores.
Notificaciones de consulta Recibe notificaciones cuando cambian los resultados de la consulta.

Características de SQL Server

Artículo Descripción
Características de SQL Server y ADO.NET Explora las funciones específicas de SQL Server disponibles a través de SqlClient.
Base de datos local Conéctate a instancias de SQL Server Express LocalDB.
Clasificación y detección de datos Lee metadatos de clasificación de sensibilidad de los conjuntos de resultados.

Referencia y recursos

Artículo Descripción
Microsoft. Referencia de la API Data.SqlClient Consulta la referencia de la API .NET para el controlador.
Cambios en AppContext Configura la compatibilidad y el comportamiento de seguridad.
Encuentra información adicional de SqlClient Encuentra código fuente, soporte y recursos comunitarios.

Contenido relacionado

  • Last updated on