Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
S’applique à : 
.NET Framework .NET Standard
La classe AppContext permet à SqlClient de fournir de nouvelles fonctionnalités tout en continuant à prendre en charge les appelants qui dépendent du comportement précédent. Les utilisateurs peuvent refuser un changement de comportement en définissant des commutateurs AppContext spécifiques.
SqlClient lit et met en cache chaque commutateur la première fois qu’il utilise ce commutateur. Réglez les commutateurs au démarrage de l’application, avant d’utiliser les types de SqlClient. Changer un commutateur après que SqlClient ait mis sa valeur en cache n’a aucun effet.
Activer MultiSubnetFailover par défaut
S’applique à : .NET Framework ; .NET ; .NET Standard
(Disponible à partir de la version 7.0)
Pour définir MultiSubnetFailover=true globalement sans modifier les chaînes de connexion individuelles, réglez le commutateur Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault AppContext sur true au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault", true);
Vous pouvez également activer ce commutateur dans votre app.Config :
<runtime>
<AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault=true" />
</runtime>
Lorsqu'elle est activée, toutes les connexions se comportent comme si MultiSubnetFailover=true était défini dans la chaîne de connexion. Ce commutateur est désactivé par défaut.
Activer le multiplexage de paquets pour les lectures asynchrones
S’applique à : .NET Framework ; .NET ; .NET Standard
(Disponible à partir de la version 7.0)
Le multiplexage de paquets améliore les performances des opérations de lecture asynchrones volumineuses telles que ExecuteReaderAsync les jeux de résultats volumineux, les scénarios de diffusion en continu ou la récupération de données en bloc. Cette fonctionnalité est contrôlée par deux commutateurs AppContext opt-in. Le réglage des deux commutateurs sur false active le nouveau chemin de traitement asynchrone.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);
Par défaut, les deux commutateurs sont true, qui conserve le comportement existant (compatible).
Activer l’extension de fonctionnalité de l’agent utilisateur
S’applique à : .NET Framework ; .NET ; .NET Standard
(Disponible à partir de la version 7.0)
Lorsque l’interrupteur Switch.Microsoft.Data.SqlClient.EnableUserAgent AppContext est activé, le pilote envoie les détails de l’agent utilisateur au serveur dans le cadre de la connexion. Ces informations aident à résoudre les problèmes et à quantifier l’utilisation des pilotes par version et système d’exploitation. Ce commutateur est désactivé par défaut. Pour l’activer, définissez le commutateur AppContext à true au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableUserAgent", true);
Activer le comportement de troncation décimale
S’applique à : .NET Framework ; .NET ; .NET Standard
À compter de la version 2.0 de Microsoft.Data.SqlClient, les données décimales sont arrondies par défaut, comme le fait SQL Server. Pour permettre le comportement précédent de troncature, vous pouvez définir le commutateur Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal AppContext sur true au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);
Activer la mise en réseau managée sur Windows
S’applique à : .NET ; .NET Standard
(Disponible à partir de la version 2.0)
Sur Windows, SqlClient utilise une implémentation native de l’interface réseau SNI par défaut. Pour permettre l’utilisation d’une implémentation SNI gérée, réglez le commutateur Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows AppContext sur true au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);
Ce commutateur modifie le comportement du pilote de façon à utiliser une implémentation réseau gérée dans les projets .NET Core 2.1 (et versions ultérieures) et .NET Standard 2.0 (et versions ultérieures) sur Windows, éliminant ainsi toutes les dépendances vis-à-vis de bibliothèques natives pour la bibliothèque Microsoft.Data.SqlClient. Il sert uniquement aux tests et au débogage.
Remarque
Il existe des différences connues par rapport à l’implémentation native. Par exemple, l'implémentation gérée ne prend pas en charge l'authentification Windows hors domaine.
Désactiver la résolution transparente de l’adresse IP réseau
S’applique à : .NET Framework
La résolution d’adresses IP réseau transparente (TNIR) est une révision de la fonctionnalité MultiSubnetFailover existante. TNIR affecte la séquence de connexion du pilote dans le cas où la première adresse IP résolue du nom d’hôte ne répond pas et qu’il existe plusieurs adresses IP associées au nom d’hôte. La combinaison de TransparentNetworkIPResolution et MultiSubnetFailover sélectionne la séquence de connexion :
| TransparentNetworkIPResolution | MultiSubnetFailover | Séquence de connexion |
|---|---|---|
| Vrai | Vrai |
TransparentNetworkIPResolution est ignoré. Le pilote tente en parallèle les adresses IP résolues par DNS et complète l’authentification avec le premier intervenant. |
| Vrai | Faux | Le pilote effectue plusieurs cycles de connexion sur les adresses IP résolues par DNS, avec un minimum de 500 millisecondes lors de la première tentative et des délais d’attente progressivement plus grands par tentative, jusqu’à ce qu’une connexion réussisse ou que le total Connect Timeout soit atteint. |
| Faux | Vrai | Le pilote tente en parallèle les adresses IP résolues par DNS et complète l’authentification avec le premier intervenant. |
| Faux | Faux | Le pilote tente chaque adresse IP résolue par DNS de manière séquentielle jusqu’à ce qu’une adresse réussisse ou Connect Timeout soit atteinte. |
TransparentNetworkIPResolutionest activé par défaut sur le cadre .NET, et MultiSubnetFailover est désactivé par défaut. Sur .NET 5 et versions ultérieures, TransparentNetworkIPResolution ce n'est pas un mot-clé de chaîne de connexion reconnu et le définir (avec n'importe quelle valeur) projette ArgumentException (KeywordNotSupported). Ces versions prennent uniquement en compte MultiSubnetFailover. Le reste de cette section (le remplacement automatique, les modes de défaillance dans l’avertissement suivant, et l’interrupteur AppContext) s’applique au cadre .NET.
Conseil / Astuce
Défini MultiSubnetFailover=True sur chaque chaîne de connexion, quelle que soit la version .NET ou que la cible soit Azure SQL ou SQL Server sur site.
MultiSubnetFailover=True sélectionne un mode de connexion parallèle qui permet de trouver rapidement la première réplique qui répond. Sur .NET Framework, cela contourne également la boucle de nouvelles tentatives séquentielles par adresse IP de TNIR, qui est une cause courante de longs délais de connexion et d’expirations du délai de négociation avant authentification.
Sur .NET Framework, lorsque TransparentNetworkIPResolution n'est pas spécifié dans la chaîne de connexion, le pilote désactive automatiquement TNIR lorsque la source de données est un point de terminaison Azure SQL reconnu, lorsque la clé Authentication est définie sur l'une des méthodes Microsoft Entra ID (Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principal, Active Directory Device Code Flow, Active Directory Managed Identity, Active Directory MSI, Active Directory Default ou Active Directory Workload Identity), ou lorsque la propriété SqlConnection.AccessToken est définie. Pour les suffixes de terminaison reconnus par le pilote, voir l’entrée TransparentNetworkIPResolution dans SqlConnection.ConnectionString.
Une valeur explicite TransparentNetworkIPResolution contourne ce comportement automatique : True active le TNIR, et False désactive le TNIR sans condition. Pour rétablir le comportement automatique, supprimez le mot-clé de la chaîne de connexion. La dérogation automatique ne s'applique pas non plus lorsque la chaîne de connexion pointe vers Azure SQL via un nom personnalisé CNAME ou un nom DNS personnalisé dont le suffixe n'est pas reconnu comme un point de terminaison Azure SQL. Le override automatique cible spécifiquement Azure SQL ; il ne s'active pas pour le SQL Server sur site, donc TNIR est activé par défaut là-bas.
Délais de connexion longs sur le framework .NET
Sur .NET Framework, TransparentNetworkIPResolution=True (par défaut) peut entraîner de longs délais de connexion et des dépassements de délai lors de la négociation de préauthentification chaque fois que le nom DNS cible se résout en plusieurs adresses IP et que l’une des premières adresses IP est défaillante, obsolète ou inaccessible. TNIR essaie les adresses IP résolues de manière séquentielle et augmente le délai d’attente de chaque tentative à chaque tour jusqu’à ce que le Connect Timeout global soit atteint. Vous observez généralement un délai de connexion inattendu qui se termine par cette erreur :
Connection Timeout Expired. The timeout period elapsed while attempting to consume the pre-authentication handshake acknowledgement. This could be because the pre-authentication handshake failed or the server was unable to respond back in time.
Le motif apparaît dans plusieurs topologies :
- Azure SQL Database, Azure SQL Managed Instance, ou une base de données SQL dans Microsoft Fabric. La passerelle Azure SQL achemine chaque authentification vers une réplique de back-end. Lorsqu’une connexion routée échoue, TNIR réessaie le serveur principal routé sans revenir à la passerelle pour être rerouté, ce qui prolonge le délai pendant un basculement du serveur principal.
- SQL Server local derrière un écouteur de groupe de disponibilité Always On dont le nom DNS se résout en plusieurs adresses IP de réplica. Une entrée DNS obsolète ou une réplique IP malsaine est tentée séquentiellement avant que le TNIR n’atteigne une réplique fonctionnelle.
-
Instances de cluster de basculement avec un écouteur de cluster multisous-réseau, ou toute autre configuration dans laquelle le nom DNS cible comporte plusieurs enregistrements
A/AAAA, par exemple avec un DNS round-robin.
Pour éviter ce comportement, on définit MultiSubnetFailover=True dans la chaîne de connexion :
MultiSubnetFailover=True
Cette recommandation s’applique à toutes les versions .NET et couvre à la fois Azure SQL et SQL Server sur site. Lorsque MultiSubnetFailover=True, le pilote ignore TransparentNetworkIPResolution, tente en parallèle les adresses IP résolues par DNS et effectue l’authentification auprès de la première réplique à répondre. Malgré le nom, MultiSubnetFailover s’applique à tout écouteur dont le nom DNS se résout sur plusieurs IP cibles, que ces IP soient ou non dans des sous-réseaux différents, et il est sûr sur les serveurs autonomes dont le DNS se résout sur une seule IP.
Pour un contrôle à l’échelle du processus sans modifier chaque chaîne de connexion, utilisez l’option Enable MultiSubnetFailover par défaut avec l’interrupteur AppContext.
Désactiver TNIR avec un commutateur AppContext
Pour inverser la valeur par défaut de TransparentNetworkIPResolution de true à false sur .NET Framework, définissez le commutateur AppContext Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString sur true au démarrage de l’application. Ce commutateur ne modifie la valeur par défaut que lorsquTransparentNetworkIPResolution'elle n'est pas dans la chaîne de connexion ; il ne remplace pas une valeur explicite.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);
Pour plus d’informations sur la définition de ces propriétés, consultez la documentation relative à la propriété SqlConnection.ConnectionString.
Activation d’un délai d’expiration minimal pendant la connexion
S’applique à : .NET Framework ; .NET ; .NET Standard
Pour éviter qu’une tentative de connexion n’attende indéfiniment, vous pouvez définir le commutateur Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin AppContext sur true au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);
Désactivation du comportement de blocage de ReadAsync
S’applique à : .NET Framework ; .NET ; .NET Standard
À partir de la version 3.0, ReadAsync s’exécute de manière asynchrone. Les versions précédentes exécutent ReadAsync en synchrone et bloquent le thread d’appel sur .NET Framework. Pour contrôler ce comportement de blocage, réglez le commutateur Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking AppContext sur true ou false au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);
Activer le comportement de valeur NULL pour rowversion
S’applique à : .NET Framework ; .NET ; .NET Standard
À partir de la version 3.0, lorsqu’une rowversion a une valeur nulle, SqlDataReader elle retourne une DBNull valeur au lieu d’une valeur vide byte[]. Pour activer le comportement hérité consistant à retourner une valeur byte[] vide, activez le commutateur AppContext Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior au démarrage de l’application.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);
Supprimer l’avertissement TLS non sécurisé
S’applique à : .NET Framework ; .NET ; .NET Standard
(Disponible à partir de la version 4.0.1)
Lors de l’utilisation Encrypt=false de la chaîne de connexion, la console affiche un avertissement de sécurité si la version TLS est 1.2 ou inférieure. Supprimez cet avertissement en activant le commutateur AppContext suivant au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);
Ignorer le partenaire de basculement fourni par le serveur
S’applique à : .NET Framework ; .NET ; .NET Standard
(Disponible à partir des versions 5.1.8, 6.0.4 et 6.1.3)
Lors du basculement, les informations du partenaire de basculement fournies par le serveur sont préférées aux informations du partenaire de basculement fournies dans la chaîne de connexion. Pour ignorer les informations du partenaire de basculement fournies par le serveur et envisager uniquement les informations du partenaire de basculement fournies dans la chaîne de connexion, activez ce commutateur AppContext au démarrage de l’application :
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner", true);
Appliquer le délai d’inactivité de la connexion
S’applique à : .NET Framework ; .NET ; .NET Standard
À partir de la version 7.1.0-preview2, le Connection Idle Timeout mot-clé chaîne de connexion configure la durée d’inactivité en secondes, après quoi une connexion regroupée devient éligible à l’expulsion (par défaut 300 ; une valeur de 0 désactive l’expiration d’idle). Une connexion éligible est supprimée lors d’une récupération ou d’une maintenance ultérieure, donc le timing exact peut varier selon la mise en œuvre du pool et la cadence de maintenance. Le mot-clé n’est appliqué que lorsque le comportement d’expiration d’inactivité hérité est désactivé. Avec le commutateur à sa valeur par défaut de true, le pool préserve le comportement historique et le mot-clé n’a aucun effet.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior", false);
Activez le pool de connexions V2
S’applique à : .NET Framework ; .NET ; .NET Standard
À partir de la version 6.1, SqlClient inclut une implémentation alternative expérimentale de pool de connexions (V2). Le pool V1 reste le modèle par défaut (le commutateur est par défaut à false). Pour rejoindre le pool V2, activez le commutateur Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2 AppContext au démarrage de l’application.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2", true);
Le pool de compte attend contre le délai d’attente de connexion
S’applique à : .NET Framework ; .NET ; .NET Standard
À partir de la version 7.1.0-preview2, le temps passé à attendre une connexion du pool peut être décompté du budget de Connect Timeout de l’appelant, de sorte que l’attente dans le pool et la tentative de connexion réseau partagent un délai d’expiration global. Lorsque le commutateur est réglé à sa valeur par défaut de false, les opérations du pool reçoivent un budget complet Connect Timeout et la tentative de connexion réseau reçoit un budget complet supplémentaire.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutForPoolWait", true);
Retour à l’alternance de basculement héritée en cas d’erreurs de connexion
S’applique à : .NET Framework ; .NET ; .NET Standard
À partir de la version 7.1.0-preview2, lorsqu’un basculement est configuré, SqlClient ne bascule plus vers le partenaire de basculement pour les erreurs SQL renvoyées lors de la phase de connexion. Pour revenir au comportement d’alternance hérité, activez le commutateur Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors AppContext au démarrage de l’application. L’interrupteur est par défaut sur false.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors", true);
Respecter une échelle de zéro explicite sur les paramètres vartime
S’applique à : .NET Framework ; .NET ; .NET Standard
Par défaut, SqlClient envoie une échelle de 7 lorsque vous définissez explicitement l’échelle à 0 pour datetime2, datetimeoffset ou paramètres de temps . Dans la version 6.0 ou ultérieure, réglez Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour sur false au démarrage de l’application pour préserver l’échelle explicite de 0. L’interrupteur est par défaut sur true.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false);