Chaînes de connexion pour Microsoft.Data.SqlClient

Une chaîne de connexion Microsoft.Data.SqlClient est une liste de paires keyword=value séparées par des points-virgules. Passez-le à SqlConnection ou SqlConnectionStringBuilder:

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

Une chaîne de connexion répond à quatre questions :

1. Quel serveur et quelle base de données l’application utilise-t-elle ?
2. Sous quelle identité l’application s’exécute-t-elle ?
3. Comment le client valide-t-il le certificat serveur ?
4. De quel comportement de connexion la charge de travail a-t-elle besoin ?

Cet article traite de ces choix et des règles que le pilote utilise pour lire le texte. Pour chaque mot-clé, ses synonymes et ses valeurs par défaut, voir Options de connexion. Pour créer et modifier des chaînes de connexion dans le code, voir Constructeurs de chaînes de connexion.

Choisir un motif d’authentification

Utilisez le schéma qui correspond au déploiement. Remplacez chaque placeholder, comme <server>, par votre valeur.

L’authentification intégrée Windows se connecte sous l’identité du processus. Pour une application de bureau ou de console, c’est généralement l’utilisateur connecté. Pour une application web ou un service Windows, c'est le pool d'applications ou le compte de service. L’emprunt d’identité peut changer l’identité. Accordez un identifiant de connexion et des permissions de base de données à l’identité que votre application utilise réellement.

Ces trois formes d’authentification intégrée Windows sont équivalentes :

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 une chaîne définit Integrated Security=true et définit également User ID et Password, le pilote utilise l’authentification Windows et ignore le nom d’utilisateur et le mot de passe.

Microsoft. Data.SqlClient 7.0 et versions ultérieures nécessitent le package apparié Microsoft.Data.SqlClient.Extensions.Azure par version pour les méthodes d’authentification Microsoft Entra ID fournies par le pilote. Vous n’avez pas besoin de ce package lorsque le code applicatif fournit un jeton d’accès ou un callback de jeton d’accès.

Pour les valeurs acceptées Authentication , voir Options d’authentification. L’authentification nécessite également des utilisateurs de base de données, des permissions et une configuration d’identité sur le serveur. Pour les étapes de configuration, voir authentification Microsoft Entra ID et authentification SQL Server.

Spécifier le serveur et la base de données

Server et Database sont les noms de mots-clés les plus lisibles. Le générateur les écrit comme leurs équivalents canoniques, Data Source et Initial Catalog. Les quatre noms fonctionnent dans une chaîne de connexion.

Réglez Server sur l’une de ces formes :

Utilisez tcp:, un nom hôte pleinement qualifié, et un port explicite en production. Utilisez un nom DNS correspondant au certificat serveur, et non une adresse IP, car la validation du certificat compare le nom du serveur dans la chaîne de connexion avec les noms du certificat.

Lorsque vous vous connectez à Azure SQL Database avec une authentification SQL et un nom d’utilisateur sous la forme user@servername, la partie servername doit correspondre au serveur dans Server.

Pour un écouteur de groupe de disponibilité ou une instance de cluster de basculement, consultez également Multi Subnet Failover dans Options de connexion.

Configurer le chiffrement et la validation des certificats

Le Encrypt mot-clé accepte les valeurs suivantes, quelle que soit la casse :

Utilisez Strict lorsque le serveur supporte TDS 8.0 et possède un certificat que le client peut valider. Azure SQL Database et SQL Database dans Microsoft Fabric le supportent. Une connexion LocalDB n’est pas chiffrée, même avec Mandatory, et Strict échoue.

Les valeurs Encrypt et Trust Server Certificate se combinent comme suit :

Ne réglez Trust Server Certificate=true pas la correction d’une erreur de connexion en production. Il chiffre le canal mais ne confirme pas l’identité du serveur. Limitez-le aux environnements de développement où un certificat de confiance n’est pas disponible.

Lorsque le nom du serveur ne Data Source correspond pas au certificat, définissez Host Name In Certificate le nom dans le certificat. SqlClient ne le vérifie que lorsque le nom du serveur ne correspond pas, et il n’épingle pas de certificat. Pour accepter un seul certificat spécifique, réglez Server Certificate sur le chemin d’un fichier PEM, DER ou 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

Pour les règles complètes de validation, voir Chiffrement et validation des certificats.

Utiliser le regroupement de connexions

Le pooling est activé par défaut. Lorsque vous ouvrez un SqlConnection, le conducteur prend une connexion physique d’un pool qui correspond à la connexion. Lorsque vous fermez ou jetez la connexion, la connexion physique revient dans le pool au lieu de se fermer. L’ouverture d’un pool évite la connexion réseau, la poignée de main TLS et l’authentification.

Suivez ces règles :

• Ouvrez une connexion juste avant d’en avoir besoin, et libérez-la dès que vous avez terminé, avec using ou await using. Une connexion qui n’est pas éliminée reste vérifiée, et la piscine peut s’épuiser.

• Construis la chaîne de connexion une fois au démarrage et réutilise-la. La clé du pool inclut le texte exact de la chaîne de connexion, donc un ordre différent de mot-clé, un synonyme, ou une valeur par requête comme un identifiant de requête ou un nom d’utilisateur crée un pool séparé. Le constructeur écrit une forme canonique. Pour plus d’informations, voir Conserver une chaîne de connexion canonique.

• Attendez-vous à un pool séparé pour chaque identité Windows sous authentification intégrée, chaque SqlCredential instance et chaque AccessToken valeur. Utilisez une méthode fournie Authentication par le pilote ou une méthode réutilisée AccessTokenCallback au lieu de définir AccessToken pour chaque connexion.

• Cherchez les connexions qui ne sont pas éliminées avant de relever Max Pool Size, ce qui est par défaut à 100. Lorsque chaque connexion d’un pool est utilisée, Open attend jusqu’à Connect Timeout puis lance 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.
  

• Planification de la capacité des serveurs pour chaque pool. Chaque processus, ou chaque domaine d’application sur .NET Framework, possède ses propres pools. Les connexions au serveur peuvent atteindre Max Pool Size, multiplié par les pools de chaque processus et par le nombre d’instances d’application.

• Ne définissez pas Pooling=false pour contourner un problème de pooling. À chaque ouverture, une connexion complète est alors effectuée.

Pour fermer les connexions pooled qui restent inactives trop longtemps, voir Limiter le temps d’inactivité des connexions. Pour les clés de pool, le dimensionnement, la réinitialisation et les transactions, voir le pooling de connexions SQL Server.

Paramètres de connexion et de commande séparés

Une chaîne de connexion contrôle l’établissement de la connexion et le comportement de la session. Une commande contrôle une opération SQL.

Un temps d’attente plus long ne constitue pas une logique de nouvelle tentative. Un délai d’expiration limite une seule attente. Un réessai déclenche une autre tentative, et il doit être limité et sans risque d’être répété.

Déclarez l’identité de l’application

Application Name définit le nom que le serveur rapporte via APP_NAME(). Utilisez un nom stable pour chaque charge de travail déployée. Les frameworks et outils qui ouvrent des connexions pour une application peuvent également se déclarer via la propriété RegisteredApplication, qui n’a pas de mot-clé de chaîne de connexion. Pour plus d’informations, voir Signaler l’identité de l’application.

Construire des chaînes de connexion en toute sécurité

À utiliser SqlConnectionStringBuilder lorsque le code ajoute ou modifie une valeur. Ne rattachez pas de texte non fiable à une chaîne de connexion, car un point-virgule dans ce texte peut ajouter ou remplacer un mot-clé. Le constructeur valide les valeurs, associe les synonymes à des mots-clés canoniques, et met chaque valeur entre guillemets pour que la valeur ne puisse pas ajouter de mots-clés. Pour des exemples, voir Constructeurs de chaînes de connexion.

Stocker les informations de connexion en dehors du code

Chargez les chaînes de connexion depuis le système de configuration de l’application. Les applications .NET utilisent couramment des variables d’environnement, des secrets utilisateur pour le développement local, Azure App Configuration et Azure Key Vault.

Suivez ces règles :

• Ne validez pas dans le contrôle de code source les mots de passe, les clés secrètes client, les jetons d’accès ou les chaînes de connexion de production.
• Préférez une méthode d'authentification qui n'a pas besoin de mot de passe dans la chaîne de connexion.
• Restreignez l’accès à la source de configuration.
• Effectuez la rotation des secrets stockés, puis redémarrez ou rafraîchissez les applications qui les mettent en cache.
• N’écrivez pas de chaînes de connexion dans les logs, exceptions, traces ou télémétrie.
• Laissez Persist Security Info=false, la valeur par défaut, pour qu’une connexion ouverte n’expose pas le mot de passe via sa propriété ConnectionString.

Pour les fournisseurs de configuration .NET, voir Configuration en .NET. Pour plus d’options, voir Protéger les informations de connexion.

Règles d’analyse

Le conducteur applique ces règles :

• Les mots-clés ne sont pas sensibles à la casse. DATABASE, Database, et database sont le même terme de recherche.
• Beaucoup de mots-clés ont des synonymes. Server et Data Source fixent la même valeur. L’article Connection options liste les synonymes pour chaque mot-clé.
• Lorsqu’un mot-clé apparaît plusieurs fois, la dernière valeur l’emporte. Les synonymes comptent comme le même mot-clé.
• Le pilote ignore les espaces autour des mots-clés et autour des valeurs sans guillemets.
• Un point-virgule à la fin est optionnel.
• Un mot-clé que le pilote ne reconnaît pas génère ArgumentException avec le message Keyword not supported.

Les valeurs peuvent être sensibles à la majuscule, selon le mot-clé. Un mot de passe est sensible à la casse. Encrypt=STRICT et Encrypt=strict sont les mêmes.

Ce programme montre comment le builder normalise les mots-clés, résout un doublon et met entre guillemets les caractères spéciaux. L’onglet .NET Framework utilise C# 7.3. Pour créer un projet qui exécute les exemples, voir Créer le projet.

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 sortie est la suivante :

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 première ligne montre chaque synonyme remplacé par son mot-clé canonique : server par Data Source, DATABASE par Initial Catalog, uid par User ID, et timeout par Connect Timeout.

Valeurs du devis

Entourer une valeur entre guillemets doubles (") ou guillemets simples (') lorsqu’elle contient un point-virgule, commence ou se termine par un espace, ou commence ou se termine par un guillemet. Dans une valeur citée, écrivez deux fois le guillemet fermant.

Les règles de guillemets sont faciles à mal appliquer. Fixez les valeurs via les propriétés SqlConnectionStringBuilder et laissez le constructeur les mettre entre guillemets. Pour plus d’informations, voir Construire des chaînes de connexion en toute sécurité.

Spécifier les valeurs booléennes

Les mots-clés qui prennent une valeur booléenne acceptent true, false, yes et no, quelle que soit la casse. Integrated Security accepte sspiaussi , ce qui signifie true. Le constructeur écrit True ou False.

Utilisez des mots-clés provenant d’autres pilotes

Microsoft. Data.SqlClient n'accepte pas les mots-clés ODBC ou OLE DB tels que Driver et Provider. Supprimez ces mots-clés lorsque vous déplacez une chaîne de connexion d’un autre pilote. System.Data.SqlClientLes chaînes de connexion fonctionnent dans Microsoft. Data.SqlClient, avec ces différences :

• Encrypt prend par défaut la valeur Mandatory dans Microsoft.Data.SqlClient. Un serveur sans certificat fiable échoue à valider le certificat. Installez un certificat de confiance sur le serveur.
• Sur .NET, Network Library, Connection Reset, et Transparent Network IP Resolution ne sont pas pris en charge. Supprimez-les.
• Context Connection=true n’est pas pris en charge.
• Asynchronous Processing n’est pas un mot-clé pris en charge et génère ArgumentException. Supprimez-le. Les méthodes asynchrones n’en ont pas besoin.
• Type System Version=SQL Server 2000 n’est pas pris en charge. Créer la connexion génère ArgumentException. Utiliser Latest, SQL Server 2012, SQL Server 2008, ou SQL Server 2005.

Contenu connexe

• Utilisez Microsoft. Data.SqlClient dans une application .NET
• Options de connexion
• Générateurs de chaînes de connexion
• Se connecter à une source de données
• Pooling de connexions SQL Server
• Authentification avec Microsoft Entra ID
• Chiffrement et validation de certificat
• Instances d’utilisateur SQL Server Express
• Cycle de vie de prise en charge du pilote SqlClient