AppContext-Schalter in SqlClient

Gilt für: .NET Framework .NET .NET Standard

Herunterladen von ADO.NET

Die AppContext-Klasse ermöglicht SqlClient das Bereitstellen neuer Funktionen, während weiterhin Aufrufer unterstützt werden, die vom vorherigen Verhalten abhängen. Benutzer können sich gegen Änderungen am Verhalten entscheiden, indem Sie bestimmte AppContext-Optionen festlegen.

SqlClient liest und cachet jeden Switch beim ersten Mal, wenn er diesen Switch verwendet. Stelle Switches beim Anwendungsstart ein, bevor du irgendwelche SqlClient-Typen verwendest. Das Ändern eines Switches, nachdem SqlClient seinen Wert zwischengespeichert hat, hat keine Auswirkung.

Standardmäßiges Aktivieren von MultiSubnetFailover

Gilt für: .NET Framework; .NET; .NET Standard

(Ab Version 7.0 verfügbar)

Um MultiSubnetFailover=true global festzulegen, ohne einzelne Verbindungszeichenfolgen zu ändern, legen Sie den AppContext-Switch Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault beim Anwendungsstart auf true fest:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault", true);

Sie können diesen Schalter auch in Ihrer App.Config aktivieren:

<runtime>
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault=true" />
</runtime>

Wenn diese Option aktiviert ist, verhalten sich alle Verbindungen so, als ob MultiSubnetFailover=true in der Verbindungszeichenfolge gesetzt ist. Dieser Schalter ist standardmäßig deaktiviert.

Aktivieren von Paket-Multiplexing für asynchrone Lesevorgänge

Gilt für: .NET Framework; .NET; .NET Standard

(Ab Version 7.0 verfügbar)

Paket-Multiplexing verbessert die Leistung für große asynchrone Lesevorgänge, wie ExecuteReaderAsync, bei umfangreichen Resultsets, Streamingszenarien oder Massen-Datenabrufen. Dieses Feature wird von zwei Opt-In-AppContext-Schaltern gesteuert. Beide Schalter auf false setzen aktiviert den neuen asynchronen Verarbeitungspfad:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);

Standardmäßig sind beide Schalter true, wodurch das vorhandene (kompatible) Verhalten beibehalten wird.

Aktivieren Sie die Benutzer-Agent-Funktionserweiterung

Gilt für: .NET Framework; .NET; .NET Standard

(Ab Version 7.0 verfügbar)

Wenn der AppContext-Wechsel Switch.Microsoft.Data.SqlClient.EnableUserAgent aktiviert ist, sendet der Treiber die User-Agent-Daten als Teil der Verbindung an den Server. Diese Informationen helfen bei der Problembehandlung und Quantifizierung der Treibernutzung nach Version und Betriebssystem. Dieser Schalter ist standardmäßig deaktiviert. Um den AppContext-Schalter zu aktivieren, legen Sie ihn beim Start der Anwendung auf true fest:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableUserAgent", true);

Aktivieren des Dezimalabkürzungsverhaltens

Gilt für: .NET Framework; .NET; .NET Standard

Ab Microsoft.Data.SqlClient 2.0 werden Dezimaldaten wie bei SQL Server standardmäßig gerundet. Um das vorherige Verhalten des Abschneidens zu aktivieren, können Sie beim Anwendungsstart den AppContext-Schalter Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal auf true setzen:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Aktivieren von verwalteten Netzwerken unter Windows

Gilt für: .NET; .NET Standard

(Verfügbar ab Version 2.0)

Unter Windows verwendet SqlClient standardmäßig eine native Implementierung der SNI-Netzwerkschnittstelle. Um die Nutzung einer verwalteten SNI-Implementierung zu ermöglichen, setzen Sie den AppContext-Schalter Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows auf true beim Anwendungsstart:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

Diese Option schaltet das Verhalten des Treibers so um, dass in Projekten in .NET Core 2.1 und höher und in .NET Standard 2.0 und höher unter Windows eine verwaltete Netzwerkimplementierung verwendet wird. Dies beseitigt alle Abhängigkeiten von nativen Bibliotheken für die Microsoft.Data.SqlClient-Bibliothek. Die Option ist nur für Test- und Debugzwecke vorgesehen.

Transparente IP-Auflösung im Netzwerk deaktivieren

Gilt für: .NET Framework

Die transparente Netzwerk-IP-Adressauflösung (Transparent Network IP Resolution, TNIR) ist eine Überarbeitung des vorhandenen MultiSubnetFailover-Features. TNIR wirkt sich auf die Verbindungssequenz des Treibers aus, wenn die erste aufgelöste IP-Adresse des Hostnamens nicht reagiert und dem Hostnamen mehrere IP-Adressen zugeordnet sind. Die Kombination von TransparentNetworkIPResolution und MultiSubnetFailover wählt die Verbindungssequenz:

TransparentNetworkIPResolutionist standardmäßig auf .NET Framework aktiviert und MultiSubnetFailover standardmäßig deaktiviert. Auf .NET 5 und neueren Versionen TransparentNetworkIPResolution ist kein anerkanntes Verbindungsstring-Schlüsselwort und das Setzen dieser (mit beliebigem Wert) wirft ArgumentException (KeywordNotSupported). Diese Versionen berücksichtigen nur MultiSubnetFailover. Der Rest dieses Abschnitts (die automatische Überschreibung, die Fehlermodi in der folgenden Warnung und der AppContext-Wechsel) gilt für das .NET Framework.

Wenn unter .NET Framework TransparentNetworkIPResolution nicht in der Verbindungszeichenfolge angegeben ist, deaktiviert der Treiber TNIR automatisch, wenn die Datenquelle ein erkannter Azure SQL-Endpunkt ist, wenn der Schlüssel Authentication auf eine beliebige Microsoft Entra ID-Methode festgelegt ist (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 oder Active Directory Workload Identity), oder wenn die Eigenschaft SqlConnection.AccessToken festgelegt ist. Für die Endpunkt-Suffixe, die der Treiber erkennt, siehe den TransparentNetworkIPResolution Eintrag in SqlConnection.ConnectionString.

Ein expliziter TransparentNetworkIPResolution Wert umgeht dieses automatische Verhalten: True aktiviert TNIR und False deaktiviert TNIR bedingungslos. Um das automatische Verhalten wiederherzustellen, entferne das Schlüsselwort aus der Verbindungszeichenfolge. Die automatische Überschreibung gilt auch nicht, wenn die Verbindungszeichenfolge über einen benutzerdefinierten CNAME- oder Vanity-DNS-Namen auf Azure SQL zeigt, dessen Suffix nicht als Azure SQL-Endpunkt erkannt wird. Die automatische Überschreibung zielt speziell auf Azure SQL ab; sie wird nicht für lokalen SQL Server ausgelöst, daher ist TNIR dort standardmäßig aktiviert.

Lange Verbindungsverzögerungen im .NET Framework

Unter .NET Framework kann TransparentNetworkIPResolution=True (die Standardeinstellung) immer dann zu langen Verbindungsverzögerungen und Timeouts beim Pre-Authentication-Handshake führen, wenn der Ziel-DNS-Name in mehrere IP-Adressen aufgelöst wird und eine der zuerst aufgelösten IP-Adressen fehlerhaft, veraltet oder nicht erreichbar ist. TNIR probiert die aufgelösten IP-Adressen der Reihe nach aus und erhöht in jeder Runde das Timeout pro Versuch, bis insgesamt Connect Timeout erreicht ist. Typischerweise beobachten Sie eine unerwartet lange Verbindungsverzögerung, die mit folgendem Fehler endet:

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.

Das Muster tritt in mehreren Topologien auf:

• Azure SQL-Datenbank, Azure SQL Managed Instance oder SQL database in Microsoft Fabric. Das Azure SQL-Gateway leitet jede Authentifizierung an ein Backend-Replikat. Wenn eine geroutete Verbindung ausfällt, versucht TNIR erneut, eine Verbindung mit dem gerouteten Backend herzustellen, ohne zum Gateway zurückzukehren, um erneut weitergeleitet zu werden, wodurch sich die Verzögerung während eines Backend-Failovers verlängert.
• Lokaler SQL Server hinter einem Listener einer Always On-Verfügbarkeitsgruppe, dessen DNS-Name in die IP-Adressen mehrerer Replikate aufgelöst wird. Ein veralteter DNS-Eintrag oder eine ungesunde Replik-IP wird sequentiell ausprobiert, bevor TNIR eine funktionierende Replik erreicht.
• Failover-Cluster-Instanzen mit einem Multi-Subnet-Cluster-Listener oder einer anderen Konfiguration, bei der der Ziel-DNS-Name mehrere A/AAAA Datensätze hat (wie DNS-Round-Robin).

Um dieses Verhalten zu vermeiden, setze MultiSubnetFailover=True in der Verbindungszeichenfolge:

MultiSubnetFailover=True

Diese Empfehlung funktioniert auf jeder .NET-Version und umfasst sowohl Azure SQL als auch den lokalen SQL Server. Wenn MultiSubnetFailover=True, ignoriert der Treiber TransparentNetworkIPResolution, versucht er die per DNS aufgelösten IP-Adressen parallel und schließt er die Authentifizierung mit der zuerst antwortenden Replik ab. Trotz des Namens MultiSubnetFailover gilt es für jeden Zuhörer, dessen DNS-Name auf mehrere Ziel-IPs aufgelöst wird, unabhängig davon, ob diese IPs sich in verschiedenen Subnetzen befinden, und es ist sicher auf eigenständigen Servern, deren DNS auf eine einzige IP aufgelöst wird.

Um die Steuerung prozessweit vorzunehmen, ohne jede Verbindungszeichenfolge bearbeiten zu müssen, verwenden Sie standardmäßig den AppContext-Schalter Enable MultiSubnetFailover.

Deaktivieren Sie TNIR mit einem AppContext-Schalter

Um den Standardwert von TransparentNetworkIPResolution von von true auf false im .NET Framework umzudrehen, setzen Sie den AppContext-Switch Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString auf true beim Anwendungsstart. Diese Option ändert den Standardwert nur, wenn TransparentNetworkIPResolution nicht in der Verbindungszeichenfolge enthalten ist; ein explizit angegebener Wert wird dadurch nicht überschrieben.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);

Weitere Informationen zum Festlegen dieser Eigenschaften finden Sie in der Dokumentation zur SqlConnection.ConnectionString-Eigenschaft.

Aktivieren eines minimalen Timeouts bei der Anmeldung

Gilt für: .NET Framework; .NET; .NET Standard

Um zu verhindern, dass ein Anmeldeversuch unbegrenzt wartet, können Sie den AppContext-Wechsel Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin auf true 'Beim Anwendungsstart' setzen:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);

Deaktivieren des blockierenden Verhaltens von ReadAsync

Gilt für: .NET Framework; .NET; .NET Standard

Ab Version 3.0 ReadAsync läuft sie asynchron. Frühere Versionen laufen ReadAsync synchron und blockieren den aufrufenden Thread auf .NET Framework. Um dieses Blockierungsverhalten zu kontrollieren, stellen Sie den AppContext-Schalter Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking auf true oder false beim Anwendungsstart ein:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);

Aktivieren Sie das NULL-Verhalten von rowversion

Gilt für: .NET Framework; .NET; .NET Standard

Ab Version 3.0 gibt eine Rowversion , wenn sie einen Nullwert hat, SqlDataReader einen DBNull Wert statt eines leeren byte[]zurück. Um das Legacyverhalten zu aktivieren, bei dem ein leeres byte[] zurückgegeben wird, aktivieren Sie beim Anwendungsstart den AppContext-Schalter Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);

Unterdrücken von Warnungen zu unsicherem TLS

Gilt für: .NET Framework; .NET; .NET Standard

(Verfügbar ab Version 4.0.1)

Beim Einsatz Encrypt=false im Verbindungszeichenfolge gibt die Konsole eine Sicherheitswarnung aus, wenn die TLS-Version 1.2 oder niedriger ist. Unterdrücken Sie diese Warnung, indem Sie beim AppContext-Start folgenden AppContext-Schalter aktivieren:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);

Ignoriere den vom Server bereitgestellten Failoverpartner

Gilt für: .NET Framework; .NET; .NET Standard

(Ab Version 5.1.8, 6.0.4 und 6.1.3 verfügbar)

Bei einem Failover werden die vom Server bereitgestellten Failover-Partnerinformationen gegenüber den in der Verbindungszeichenfolge angegebenen bevorzugt. Um Failoverpartnerinformationen vom Server zu ignorieren und nur Failoverpartnerinformationen in der Verbindungszeichenfolge zu berücksichtigen, aktivieren Sie diesen AppContext-Switch beim Starten der Anwendung:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner", true);

Erzwingen Sie das Verbindungs-Leerlauf-Timeout

Gilt für: .NET Framework; .NET; .NET Standard

Ab Version 7.1.0-preview2 konfiguriert das Schlüsselwort für die Verbindungszeichenfolge Connection Idle Timeout die Leerlaufdauer in Sekunden, nach deren Ablauf eine gepoolte Verbindung für das Entfernen infrage kommt (Standardwert: 300; ein Wert von 0 deaktiviert die Leerlaufzeitüberschreitung). Eine berechtigte Verbindung wird bei einem späteren Abruf- oder Wartungsdurchgang verworfen, sodass der genaue Zeitpunkt je nach Pool-Implementierung und Wartungsfrequenz variieren kann. Das Schlüsselwort wird nur erzwungen, wenn das alte Leerlauftimeoutverhalten deaktiviert ist. Mit dem Wechsel auf seinem Standardwert von truebewahrt der Pool das historische Verhalten und das Schlüsselwort hat keine Auswirkung.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior", false);

Aktivieren Sie den V2-Verbindungspool

Gilt für: .NET Framework; .NET; .NET Standard

Ab Version 6.1 enthält SqlClient eine alternative, experimentelle Connection Pool-Implementierung (V2). Der V1-Pool bleibt der Standard (der Schalter steht standardmäßig auf false). Um sich für den V2-Pool anzumelden, aktivieren Sie den AppContext-Wechsel Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2 , wenn die Anwendung startet.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2", true);

Zähler-Pool wartet auf Verbindungs-Timeout

Gilt für: .NET Framework; .NET; .NET Standard

Ab Version 7.1.0-Preview2 kann die Wartezeit auf eine Verbindung aus dem Pool auf das Connect Timeout Budget des Anrufers angerechnet werden, sodass Pool-Wartezeiten und der Netzwerkverbindungsversuch eine Gesamtzeitzeit teilen. Wenn der Switch auf seinen Standardwert false gesetzt ist, erhalten die Pooloperationen das volle Connect Timeout, und für den Netzwerkverbindungsversuch steht zusätzlich das volle Budget zur Verfügung.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutForPoolWait", true);

Bei Anmeldefehlern zur Legacy-Failover-Alteration zurücksetzen

Gilt für: .NET Framework; .NET; .NET Standard

Ab Version 7.1.0-Preview2 wechselt SqlClient beim Verbinden mit konfiguriertem Failover nicht mehr zum Failover-Partner, wenn SQL-Fehler während der Anmeldephase auftreten. Um zum alten Alternation-Verhalten zurückzuverkehren, aktivieren Sie den AppContext-Switch Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors beim Anwendungsstart. Der Schalter ist standardmäßig auf false eingestellt.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors", true);

Respektieren Sie eine explizite Nullskala bei den Variabelzeitparametern

Gilt für: .NET Framework; .NET; .NET Standard

Standardmäßig sendet SqlClient eine Skala von 7, wenn man die Skala explizit auf 0 für Datetime2, Datetimeoffset oder Zeitparameter setzt. Ab Version 6.0 oder höher setzen Sie Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour beim Start der Anwendung auf false, um die explizite Skalierung von 0 beizubehalten. Der Schalter ist standardmäßig auf true eingestellt.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false);

Verwandte Inhalte

• AppContext-Klasse