Options de connexion pour Microsoft. Data.SqlClient

Les options de connexion de Microsoft.Data.SqlClient déterminent la manière dont le pilote établit, identifie, achemine, relance et gère la mise en pool des connexions. Définissez-les dans une chaîne de connexion ou via les propriétés SqlConnectionStringBuilder correspondantes.

Pour l’authentification Microsoft Entra ID, voir authentification Microsoft Entra ID. Pour les paramètres TLS, voir Chiffrement et validation des certificats.

Définir des options avec SqlConnectionStringBuilder

Utilisez le constructeur au lieu de concaténer des fragments de chaîne de connexion :

var builder = new SqlConnectionStringBuilder
{
    DataSource = "tcp:sql.example.com,1433",
    InitialCatalog = "Orders",
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Mandatory,
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    ConnectRetryCount = 3,
    ConnectRetryInterval = 10,
    MultiSubnetFailover = true,
};

Le code utilise les noms des propriétés du constructeur. Les tableaux utilisent des orthographes courantes de chaîne de connexion. Le chauffeur accepte également des pseudonymes documentés.

Options de temps mort

Mot clé Par défaut Comportement Version
Connect Timeout 15 secondes Cela limite le temps nécessaire pour établir un lien. Lorsque le pool est à Max Pool Size, cela limite aussi l’attente pour une connexion poolée utilisable. Connection Timeout et Timeout sont des alias. Toutes les versions de Microsoft.Data.SqlClient
Command Timeout 30 secondes Définit le délai d’attente par défaut pour les commandes associées à la connexion. Définissez CommandTimeout sur une commande lorsqu’une opération nécessite une limite différente. Une valeur de 0 n’a pas de limite de temps et peut laisser le travail en attente indéfiniment. Microsoft. Data.SqlClient 2.1 et versions ultérieures

Les délais d’expiration de connexion et de commande concernent des opérations différentes. Connect Timeout ne limite pas l’exécution des requêtes. Command Timeout Cela ne limite pas l’authentification ni l’attente pour une connexion regroupée.

A CancellationToken est distinct des deux réglages. Passez-le à OpenAsync, à l’exécution des commandes et aux méthodes de lecture afin que l’appelant puisse cesser d’attendre avant l’expiration d’un délai d’attente.

Identité de charge de travail et options de routage

Mot clé Par défaut Comportement Version
Application Name Nom défini par le fournisseur Identifie la charge de travail lors des sessions SQL Server, de l’audit et du diagnostic. Utilisez un nom stable et de faible cardinalité pour chaque charge de travail déployée. Toutes les versions de Microsoft.Data.SqlClient
Application Intent ReadWrite ReadOnly demande le routage en intention de lecture lorsque la cible et le groupe de disponibilité sont configurés en ce sens. Cela ne rend pas les instructions SQL en lecture seule. Toutes les versions de Microsoft.Data.SqlClient

Application Intent=ReadOnly Normalement associé à un écouteur de groupe de disponibilité ou à un point de terminaison de service qui prend en charge le routage de lecture. Voir Haute disponibilité et reprise après sinistre.

Options réseau et paquets

Mot clé Par défaut Comportement Version
Packet Size 8 000 octets Définit la taille du paquet réseau Tabular Data Stream (TDS). Les valeurs prises en charge vont de 512 à 32 768 octets. Gardez le code par défaut sauf si les mesures de charge de travail et la configuration du serveur justifient un changement. Toutes les versions de Microsoft.Data.SqlClient
MultiSubnetFailover false Utilise des tentatives parallèles de connexion TCP vers les adresses IP renvoyées pour un point de terminaison à adresses multiples. Définissez-la sur true pour les points de terminaison Azure SQL, les écouteurs de groupe de disponibilité et les instances de cluster de basculement accessibles via TCP. Toutes les versions de Microsoft.Data.SqlClient

MultiSubnetFailover=true n’est pas pris en charge par des instances nommées, des protocoles non-TCP, du miroir de base de données ou des terminaux configurés avec plus de 64 adresses IP. C’est sûr pour un point de terminaison TCP monoIP.

Microsoft. Data.SqlClient 7.0 dispose également d’un commutateur AppContext à l’échelle du processus qui peut faire en sorte que chaque connexion se comporte comme si MultiSubnetFailover=true. La chaîne de connexion par défaut reste false quand cet interrupteur n'est pas activé. Voir les commutateurs AppContext dans SqlClient.

Options de regroupement

Mot clé Par défaut Comportement Version
Pooling true Réutilise les connexions physiques pour correspondre aux configurations de connexion. Désactivez-le uniquement à des fins de diagnostic ou pour une charge de travail maîtrisée qui ne peut pas être mutualisée en toute sécurité. Toutes les versions de Microsoft.Data.SqlClient
Min Pool Size 0 Maintient au moins ce nombre de connexions physiques dans le pool après sa création. Une valeur positive peut maintenir les sessions de base de données ouvertes jusqu’à la fin du pool ou du processus. Toutes les versions de Microsoft.Data.SqlClient
Max Pool Size 100 Plafonne les connexions physiques au sein d’un même pool. Les requêtes attendent jusqu’à Connect Timeout lorsque le pool est plein. Toutes les versions de Microsoft.Data.SqlClient
Load Balance Timeout 0 secondes Une connexion est supprimée lorsqu’elle retourne au pool si son âge dépasse cette valeur. Connection Lifetime est un alias. 0 Désactive le retrait basé sur l’âge. Toutes les versions de Microsoft.Data.SqlClient
Pool Blocking Period Auto Contrôle si le pool relance temporairement une erreur de connexion mise en cache. Auto désactive la période de blocage pour les points de terminaison Azure SQL reconnus et l’active pour les autres points de terminaison. Toutes les versions de Microsoft.Data.SqlClient
Enlist true Insère automatiquement une connexion ouverte dans la transaction ambiante System.Transactions . Toutes les versions de Microsoft.Data.SqlClient

Les paramètres du pool s’appliquent à chaque pool distinct, pas à l’ensemble du processus ou du serveur de base de données. Avant de relever Max Pool Size, confirmez que les connexions et les lecteurs sont rapidement éliminés et que la base de données peut accepter le total résultant pour chaque instance d’application.

Pour les clés du pool, le comportement des jetons d’authentification, les périodes de blocage, l’effacement et les diagnostics, voir le pool de connexions SQL Server.

Options de récupération de connexion

Mot clé Par défaut Comportement Version
Connect Retry Count 1 Fixe le nombre de tentatives pour les échecs transitoires qualifiés lors de la connexion initiale et pour rétablir une connexion inactive cassée. La valeur par défaut effective est 2 pour les points de terminaison Azure SQL reconnus et 5 pour les points de terminaison Azure Synapse reconnus et à la demande. 0 désactive ces nouvelles tentatives. Toutes les versions de Microsoft.Data.SqlClient
Connect Retry Interval 10 secondes Définit le délai avant les tentatives ultérieures de connexion initiale ou de récupération au repos. Les valeurs valides sont de 1 à 60 secondes. Toutes les versions de Microsoft.Data.SqlClient

La première tentative lors de la récupération de la connexion est immédiate. Connect Retry Interval s’applique avant toute tentative ultérieure. Pour contourner la tentative ouverte initiale intégrée pour une opération, utilisez une surcharge ouverte avec OpenWithoutRetry.

Ces mots-clés ne réessaient pas une commande qui échoue pendant qu’elle est en cours d’exécution. Utilisez une logique de réessayage configurable pour une politique d’ouverture ou de commande personnalisée. Réessayez les commandes uniquement si la répétition de leurs effets est sans danger.

Options d’identité et de certificat du serveur

Ces options répondent à des exigences spécifiques en matière de certificat ou de nommage Kerberos. Ils ne remplacent pas l’authentification et la validation de certificats normales.

Mot clé Par défaut Comportement Version
Host Name In Certificate Nom de l’hôte serveur Fournit le Nom Commun (CN) ou le Nom Alternatif de Sujet (SAN) attendu lorsque la connexion utilise un alias DNS différent du certificat. Microsoft. Data.SqlClient 5.0 et versions ultérieures
Server Certificate Vide Fournit un fichier PEM, DER ou CER qui doit correspondre exactement au certificat serveur lorsque Encrypt=Mandatory ou Encrypt=Strict. Microsoft. Data.SqlClient 5.1 et versions ultérieures
Server SPN Dérivé du nom du serveur Supprime le nom principal de service (SPN) utilisé pour l’authentification intégrée du serveur principal. Configurez-le uniquement lorsque la convention de nommage Kerberos utilisée nécessite un SPN explicite. Microsoft. Data.SqlClient 5.0 et versions ultérieures
Failover Partner SPN Dérivé du partenaire de basculement Remplace le SPN d’un partenaire de basculement pour la mise en miroir de bases de données. La mise en miroir de bases de données est déconseillée. Utilisez les groupes de disponibilité pour les nouveaux déploiements. Microsoft. Data.SqlClient 5.0 et versions ultérieures

Host Name In Certificate Modifie le nom utilisé pour la correspondance des certificats. Il ne fait pas confiance à un émetteur non fiable. Server Certificate fixe un fichier de certificat spécifique et nécessite une mise à jour de l’application lorsque ce certificat est renouvelé.

Des overrides SPN incorrectes peuvent empêcher l’authentification Kerberos ou affaiblir la vérification d’identité prévue. Corrigez l’enregistrement DNS et SPN au lieu de définir des overrides quand c’est possible.

Garde les cordes de connexion petites. Ajoutez une option uniquement lorsque vous pouvez indiquer quel comportement il change et comment la charge de travail le vérifie.

Modifications des options de révision

Avant de changer une option en production :

  1. Enregistrez la chaîne de connexion actuelle, la version du pilote, le type de terminaison et le problème observé.
  2. Changez un comportement à la fois.
  3. Test de l’établissement de la connexion, de l’authentification, de la validation des certificats, du pool de connexions, du basculement, de l’annulation et de l’exécution des requêtes.
  4. Mesurez les connexions physiques, les temps d’attente du pool, la latence des connexions et le nombre d’erreurs.
  5. Confirmez le réglage sur chaque instance déployée.

Les chaînes de connexion font partie de la clé du pool. Un déploiement par étapes peut temporairement créer à la fois des pools anciens et nouveaux, ce qui augmente le nombre total de connexions physiques à une base de données.

Contenu connexe

  • Last updated on