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. Proporciona conexiones, comandos, procesamiento de resultados, transacciones, copia masiva y funciones específicas de SQL Server a 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, por lo que los valores provienen de los proveedores de configuración que el host conecta, como appsettings.json, variables de entorno, Azure App Configuration y configuraciones respaldadas por Key Vault. La configuración combina estas características:

  • Seguridad de la Capa de Transporte (TLS).
  • Identidad administrada.
  • Resiliencia de conexiones inactivas.
  • Reintento de conexión inicial mediante lógica de reintento configurable (CRL), con registro estructurado.
  • Reintento a nivel de comando para errores transitorios que ocurren a mitad de consulta.
  • Recuperación rápida del grupo de conmutación por error.
  • Llamadas asíncronas que aceptan un token de cancelació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 directivas using y envolvimientos de clase para mayor brevedad.

El fragmento asume un proyecto que apunta a versiones de .NET 8 o posteriores y hace referencia a los paquetes Microsoft.Data.SqlClient y Microsoft.Data.SqlClient.Extensions.Azure 7.1.1. El host, como el .NET Generic Host o ASP.NET Core, suministra el ILogger y el IConfiguration, y la configuración proporciona el nombre del servidor en Sql:Server y el nombre de la base de datos en Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

El método devuelve el nombre de la base de datos a la que se conectó y registra Connected to database <database>. Cuando ocurre un reintento, también registra una advertencia por cada reintento con la excepción que lo desencadenó.

Cómo funciona cada parte del fragmento:

  • Destinos: cualquier punto de conexión 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 cifrado TDS 8.0. Requiere SQL Server 2022 y versiones posteriores, Azure SQL Database, Azure SQL Managed Instance o SQL database en Microsoft Fabric. Usa SqlConnectionEncryptOption.Mandatory para servidores antiguos.
  • ActiveDirectoryManagedIdentity: Funciona solo cuando hay una identidad gestionada disponible, como Azure App Service, Azure Functions o una máquina virtual de Azure. Para desarrollo local, utiliza SqlAuthenticationMethod.ActiveDirectoryDefault, que prueba con CLI de Azure, el inicio de sesión de Visual Studio y otras fuentes de credenciales. Mantenerlo fuera de producción porque sondear cada fuente ralentiza la conexión. Para más información, consulta Usar autenticación predeterminada.
  • MultiSubnetFailover = true: Intenta conexiones TCP a todas las direcciones IP resueltas en paralelo y utiliza la primera conexión que tiene éxito, evitando el lento paseo secuencial por IP. Configúrelo para Azure SQL Database, Azure SQL Managed Instance, base de datos SQL de Microsoft Fabric, oyentes de grupos de disponibilidad e instancias de clúster de conmutación por error. Es seguro en destinos de una sola IP. No es compatible para instancias con nombre, protocolos distintos a TCP, instancias con más de 64 direcciones IP o creación de reflejo de la base de datos, que está obsoleto. 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.
  • ConnectRetryCount = 3 y ConnectRetryInterval = 10: el controlador vuelve a intentar errores transitorios aptos para reintento durante Open(), y reconecta una conexión de reposo caída en el siguiente comando. El recuento por defecto es 1. Tres intentos separados por 10 segundos abarcan más tiempo que una reconfiguración o una conmutación por error más largos. El controlador eleva el valor de 1 a 2 solo cuando el nombre del servidor termina en un dominio de Azure SQL conocido, como .database.windows.net, por lo que un alias DNS personalizado tiene el valor 1.
  • openRetry: Asignado a SqlConnection.RetryLogicProvider, añade retroceso exponencial alrededor de Open(). El driver detiene sus intentos internos cuando ConnectTimeout expira, así que el peor escenario antes de que OpenAsync lance una excepción es de cinco intentos de hasta 30 segundos cada uno, más retroceso. Cada intento de reconexión en reposo también ejecuta la política completa openRetry , y cuando esa política agota sus reintentos, la recuperación en reposo termina.
  • Autopausa sin servidor: Para Azure SQL Database serverless, suba ConnectTimeout a al menos 60 segundos. La primera Open() puede fallar con error 40613 mientras se reanuda la base de datos, y openRetry lo intenta de nuevo. Un tiempo de espera en el lado del cliente aparece como error -2, que no se vuelve a intentar, por lo que cada intento de conexión debe durar más que la reanudación. Para más información, consulta la pausa automática y la reanudación automática.
  • commandRetry: Asócialo a SqlCommand.RetryLogicProvider solo cuando reproducir el comando sea seguro: lecturas, MERGE protegido por una clave natural, upserts mediante un procedimiento almacenado y otras operaciones idempotentes. Evita reintentar dentro de una transacción, por lo que el código de aplicación debe reintentar las transacciones de múltiples instrucciones. ExecuteReader y ExecuteScalar solo reintentan los errores devueltos antes de que empiece el primer conjunto de resultados. ExecuteNonQuery vuelve a intentar la llamada completa.
  • Lista de errores transitorios: Establecer TransientErrors reemplaza la lista integrada. Para extenderlo en su lugar, usa SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 y posteriores).
  • Retrying evento:Retrying se activa antes de cada nuevo intento con el recuento de reintentos, el siguiente retraso y las excepciones hasta ahora. Enrutízalo a ILogger o tu canal de telemetría.
  • Excepciones: El método no captura excepciones. Un proveedor agotado genera AggregateException con la excepción de cada intento. Un error no transitorio se propaga como la excepción original. El llamante lo registra una vez con el resto del contexto de la petición.
  • Cancelación: CancellationToken detiene la espera del proveedor entre reintentos. No interrumpe la espera del conductor ConnectRetryInterval en un solo Open intento. Para más información, véase Programación asíncrona.
  • Vida útil del proveedor: El fragmento crea los proveedores de reintento en cada llamada para seguir siendo autocontenido. En una aplicación, créalos una vez y reutilízalos.

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

Aprende las tareas principales de acceso a datos

Después de conectar, utiliza estos artículos en orden:

  1. Ejecuta un comando para elegir una forma de resultado y ejecuta Transact-SQL (T-SQL).
  2. Configura los parámetros para que coincidan con el contrato de la base de datos.
  3. Recuperar datos con SqlDataReader para procesar filas y múltiples resultados.
  4. Modificar datos con procedimientos almacenados para usar parámetros de salida y valores de retorno.
  5. Utiliza programación asíncrona y cancelación para añadir cancelación por parte del llamador y tiempos de espera limitados.
  6. Gestiona errores y mensajes antes de añadir reintentos o diagnósticos de producción.

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.
  • 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.
  • Pooling de conexiones: activado por defecto. Se está evaluando un grupo V2 opt-in.
  • 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.
  • Identidad de la aplicación: Configura SqlConnection.RegisteredApplication para identificar tu biblioteca o herramienta ante SQL Server (Microsoft.Data.SqlClient 7.1 y posteriores).

Get started

Artículo Descripción
Empieza con el controlador SqlClient Configura un proyecto, crea una base de datos, conéctate, consulta y añade resiliencia de conexión.
Instalar, actualizar y desplegar Microsoft. Data.SqlClient Instala los paquetes NuGet, elige una versión, actualiza el controlador y prepara la salida del despliegue.
Ciclo de vida de soporte técnico Revisa las versiones de controladores compatibles y las fechas de soporte.
Migrar de System.Data.SqlClient a Microsoft. Data.SqlClient Actualizar las referencias de paquetes, los espacios de nombres, la configuración y el comportamiento modificado del controlador.
Espacio de nombres Microsoft.Data.SqlClient y compatibilidad Entiende cómo SqlClient implementa ADO.NET y su compatibilidad con System.Data.SqlClient, .NET y SQL Server.
Novedades en Microsoft. Data.SqlClient Encuentra lanzamientos actuales, cambios importantes en las actualizaciones y notas de lanzamiento aguas arriba.

Configuración y conexión

Artículo Descripción
Conectarse a un origen de datos Abre y gestiona las conexiones, y responde a los cambios en el estado de la conexión.
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.
Gestionar errores y mensajes Detectar errores y recibir mensajes informativos.

Autenticar y asegurar

Artículo Descripción
Mejores prácticas de seguridad para Microsoft.Data.SqlClient Revisa la autenticación, autorización y orientación sobre seguridad de aplicaciones.
Autenticación de Microsoft Entra Conéctese con la identidad gestionada, la entidad 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 avanzadas con datos cifrados mediante un enclave seguro.

Recuperar y actualizar datos

Artículo Descripción
Ejecutar un comando Ejecuta sentencias SQL parametrizadas y procedimientos almacenados.
DataAdapters y DataReaders Transmita conjuntos de resultados en flujo o rellene estructuras de datos desconectadas.
Ejecutar múltiples comandos con SqlBatch Envía una colección ordenada de comandos y procesa sus resultados.
Datos de flujo Transfiere valores binarios grandes, texto, XML y JSON sin almacenar en búfer el valor completo.
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.
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 en SQL Server Asigne los tipos de SQL Server a .NET y los tipos de System.Data.SqlTypes.
Datos JSON Envía y recupera el tipo de dato json de SQL Server.
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 Vuelva a intentar los errores transitorios de conexión y de comando con directivas limitadas.
Alta disponibilidad y recuperación ante desastres Conéctese con los oyentes del grupo de disponibilidad y partners de conmutación por error.
Contadores de eventos en SqlClient Monitoriza las conexiones activas, las conexiones agrupadas y otras métricas de controladores.
Habilitar el rastreo de fuentes de eventos Capture eventos detallados del controlador para diagnósticos.
Guía de solución de problemas de SqlClient Diagnosticar problemas habituales de conexión y de 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 conjuntos de resultados.

Referencia y recursos

Artículo Descripción
Referencia de la API de Microsoft.Data.SqlClient Consulta la referencia de la API .NET para el controlador.
Cambios en AppContext Configura la compatibilidad y el comportamiento de seguridad.
Repositorio de GitHub Microsoft.Data.SqlClient Lee el código fuente del controlador, las notas de lanzamiento y los ejemplos.
Ejemplos de Microsoft.Data.SqlClient Explore ejemplos de C# para la API del controlador.
Repositorio de GitHub del runtime de .NET Lee el código fuente de las bibliotecas del runtime de .NET.

Solicitud de una característica

Para solicitar una funcionalidad, abre un problema en el repositorio de Microsoft. Data.SqlClient en GitHub.

Contenido relacionado

  • Se actualizó por última vez el