Verbindungsoptionen für Microsoft. Data.SqlClient

Microsoft. Data.SqlClient-Verbindungsoptionen steuern, wie der Treiber eine Verbindung aufbaut, identifiziert, routet, erneut versucht und zusammenführt. Legen Sie sie in einer Verbindungszeichenfolge oder über entsprechende SqlConnectionStringBuilder Eigenschaften fest.

Für die Microsoft Entra ID-Authentifizierung siehe Microsoft Entra ID Authentifizierung. Für TLS-Einstellungen siehe Verschlüsselung und Zertifikatsvalidierung.

Setze Optionen mit SqlConnectionStringBuilder

Verwenden Sie den Builder, anstatt Verbindungszeichenfolge-Fragmente zu verketten:

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,
};

Der Kodex verwendet Bauunternehmernamen. Die Tabellen verwenden gängige Verbindungszeichenfolge-Schreibweisen. Der Fahrer akzeptiert außerdem dokumentierte Aliasnamen.

Auszeitoptionen

Keyword Vorgabe Behavior Version
Connect Timeout 15 Sekunden Das begrenzt die Zeit, um eine Verbindung herzustellen. Wenn der Pool bei Max Pool Sizeist, begrenzt er auch die Wartezeit auf eine nutzbare Poolverbindung. Connection Timeout und Timeout sind Aliase. Alle Microsoft. Data.SqlClient-Versionen
Command Timeout 30 Sekunden Setzt das Standard-Timeout für Befehle, die mit der Verbindung verbunden sind. Legen Sie CommandTimeout für einen Befehl fest, wenn ein Vorgang ein anderes Limit benötigt. Ein Wert von 0 hat keine Zeitbegrenzung und kann die Arbeit unbegrenzt warten lassen. Microsoft. Data.SqlClient 2.1 und neuere Versionen

Verbindungs- und Befehls-Timeouts beziehen sich auf unterschiedliche Vorgänge. Connect Timeout schränkt die Abfrageausführung nicht ein. Command Timeout Das schränkt die Authentifizierung oder das Warten auf eine Pool-Verbindung nicht ein.

A CancellationToken ist von beiden Einstellungen getrennt. Übergebe es an OpenAsync, Befehlsausführung und Lesemethoden, damit der Aufrufer aufhören kann, vor Ablauf eines Timeouts zu warten.

Workload-Identität und Routing-Optionen

Keyword Vorgabe Behavior Version
Application Name Anbieterdefinierter Name Identifiziert die Arbeitsbelastung in SQL Server-Sitzungen, Audits und Diagnosen. Verwenden Sie für jede bereitgestellte Workload einen stabilen Namen mit geringer Kardinalität. Alle Microsoft. Data.SqlClient-Versionen
Application Intent ReadWrite ReadOnly fordert Read-Intent-Routing an, wenn Ziel und Verfügbarkeitsgruppe dafür konfiguriert sind. SQL-Anweisungen werden dadurch nicht schreibgeschützt. Alle Microsoft. Data.SqlClient-Versionen

Application Intent=ReadOnly wird normalerweise mit einem Verfügbarkeitsgruppen-Listener oder einem Dienstendpunkt kombiniert, der Leserouting unterstützt. Siehe Hohe Verfügbarkeit und Katastrophenwiederherstellung.

Netzwerk- und Paketoptionen

Keyword Vorgabe Behavior Version
Packet Size 8.000 Bytes Legt die Paketgröße des Tabular Data Stream (TDS) im Netzwerk fest. Unterstützte Werte sind 512 bis 32.768 Bytes. Behalten Sie den Standard, es sei denn, Arbeitslastmessungen und Serverkonfiguration rechtfertigen eine Änderung. Alle Microsoft. Data.SqlClient-Versionen
MultiSubnetFailover false Verwendet parallele TCP-Verbindungsversuche zu den IP-Adressen, die für einen Endpunkt mit mehreren Adressen zurückgegeben werden. Stellen Sie es für Azure SQL-Endpunkte, Verfügbarkeitsgruppen-Listener und Failover-Cluster-Instanzen, die über TCP erreicht werden, auf true ein. Alle Microsoft. Data.SqlClient-Versionen

MultiSubnetFailover=true wird nicht mit benannten Instanzen, Nicht-TCP-Protokollen, Datenbankspiegelung oder Endpunkten mit mehr als 64 IP-Adressen unterstützt. Es ist sicher für einen TCP-Endpunkt mit nur einer IP.

Microsoft. Data.SqlClient 7.0 verfügt außerdem über einen prozessweiten AppContext-Schalter, der jede Verbindung so verhalten lassen kann, als ob MultiSubnetFailover=true. Die Standardverbindungszeichenfolge bleibt false, wenn dieser Schalter nicht aktiviert ist. Siehe AppContext-Switches in SqlClient.

Optionen für das Pooling

Keyword Vorgabe Behavior Version
Pooling true Nutzt physische Verbindungen wieder, um die Verbindungskonfigurationen anzupassen. Deaktiviere es nur für Diagnosen oder eine gemessene Arbeitsbelastung, die nicht sicher zusammengefasst werden kann. Alle Microsoft. Data.SqlClient-Versionen
Min Pool Size 0 Es werden nach der Erstellung des Pools mindestens so viele physische Verbindungen in einem Pool beibehalten. Ein positiver Wert kann Datenbanksitzungen offenhalten, bis der Pool oder Prozess endet. Alle Microsoft. Data.SqlClient-Versionen
Max Pool Size 100 Begrenzt physische Verbindungen in einem Pool. Anfragen warten bis zu Connect Timeout, wenn der Pool voll ist. Alle Microsoft. Data.SqlClient-Versionen
Load Balance Timeout 0 Sekunden Verwirft eine Verbindung, wenn sie in den Pool zurückgegeben wird und ihr Alter diesen Wert überschreitet. Connection Lifetime ist ein Alias. 0 deaktiviert die altersbasierte Entfernung. Alle Microsoft. Data.SqlClient-Versionen
Pool Blocking Period Auto Legt fest, ob der Pool einen im Cache gespeicherten Anmeldefehler vorübergehend erneut ausgibt. Autodeaktiviert die Sperrperiode für erkannte Azure SQL-Endpunkte und aktiviert sie für andere Endpunkte. Alle Microsoft. Data.SqlClient-Versionen
Enlist true Nimmt eine geöffnete Verbindung automatisch in die umgebende Transaktion System.Transactions auf. Alle Microsoft. Data.SqlClient-Versionen

Pool-Einstellungen gelten für jeden einzelnen Pool, nicht für den gesamten Prozess oder Datenbankserver. Bevor Sie Max Pool Size erhöhen, stellen Sie sicher, dass Verbindungen und Reader-Objekte umgehend freigegeben werden und dass die Datenbank die daraus resultierende Gesamtzahl über alle Anwendungsinstanzen hinweg akzeptieren kann.

Für Poolschlüssel, Tokenverhalten, Blockierungsperioden, Löschen und Diagnostik siehe SQL Server Connection Pooling.

Verbindungswiederherstellungsoptionen

Keyword Vorgabe Behavior Version
Connect Retry Count 1 Setzt die Wiederholungsanzahl für die Qualifikation von transienten Fehlern während der Erstverbindung und für die Wiederherstellung einer unterbrochenen Leerlaufverbindung. Der effektive Standard gilt 2 für anerkannte Azure SQL-Endpunkte sowie 5 für anerkannte Azure Synapse- und On-Demand-Endpunkte. 0 Deaktiviert diese Wiederversuche. Alle Microsoft. Data.SqlClient-Versionen
Connect Retry Interval 10 Sekunden Legt die Verzögerung vor nachfolgenden anfänglichen Verbindungsversuchen oder Wiederherstellungsversuchen nach Leerlauf fest. Gültige Werte sind 1 bis 60 Sekunden. Alle Microsoft. Data.SqlClient-Versionen

Der erste Versuch während der Verbindungswiederherstellung erfolgt sofort. Connect Retry Interval gilt vor späteren Versuchen. Um den eingebauten Initial-Open-Retry für eine Operation zu umgehen, verwendet man eine offene Überlastung mit OpenWithoutRetry.

Diese Schlüsselwörter versuchen keinen Befehl erneut, der während der Ausführung fehlschlägt. Verwenden Sie konfigurierbare Wiederholungslogik für eine benutzerdefinierte Öffnungs- oder Befehlsrichtlinie. Befehle nur dann wiederholen, wenn es sicher ist, ihre Effekte zu wiederholen.

Serveridentität und Zertifikatsoptionen

Diese Optionen erfüllen spezifische Benennungsanforderungen für Zertifikate oder Kerberos. Sie ersetzen nicht die normale Authentifizierung und Zertifikatsvalidierung.

Keyword Vorgabe Behavior Version
Host Name In Certificate Hostname des Servers Liefert den erwarteten Common Name (CN) oder Subject Alternative Name (SAN), wenn die Verbindung ein DNS-Alias verwendet, das sich vom Zertifikat unterscheidet. Microsoft. Data.SqlClient 5.0 und neuere Versionen
Server Certificate Leer Stellt eine PEM-, DER- oder CER-Datei bereit, die genau mit dem Serverzertifikat übereinstimmen muss, wenn Encrypt=Mandatory oder Encrypt=Strict. Microsoft. Data.SqlClient 5.1 und spätere Versionen
Server SPN Abgeleitet vom Servernamen Überschreibt den Service Principal Name (SPN), der für die integrierte Authentifizierung des Primärservers verwendet wird. Konfigurieren Sie es nur, wenn die bereitgestellte Kerberos-Benennung eine explizite SPN erfordert. Microsoft. Data.SqlClient 5.0 und neuere Versionen
Failover Partner SPN Abgeleitet aus dem Failover-Partner Überschreibt den SPN eines Failoverpartners für die Datenbankspiegelung. Datenbankspiegelung ist veraltet. Nutze Verfügbarkeitsgruppen für neue Deployments. Microsoft. Data.SqlClient 5.0 und neuere Versionen

Host Name In Certificate ändert den Namen, der für den Zertifikatabgleich verwendet wird. Es vertraut einem nicht vertrauenswürdigen Emittenten nicht. Server Certificate pinnt eine exakte Zertifikatsdatei und benötigt ein Anwendungsupdate, wenn dieses Zertifikat rotiert.

Falsche SPN-Übersteuerungen können die Kerberos-Authentifizierung verhindern oder die beabsichtigte Identitätsprüfung schwächen. Beheben Sie DNS- und SPN-Registrierung, anstatt Overrides zu setzen, wenn möglich.

Halte die Verbindungsstränge klein. Füge eine Option nur hinzu, wenn du angeben kannst, welches Verhalten es ändert und wie die Arbeitslast dieses Verhalten überprüft.

Optionsänderungen überprüfen

Vor der Änderung einer Option in der Produktion:

  1. Notieren Sie den aktuellen Verbindungszeichenfolge, die Treiberversion, den Endpunkttyp und das beobachtete Problem.
  2. Ändere ein Verhalten nach dem anderen.
  3. Testen Sie den Verbindungsaufbau, die Authentifizierung, die Zertifikatsvalidierung, das Pooling, das Failover, den Abbruch und die Abfrageausführung.
  4. Messen Sie neue Verbindungen, Wartezeiten im Pool, Verbindungslatenz und Fehlerzahlen.
  5. Bestätigen Sie die Einstellung auf jeder bereitgestellten Instanz.

Verbindungsstrings sind Teil des Pool-Schlüssels. Ein stufenweiser Rollout kann vorübergehend sowohl alte als auch neue Pools erstellen, was die Gesamtzahl der physischen Datenbankverbindungen erhöht.

Verwandte Inhalte

  • Last updated on