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 .NET 8 o versiones posteriores y hace referencia a los Microsoft.Data.SqlClient paquetes y Microsoft.Data.SqlClient.Extensions.Azure 7.1.2. 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:

  • Objetivos: 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 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 donde 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 tenga éxito, evitando el lento recorrido 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 los errores transitorios que cumplan los requisitos durante Open(), y reconecta una conexión inactiva interrumpida 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 un 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.
  • Pausa automática sin servidor: Para Azure SQL Database serverless, aumenta 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: Adjúntelo a SqlCommand.RetryLogicProvider solo cuando reproducir el comando sea seguro: lectura, MERGE protegidos 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 reintentan solo los errores devueltos antes de que comience el primer conjunto de resultados. ExecuteNonQuery vuelve a intentar toda la llamada.
  • Lista de errores transitorios: La configuración 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 reintento con el recuento de reintentos, el siguiente retraso y las excepciones hasta el momento. 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 intentos. 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 reintentos en cada llamada para mantenerse autónomos. 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. Ejecute un comando para elegir una forma de resultado y ejecutar Transact-SQL (T-SQL).
  2. Configure los parámetros para que coincidan con el contrato de base de datos.
  3. Recupera datos con SqlDataReader para procesar filas y múltiples resultados.
  4. Modificar datos con procedimientos almacenados para utilizar parámetros de salida y valores de retorno.
  5. Utilice programación asíncrona y cancelación para añadir cancelación iniciada por el autor de la llamada 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 valor predeterminado. Establezca Encrypt=Strict para el cifrado TDS 8.0.
  • Autenticación de Microsoft Entra ID: Conexiones sin contraseña con flujos de identidad gestionada, principal de servicio, autenticación interactiva, autenticación integrada, cadena de credenciales predeterminada y token de acceso.
  • Kerberos y NTLM: autenticación de Windows para Active Directory local y escenarios heredados.
  • Always Encrypted: Cifrado en el lado del cliente para columnas sensibles, con enclaves seguros opcionales para operaciones in situ.
  • Copia masiva: insertos de alto rendimiento con SqlBulkCopy.
  • Agrupación de conexiones: Activada por defecto. Se está evaluando un grupo V2 opt-in.
  • Resiliencia de conexión: Reintentos de conexión incorporados (ConnectRetryCount y ConnectRetryInterval) más lógica de reintento configurable opcional para conexiones y comandos.
  • Tipos de datos enriquecidos de SQL Server: datetimeoffset, sql_variant, tipos de datos JSON, vectoriales y espaciales, XML y parámetros con valores de tabla.
  • Diagnósticos: Rastreo de fuentes de eventos, contadores de diagnóstico, estadísticas de proveedores y una guía dedicada a la solución de problemas.
  • Identidad de aplicación: Configura SqlConnection.RegisteredApplication para identificar tu biblioteca o herramienta a SQL Server (Microsoft. Data.SqlClient 7.1 y posterior).

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 implementar 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 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 de 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.
Always Encrypted 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.
Transferir datos Transfiere valores binarios grandes, texto, XML y JSON sin almacenar en búfer el valor completo.
Transacciones y concurrencia 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 de 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
Asignaciones de tipos de datos de 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 valores grandes 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 la fuente 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.
LocalDB Conéctate a instancias de SQL Server Express LocalDB.
Descubrimiento y clasificació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.
Modificadores de AppContext Configura la compatibilidad y el comportamiento de seguridad.
Repositorio de GitHub de 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 en tiempo de ejecución .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.