Cadenas de conexión para Microsoft.Data.SqlClient

Un Microsoft. Data.SqlClient cadena de conexión es una lista de keyword=value pares separados por puntos y coma. Pásalo a SqlConnection o SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Una cadena de conexión responde a cuatro preguntas:

1. ¿Qué servidor y base de datos utiliza la aplicación?
2. ¿Con qué identidad se ejecuta la aplicación?
3. ¿Cómo valida el cliente el certificado del servidor?
4. ¿Qué comportamiento de conexión necesita la carga de trabajo?

Este artículo aborda esas opciones y las reglas que utiliza el controlador para leer el texto. Para cada palabra clave, sus sinónimos y su valor predeterminado, véase Opciones de conexión. Para crear y cambiar cadenas de conexión en el código, véase Constructores de cadenas de conexión.

Elige un patrón de autenticación

Utiliza el patrón que se ajuste al despliegue. Sustituye cada marcador de posición, como <server>, por tu valor.

La autenticación integrada de Windows se conecta con la identidad del proceso. Para una aplicación de escritorio o consola, normalmente es el usuario que ha iniciado sesión. Para una aplicación web o un servicio de Windows, es el pool de aplicaciones o la cuenta de servicio. La suplantación puede cambiar la identidad. Concede permisos de inicio de sesión y de base de datos a la identidad que realmente utiliza tu aplicación.

Estas tres formas de autenticación integrada de Windows son equivalentes:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Si una cadena establece Integrated Security=true y también establece User ID y Password, el controlador utiliza autenticación de Windows e ignora el nombre de usuario y la contraseña.

Microsoft. Data.SqlClient 7.0 y versiones posteriores necesitan el paquete de Microsoft.Data.SqlClient.Extensions.Azure versión compatible para los métodos de autenticación Microsoft Entra ID proporcionados por el controlador. No necesitas ese paquete cuando el código de la aplicación suministra un token de acceso o un callback de token de acceso.

Para los valores aceptados Authentication , consulte Opciones de autenticación. La autenticación también requiere usuarios de bases de datos, permisos y configuración de identidad en el servidor. Para los pasos de configuración, véase la autenticación de Microsoft Entra ID y la autenticación de SQL Server.

Especificar el servidor y la base de datos

Server y Database son los nombres de palabras clave más legibles. El constructor los escribe como sus equivalentes canónicos, Data Source y Initial Catalog. Los cuatro nombres funcionan en una cadena de conexión.

Establezca Server en una de estas formas:

Utiliza tcp:, un nombre de host totalmente cualificado y un puerto explícito en producción. Utiliza un nombre DNS que coincida con el certificado del servidor, no una dirección IP, porque la validación del certificado compara el nombre del servidor en la cadena de conexión con los nombres del certificado.

Cuando te conectas a Azure SQL Database con autenticación SQL y un nombre de usuario con el formato user@servername, la parte servername debe coincidir con el servidor en Server.

Para un oyente de grupo de disponibilidad o una instancia de clúster de conmutación por error, revisa Multi Subnet Failover también las opciones de Conexión.

Configurar el cifrado y la validación de certificados

La Encrypt palabra clave acepta los siguientes valores, independientemente de mayúsculas y minúsculas:

Úsalo Strict cuando el servidor soporta TDS 8.0 y tiene un certificado que el cliente puede validar. Azure SQL Database y SQL Database en Microsoft Fabric lo soportan. Una conexión a LocalDB no está cifrada, ni siquiera con Mandatory, y Strict falla.

Los valores Encrypt y Trust Server Certificate se combinan de la siguiente manera:

No establezcas Trust Server Certificate=true para solucionar un error de conexión en entorno de producción. Cifra el canal pero no confirma la identidad del servidor. Limítalo a entornos de desarrollo donde no haya un certificado de confianza disponible.

Cuando el nombre del servidor en Data Source no coincida con el certificado, establece Host Name In Certificate con el nombre que figura en el certificado. SQL Client solo lo comprueba cuando el nombre del servidor no coincide y no fija ningún certificado. Para aceptar únicamente un certificado específico, establece Server Certificate con la ruta de un archivo PEM, DER o CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

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

Utilice la agrupación de conexiones

El pooling está activado por defecto. Al abrir un SqlConnection, el controlador toma una conexión física de un grupo que coincida con la conexión. Al cerrar o liberar la conexión, la conexión física vuelve al grupo en lugar de cerrarse. Una conexión abierta del grupo omite la conexión de red, el protocolo de enlace TLS y el inicio de sesión.

Siga estas reglas:

• Abre una conexión justo antes de necesitarla y libérala tan pronto como termines, con using o await using. Una conexión que no se libera permanece en uso, y el grupo puede agotarse.

• Crea la cadena de conexión una sola vez al iniciar el sistema y reutilízala. La clave del pool incluye el texto exacto de la cadena de conexión, por lo que un orden de palabras clave diferente, un sinónimo o un valor por petición como un ID de solicitud o un nombre de usuario crea un pool separado. El constructor escribe una única forma canónica. Para obtener más información, consulta Mantener una cadena de conexión canónica.

• Ten en cuenta que habrá un grupo de conexiones independiente para cada identidad de Windows en la autenticación integrada, cada SqlCredential instancia y cada AccessToken valor. Utiliza un método proporcionado Authentication por el driver o uno reutilizado AccessTokenCallback en lugar de configurar AccessToken en cada conexión.

• Busca conexiones que no se hayan liberado antes de alcanzar el valor de Max Pool Size, cuyo valor predeterminado es 100. Cuando todas las conexiones de un pool están en uso, Open espera hasta Connect Timeout y luego lanza InvalidOperationException:

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• Planifica la capacidad del servidor para cada grupo. Cada proceso, o cada dominio de aplicación en .NET Framework, tiene sus propios pools. Las conexiones al servidor pueden alcanzar Max Pool Size multiplicado por los grupos de cada proceso y por el número de instancias de la aplicación.

• No configures Pooling=false para solucionar un problema de agrupación. Cada vez que se abre, se realiza un inicio de sesión completo.

Para cerrar conexiones agrupadas que permanecen inactivas demasiado tiempo, véase Limitar el tiempo de inactividad de conexión. Para obtener información sobre claves de grupo, dimensionamiento, borrado y transacciones, consulta Agrupación de conexiones de SQL Server.

Configuración de conexión y de comandos por separado

Una cadena de conexión controla el establecimiento de la conexión y el comportamiento de la sesión. Un comando controla una operación SQL.

Un tiempo de espera más largo no sustituye la lógica de reintentos. Un tiempo de espera limita una espera. Un reintento inicia otro intento, y debe estar acotado y poder repetirse de forma segura.

Informa de la identidad de la aplicación

Application Name establece el nombre que el servidor reporta a través de APP_NAME(). Utiliza un nombre estable para cada carga de trabajo desplegada. Los marcos y herramientas que abren conexiones para una aplicación también pueden informarse a sí mismos a través de la propiedad RegisteredApplication, que no tiene ninguna palabra clave de cadena de conexión. Para más información, consulte Reportar la identidad de la aplicación.

Construye cadenas de conexión de forma segura

Utilice SqlConnectionStringBuilder cuando el código añada o modifique un valor. No unas texto no confiable en una cadena de conexión, porque un punto y coma en ese texto puede añadir o reemplazar una palabra clave. El generador valida los valores, asigna sinónimos a palabras clave canónicas y encierra cada valor entre comillas para que no se puedan añadir palabras clave. Para ejemplos, véase Constructores de cadenas de conexión.

Almacenar información de conexión fuera del código

Carga cadenas de conexión desde el sistema de configuración de la aplicación. Las aplicaciones .NET suelen usar variables de entorno, secretos de usuario para desarrollo local, Azure App Configuration y Azure Key Vault.

Siga estas reglas:

• No commitas contraseñas, secretos de clientes, tokens de acceso ni cadenas de conexión de producción.
• Opte por un método de autenticación que no requiera una contraseña en la cadena de conexión.
• Restringir el acceso a la fuente de configuración.
• Rota los secretos almacenados y reinicia o actualiza las aplicaciones que los almacenan en caché.
• No escribas cadenas de conexión en registros, excepciones, trazas o telemetría.
• Deja Persist Security Info=false, el valor por defecto, para que una conexión abierta no exponga la contraseña a través de su propiedad ConnectionString.

Para proveedores de configuración .NET, véase Configuración en .NET. Para más controles, consulta Protección de la información de conexión.

Reglas de análisis

El conductor aplica estas reglas:

• Las palabras clave no distinguen mayúsculas de minúsculas. DATABASE, Database, y database son la misma palabra clave.
• Muchas palabras clave tienen sinónimos. Server y Data Source establecen el mismo valor. El artículo de Opciones de Conexión enumera los sinónimos de cada palabra clave.
• Cuando una palabra clave aparece más de una vez, gana el último valor. Los sinónimos cuentan como la misma palabra clave.
• El controlador ignora los espacios alrededor de palabras clave y de valores no comillados.
• Un punto y coma final es opcional.
• Una palabra clave que el controlador no reconozca generará un ArgumentException con el mensaje Keyword not supported.

Los valores pueden distinguir entre mayúsculas y minúsculas, dependiendo de la palabra clave. Las contraseñas distinguen entre mayúsculas y minúsculas. Encrypt=STRICT y Encrypt=strict son lo mismo.

Este programa muestra cómo el generador normaliza las palabras clave, resuelve los duplicados y encierra entre comillas los caracteres especiales. La pestaña .NET Framework utiliza C# 7.3. Para crear un proyecto que ejecute las muestras, consulta Crear el proyecto.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

La salida es la siguiente:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

La primera línea muestra cada sinónimo reemplazado por su palabra clave canónica: server por Data Source, DATABASE por Initial Catalog, uid por User ID, y timeout por Connect Timeout.

Encerrar valores entre comillas

Encierra un valor entre comillas dobles (") o comillas simples (') cuando contiene punto y coma, comienza o termina con un espacio, o comienza o termina con comillas. Dentro de un valor entrecomillado, escribe dos veces la comilla que lo delimita.

Es fácil cometer errores con las reglas para encerrar entre comillas. Establece los valores a través de las propiedades SqlConnectionStringBuilder y deja que el generador los encierre entre comillas. Para obtener más información, consulte Crear cadenas de conexión de forma segura.

Especificar valores booleanos

Las palabras clave que toman un valor booleano aceptan true, false, yes y no, independientemente de mayúsculas/minúsculas. Integrated Security también acepta sspi, lo que significa true. El constructor escribe True o False.

Uso de palabras clave de otros controladores

Microsoft. Data.SqlClient no acepta palabras clave ODBC u OLE DB como Driver y Provider. Elimina estas palabras clave cuando muevas una cadena de conexión desde otro controlador. System.Data.SqlClientLas cadenas de conexión funcionan en Microsoft.Data.SqlClient, con estas diferencias:

• Encrypt se establece de forma predeterminada en Mandatory en Microsoft.Data.SqlClient. Un servidor sin un certificado de confianza no supera la validación del certificado. Instala un certificado de confianza en el servidor.
• En .NET, Network Library, Connection Reset, y Transparent Network IP Resolution no están soportados. Elimínelas.
• Context Connection=true no es compatible.
• Asynchronous Processing no es una palabra clave soportada y lanza ArgumentException. Quítelo. Los métodos asíncronos funcionan sin ello.
• Type System Version=SQL Server 2000 no es compatible. Crear la conexión lanza ArgumentException. Usa Latest, SQL Server 2012, SQL Server 2008, o SQL Server 2005.

Contenido relacionado

• Usa Microsoft. Data.SqlClient en una app .NET
• Opciones de conexión
• Generadores de cadenas de conexión
• Conectarse a un origen de datos
• Agrupación de conexiones a SQL Server
• Autenticación de Microsoft Entra ID
• Cifrado y validación de certificados
• Instancias de usuario de SQL Server Express
• Ciclo de vida de soporte del controlador SqlClient