Opciones de conexión para Microsoft. Data.SqlClient

Este artículo enumera todas las palabras clave de cadena de conexión que Microsoft. Data.SqlClient acepta. Cada palabra clave también tiene una propiedad de coincidencia SqlConnectionStringBuilder . Para una introducción, patrones comunes y reglas de análisis sintáctico, véase Cadenas de conexión.

Las palabras clave y alias no son sensibles a mayúsculas y minúsculas. Cuando fijas un valor a través de una propiedad constructora, este escribe la palabra clave canónica en la columna Palabra Clave .

Establecer opciones con SqlConnectionStringBuilder

Empieza desde una cadena de conexión base que contiene los ajustes del servidor, la base de datos y la autenticación. Luego establece opciones específicas de carga de trabajo a través de propiedades del constructor. Las pestañas del Marco .NET usan C# 7.3. Para crear un proyecto que ejecute las muestras, consulta Crear el proyecto.

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
            ?? throw new InvalidOperationException(
                "Set the SQL_CONNECTION_STRING environment variable.");

        var builder = new SqlConnectionStringBuilder(connectionString)
        {
            ApplicationName = "Orders.Worker",
            ConnectTimeout = 30,
            CommandTimeout = 60,
            MaxPoolSize = 50,
        };

        using (var connection = new SqlConnection(builder.ConnectionString))
        {
            await connection.OpenAsync();

            using (var command = new SqlCommand("SELECT APP_NAME();", connection))
            {
                Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
                Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
                Console.WriteLine($"Command timeout: {command.CommandTimeout}");
            }
        }
    }
}

La salida es la siguiente:

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

Un nuevo SqlCommand toma su tiempo de espera por defecto de la Command Timeout palabra clave de su conexión.

Comprobar valores por defecto

Un nuevo SqlConnectionStringBuilder informa la opción predeterminada para cada opción. Este programa imprime los valores predeterminados que la mayoría de las aplicaciones revisan:

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        var defaults = new SqlConnectionStringBuilder();

        Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
        Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
        Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
        Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
        Console.WriteLine($"Encrypt: {defaults.Encrypt}");
        Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
        Console.WriteLine($"Pooling: {defaults.Pooling}");
        Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
        Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
        Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
        Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
        Console.WriteLine($"Packet Size: {defaults.PacketSize}");
        Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
        Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
        Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
        Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
        Console.WriteLine($"Application Name: {defaults.ApplicationName}");
        Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
        Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");
    }
}

En .NET, la salida es:

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True es la Mandatory opción. En .NET Framework, el nombre de la aplicación por defecto es Framework Microsoft SqlClient Proveedor de datos.

Opciones de servidor y base de datos

Opciones de identidad de aplicación

Para informar qué framework o herramienta abrió una conexión, utiliza la RegisteredApplication propiedad. No tiene palabra clave de cadena de conexión. Para más información, consulte Reportar la identidad de la aplicación.

Opciones de autenticación

Authentication acepta estos valores. El constructor las escribe sin espacios, como ActiveDirectoryDefault, y el analizador acepta ambas formas.

Los métodos Microsoft Entra ID necesitan el Microsoft.Data.SqlClient.Extensions.Azure paquete. Para configuración y ejemplos, véase la autenticación Microsoft Entra ID y la autenticación de SQL Server.

Opciones de cifrado

Para las reglas completas de validación, véase Cifrado y validación de certificados.

Opciones siempre cifradas

Opciones de red

Un interruptor AppContext a nivel de proceso puede cambiar el Multi Subnet Failover valor predeterminado a true. Para más información, consulta los interruptores AppContext en SqlClient.

Opciones de tiempo de espera

Connect Timeout no limita la ejecución de consultas. Command Timeout No limita el inicio de sesión ni la espera para una conexión agrupada. Pasa a CancellationToken llamadas asíncronas para que el llamante pueda dejar de esperar antes de que expire cualquiera de los tiempos muertos.

Opciones de recuperación de conexión

Cuando Connect Retry Count es 1, que es el valor predeterminado, el controlador lo utiliza 2 para endpoints de Azure SQL y 5 para endpoints de pools SQL serverless de Azure Synapse Analytics cuando restaura una conexión inactiva rota. La primera apertura usa el valor como establecido, por lo que el valor por defecto permite un reintento en cada extremo. El controlador utiliza cualquier otro valor establecido en ambos casos.

Estas palabras clave no intentan repetir un comando que falla mientras está en ejecución. Para saltarse el reintento incorporado para una apertura, llama a una Open sobrecarga con OpenWithoutRetry. Para políticas personalizadas, véase Lógica de reintento configurable. Vuelve a intentar un comando solo cuando sea seguro repetirlo.

Opciones de agrupación

Cada cadena de conexión distinta tiene su propio pool. Para claves de pool, limpieza y tiempo de inactividad, consulta pooling de conexiones de SQL Server.

Opciones de transacción y sesión

Opciones solo del framework .NET

Estas palabras clave solo se aceptan en .NET Framework. En .NET, el constructor lanza NotSupportedException y SqlConnection lanza ArgumentException.

Palabras clave no soportadas

Reglas de validación

SqlConnectionStringBuilder Rechaza palabras clave desconocidas y muchos valores inválidos cuando los configuras. SqlConnectionrealiza más comprobaciones cuando configuras su cadena de conexión, incluyendo valores individuales que acepta el constructor y combinaciones de palabras clave. Una cadena que el constructor acepta aún puede fallar cuando creas la conexión.

El constructor y la conexión rechazan estos valores con ArgumentException:

• Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, o Min Pool Size menos que 0.
• Max Pool Size menos de 1.
• Packet Size fuera de 512 a 32.768.
• Connect Retry Count Fuera de 0 a 255.
• Connect Retry Interval Fuera del 1 al 60.
• Una palabra clave que no aparece en este artículo.

SqlConnection también rechaza estos valores con ArgumentException, aunque el constructor los acepte:

• Type System Version aparte de Latest, SQL Server 2012, SQL Server 2008, o SQL Server 2005.
• Transaction Binding aparte de Implicit Unbind o Explicit Unbind.
• Un valor mayor que el límite TDS para Application Name, Current Language, Data Source, Failover Partner, Initial Catalog, PasswordUser ID, , Workstation ID, o AttachDBFilename.

SqlConnection también rechaza estas combinaciones con ArgumentException:

• Min Pool Size mayor que Max Pool Size.
• Failover Partner sin Initial Catalog.
• Failover Partner con Multi Subnet Failover=true, User Instance=trueo Application Intent=ReadOnly.
• Authentication con Integrated Security=true.
• Password con Active Directory Integrated, Active Directory Interactive, Active Directory Managed Identity, Active Directory MSI, Active Directory Default, , o Active Directory Workload Identity.
• User ID o Password con Active Directory Device Code Flow.

Cambios en la opción de revisión

Antes de cambiar una opción en producción:

1. Registra la cadena de conexión actual, la versión del driver, el tipo de endpoint y el problema que estás resolviendo.
2. Cambia una opción a la vez.
3. Prueba del establecimiento de conexiones, la autenticación, la validación de certificados, la agrupación de conexiones, la conmutación por error, la cancelación y la ejecución de consultas.
4. Mide la latencia de conexión, las esperas en el pool y los números de error.
5. Confirma la configuración en cada instancia desplegada.

Un cambio en la cadena de conexión crea un nuevo pool. Durante un despliegue por etapas, los pools antiguos y nuevos existen al mismo tiempo, por lo que el número total de conexiones físicas al servidor puede aumentar.

Contenido relacionado

• Cadenas de conexión
• Generadores de cadenas de conexión
• Conectarse a un origen de datos
• Agrupación de conexiones a SQL Server
• Cifrado y validación de certificados