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 trata 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 autentica 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.

Configure 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 configure Trust Server Certificate=true para corregir un error de conexión en 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 coincide 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 solo un certificado específico, configure 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. Cuando abres un SqlConnection, el controlador toma una conexión física de un pool que coincida con la conexión solicitada. Cuando cierras o liberas la conexión, la conexión física regresa al pool en lugar de cerrarse. Una apertura reutilizada salta la conexión de red, el handshake TLS y el inicio de sesión.

Siga estas reglas:

• Abre una conexión justo antes de necesitarla y deshazla tan pronto como termines, con using o await using. Una conexión que no se elimina se queda revisada, y la piscina puede quedarse sin ella.

• Construye la cadena de conexión una vez al arrancar y reutilala. 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 más información, véase Mantener una cadena de conexión canónica.

• Espera un pool separado para cada identidad de Windows bajo 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 estén eliminadas antes de que subas Max Pool Size, que por defecto 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 de los servidores para cada pool. Cada proceso, o cada dominio de aplicación en .NET Framework, tiene sus propios pools. Las conexiones al servidor pueden multiplicarse Max Pool Size por los pools en cada proceso y por el número de instancias de aplicación.

• No configures Pooling=false para evitar un problema de pooling. 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 claves de pool, tamaño, compensación y transacciones, consulta SQL Server connection pooling.

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 frameworks y herramientas que abren conexiones para una aplicación también pueden reportarse 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

Usa SqlConnectionStringBuilder cuando el código añade o cambia 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 constructor valida valores, asigna sinónimos a palabras clave canónicas y pone entre comillas cada valor para que el valor no pueda 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.
• Prefiera un método de autenticación que no necesite contraseña en la cadena de conexión.
• Restringir el acceso a la fuente de configuración.
• Rota los secretos almacenados y reinicia o recarga las aplicaciones que los almacenan en caché.
• No escribas cadenas de conexión en registros, excepciones, trazas o telemetría.
• Deje Persist Security Info=false, el valor predeterminado, 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 fijan 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 reconoce genera ArgumentException junto con el mensaje Keyword not supported.

Los valores pueden ser sensibles a mayúsculas y mayúsculas, dependiendo de la palabra clave. Una contraseña distingue entre mayúsculas y minúsculas. Encrypt=STRICT y Encrypt=strict son lo mismo.

Este programa muestra cómo el generador normaliza palabras clave, resuelve un duplicado y cita 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.

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.

Las normas de presupuesto son fáciles de equivocar. Fija los valores a través de SqlConnectionStringBuilder las propiedades y deja que el constructor los presupuesta. Para más información, consulta Construir 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.

Utiliza palabras clave de otros conductores

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ínelos.
• 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