Cadenas de conexión para Microsoft.Data.SqlClient

Una Microsoft. Data.SqlClient cadena de conexión indica al controlador qué endpoint y base de datos compatibles con SQL Server usar, cómo autenticarse y cómo configurar la conexión. Pásalo a SqlConnection o SqlConnectionStringBuilder.

Empieza con cuatro decisiones:

  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?

Mantén las credenciales y los tokens de acceso fuera de la cadena de conexión cuando el método de autenticación elegido soporte ese diseño.

Elige un patrón de autenticación

Utiliza el patrón más estrecho que se ajuste al despliegue.

Medio ambiente Patrón preferido Cadena de conexión principal
SQL Server en Windows bajo un dominio o identidad local de Windows Autenticación integrada de Windows Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
Estación de trabajo de desarrollador conectándose a base de datos SQL en Microsoft Fabric Cadena de credenciales por defecto de Microsoft Entra ID Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Aplicación alojada en Azure y conectada a Azure SQL Identidad administrada de Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
Estación de trabajo del desarrollador conectada a Azure SQL Cadena de credenciales por defecto de Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Herramienta interactiva de escritorio que se conecta a Azure SQL Autenticación interactiva de Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
Entorno que requiere autenticación SQL Nombre de usuario y contraseña de una tienda secreta Server=<server>;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true

Microsoft.Data.SqlClient 7.0 y versiones posteriores requieren el paquete Microsoft.Data.SqlClient.Extensions.Azure de la misma versión para los modos de autenticación de Microsoft Entra ID proporcionados por el controlador. No necesitas esa extensión cuando el código de la aplicación proporciona un token de acceso o una función de devolución de llamada para el token de acceso.

La autenticación también requiere usuarios en el lado de la base de datos, permisos y configuración de identidad. Para la matriz completa de elecciones y configuración, véase la autenticación Microsoft Entra ID y la autenticación de SQL Server.

Especificar el servidor y la base de datos

Usar Server y Database como nombres de palabras clave canónicas. El controlador también acepta alias como Data Source para Server y Initial Catalog para Database.

Los formularios comunes de servidores incluyen:

Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB

Prefiero un protocolo explícito, nombre de host y puerto para conexiones TCP de producción. Utiliza un nombre DNS estable que coincida con el certificado del servidor en lugar de una dirección IP.

Para un agente de escucha de un grupo de disponibilidad, un grupo de conmutación por error, el punto de conexión de Azure SQL u otro punto de conexión TCP con varias direcciones, revisa también MultiSubnetFailover en Opciones de conexión.

Configurar el cifrado y la validación de certificados

Microsoft.Data.SqlClient 4.0 y las versiones posteriores usan de forma predeterminada Encrypt en lugar de true. Microsoft.Data.SqlClient 5.0 y versiones posteriores también admiten Encrypt=Strict para servidores que negocian TDS 8.0.

Uso:

  • Encrypt=Strict cuando el servidor soporta TDS 8.0 y tiene un certificado que el cliente puede validar.
  • Encrypt=true para conexiones cifradas a otros servidores soportados.
  • TrustServerCertificate=false, el valor predeterminado, para la validación de certificados de producción.

No la uses TrustServerCertificate=true como una solución general de conexión. Cifra el canal pero omite la validación de identidad del servidor. Limítalo a entornos de desarrollo controlados donde no haya un certificado de confianza disponible.

Para requisitos de servidor, comportamiento de versiones y opciones de certificados, consulte Cifrado y validación de certificados.

Comprender la sintaxis de la cadena de conexión

Una cadena de conexión es una lista delimitada por punto y coma de pares de palabras clave y valores:

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

Siga estas reglas:

  • Los nombres de palabras clave no son sensibles a mayúsculas y minúsculas.
  • Los valores pueden distinguir entre mayúsculas y minúsculas.
  • Un punto y coma final es opcional.
  • Cita un valor con comillas simples o dobles cuando contiene un punto y coma o un espacio en blanco inicial o final.
  • Evita la cotización que encierra un valor duplicándolo.
  • No uses palabras clave duplicadas. El analizador utiliza el último valor, lo que dificulta la revisión de la configuración efectiva.

El conjunto de palabras clave y alias aceptados pertenece al proveedor. Una cadena de conexión aceptada por Microsoft.Data.SqlClient puede no funcionar con System.Data.SqlClient ni con otro proveedor de datos.

Construye cadenas de conexión de forma segura

Úsalo SqlConnectionStringBuilder cuando el código necesite añadir, validar o reemplazar valores. No concatenes valores no confiables en una cadena de conexión.

string baseConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    ApplicationName = "Orders.Api",
    ConnectTimeout = 30,
};

string connectionString = builder.ConnectionString;

El constructor:

  • Rechaza palabras clave no soportadas y valores inválidos.
  • Asocia alias con propiedades canónicas.
  • Entrecomilla los valores cuando sea necesario.
  • Impide que un valor inyecte otra palabra clave.

El generador no protege una contraseña ni un token una vez que entran en la memoria del proceso. Tampoco decide si un servidor, identidad o configuración de certificado es segura.

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

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

Mantén estas reglas:

  • No commitas contraseñas, secretos de clientes, tokens de acceso ni cadenas de conexión de producción.
  • Prefiero un método de autenticación basado en identidad que no requiera 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.
  • Deje Persist Security Info=false, el valor predeterminado, para que una conexión abierta no exponga valores confidenciales a través de su cadena de conexión.

Para proveedores de configuración .NET, véase Configuración en .NET. Para controles adicionales, consulte Proteger información de conexión.

Mantén estables las claves del pool

La agrupación de conexiones utiliza una configuración exacta de la conexión como parte de la clave del grupo. Las cadenas equivalentes pueden crear pools separados cuando su texto difiere, incluso cuando aparecen palabras clave en un orden diferente.

Crea una cadena de conexión canónica al iniciar la aplicación y reutilízala. No añadas IDs de solicitud, nombres de usuario, tokens de acceso u otros valores por solicitud a la cadena. Para las reglas clave completas, véase 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.

Requirement Configurar en
Tiempo permitido para establecer una conexión o obtenerla del grupo Connect Timeout Opción de conexión
Tiempo de espera predeterminado para la ejecución de comandos Command Timeout Opción de conexión, cuando la versión del controlador es compatible
Tiempo de espera para un comando CommandTimeout
Cancelación por parte del llamante CancellationToken pasado a APIs asíncronas
Política de reintento para abrir una conexión o ejecutar un comando Lógica de reintento configurable en SqlConnection o SqlCommand

No consideres un tiempo de espera más largo como un mecanismo de reintento. Un tiempo muerto limita una espera. Un reintento supone un nuevo intento y debe estar acotado y ser seguro de repetir.

Revisar el comportamiento dependiente de la versión

Versión del controlador Cambio de cadena de conexión
4.0 Encrypt se establece de forma predeterminada en true.
5.0 Encrypt=Strict y HostNameInCertificate están disponibles. SqlConnectionStringBuilder.Encrypt usa SqlConnectionEncryptOption.
5,1 ServerCertificate puede comparar el certificado del servidor con un archivo.
5.2 AccessTokenCallback está disponible para tokens renovables proporcionados por la aplicación.
7.0 La autenticación de Microsoft Entra ID proporcionada por el controlador pasa a Microsoft.Data.SqlClient.Extensions.Azure.
7.0.2 El controlador principal y sus paquetes complementarios utilizan versiones alineadas.

Utiliza una versión estable de drivers compatible y lee las notas de la versión antes de una actualización. Para las versiones actuales, véase ciclo de vida del soporte de controladores SqlClient.

Contenido relacionado

  • Last updated on