Opcje połączenia dla Microsoft. Data.SqlClient

Opcje połączenia Microsoft.Data.SqlClient określają, w jaki sposób sterownik ustanawia, identyfikuje, kieruje, ponawia i zarządza pulą połączeń. Ustaw je w ciągu połączenia lub za pomocą odpowiadających im właściwości SqlConnectionStringBuilder.

Informacje na temat uwierzytelniania Microsoft Entra ID można znaleźć w artykule uwierzytelnianie Microsoft Entra ID. Aby poznać ustawienia TLS, zobacz Szyfrowanie i walidacja certyfikatów.

Ustaw opcje za pomocą SqlConnectionStringBuilder

Użyj konstruktora zamiast łączenia fragmentów parametrów połączenia:

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

Kod wykorzystuje nazwy nieruchomości budowniczych. W tabelach stosuje się typowe warianty zapisu parametrów połączenia. Kierowca akceptuje również udokumentowane aliasy.

Opcje timeoutu

Keyword Default Behavior wersja
Connect Timeout 15 sekund Ogranicza to czas na nawiązanie więzi. Gdy pula jest na poziomie Max Pool Size, ogranicza to również czas oczekiwania na nadające się do użycia połączenie z puli. Connection Timeout i Timeout są aliasami. Wszystkie wersje Microsoft. Data.SqlClient
Command Timeout 30 sekund Ustawia domyślny limit czasu dla poleceń powiązanych z połączeniem. Ustaw CommandTimeout dla polecenia, jeśli jedna operacja wymaga innego limitu. Wartość 0 nie ma limitu czasu i może pozostawić zadanie w stanie oczekiwania bezterminowo. Microsoft. Data.SqlClient 2.1 i nowsze wersje

Limity czasu połączenia i polecenia dotyczą różnych operacji. Connect Timeout Nie ogranicza wykonywania zapytań. Command Timeout Nie ogranicza uwierzytelniania ani oczekiwania na połączenie w grupie.

CancellationToken jest oddzielne od obu ustawień. Przekaż go do OpenAsync, metod wykonywania poleceń oraz metod odczytu, aby wywołujący mógł przerwać oczekiwanie przed upływem limitu czasu.

Tożsamość obciążenia i opcje routingu

Keyword Default Behavior wersja
Application Name Nazwa zdefiniowana przez dostawcę Identyfikuje obciążenie w sesjach SQL Server, audytach i diagnostyce. Dla każdego wdrożonego obciążenia używaj jednej stabilnej nazwy o małej liczbie wariantów. Wszystkie wersje Microsoft. Data.SqlClient
Application Intent ReadWrite ReadOnly żąda kierowania połączeń z zamiarem odczytu, gdy replica docelowa i grupa dostępności są do tego skonfigurowane. Nie powoduje, że instrukcje SQL są tylko do odczytu. Wszystkie wersje Microsoft. Data.SqlClient

Application Intent=ReadOnly zazwyczaj łączy się z nasłuchiwaczem grupy dostępności lub punktem końcowym usługi, który obsługuje routowanie odczytu. Zobacz Wysoka dostępność i odzyskiwanie po awariach.

Opcje sieciowe i pakietowe

Keyword Default Behavior wersja
Packet Size 8 000 bajtów Ustala rozmiar pakietu sieciowego strumienia danych tabelarnych (TDS). Obsługiwane wartości to od 512 do 32 768 bajtów. Zachowaj domyślne ustawienia, chyba że pomiary obciążenia i konfiguracja serwera uzasadniają zmianę. Wszystkie wersje Microsoft. Data.SqlClient
MultiSubnetFailover false Wykorzystuje równoległe próby połączenia TCP z adresami IP zwracanymi dla wieloadresowego punktu końcowego. Ustaw tę wartość na true dla punktów końcowych Azure SQL, odbiorników grup dostępności i wystąpień klastrów trybu failover osiąganych przez protokół TCP. Wszystkie wersje Microsoft. Data.SqlClient

MultiSubnetFailover=true nie jest obsługiwany z nazwanymi instancjami, protokołami innymi niż TCP, dublowaniem bazy danych ani punktami końcowymi skonfigurowanymi z ponad 64 adresami IP. Jest bezpieczny dla punktu końcowego TCP z jednym IP.

Microsoft.Data.SqlClient 7.0 ma również przełącznik AppContext obejmujący cały proces, który może sprawić, że każde połączenie będzie się zachowywać tak, jakby MultiSubnetFailover=true. Domyślnie parametr połączenia pozostaje ustawiony na false, jeśli ten przełącznik nie jest włączony. Zobacz przełączniki AppContext w SqlClient.

Opcje łączenia

Keyword Default Behavior wersja
Pooling true Ponowne wykorzystanie fizycznych połączeń do dopasowania konfiguracji połączeń. Wyłączaj to tylko do celów diagnostycznych lub w przypadku ściśle określonego obciążenia, którego nie można bezpiecznie obsługiwać w puli. Wszystkie wersje Microsoft. Data.SqlClient
Min Pool Size 0 Utrzymuje przynajmniej tyle fizycznych połączeń w puli po jego utworzeniu. Wartość dodatnia może pozostawić sesje bazy danych otwarte aż do zakończenia działania puli lub procesu. Wszystkie wersje Microsoft. Data.SqlClient
Max Pool Size 100 Ustala limit fizycznych połączeń w obrębie jednej puli. Prośby czekają do Connect Timeout momentu, gdy pula jest pełna. Wszystkie wersje Microsoft. Data.SqlClient
Load Balance Timeout 0 Sekund Odrzuca połączenie, gdy wraca do puli, jeśli jego wiek przekracza tę wartość. Connection Lifetime jest aliasem. 0 wyłącza usuwanie na podstawie wieku. Wszystkie wersje Microsoft. Data.SqlClient
Pool Blocking Period Auto Określa, czy pula tymczasowo ponownie zgłasza zapisany w pamięci podręcznej błąd logowania. Autowyłącza okres blokowania dla uznanych punktów końcowych Azure SQL i włącza go dla innych punktów końcowych. Wszystkie wersje Microsoft. Data.SqlClient
Enlist true Automatycznie dołącza otwarte połączenie do bieżącej transakcji System.Transactions. Wszystkie wersje Microsoft. Data.SqlClient

Ustawienia puli dotyczą każdej odrębnej puli, a nie całego procesu czy serwera bazy danych. Przed wygenerowaniem Max Pool Size, upewnij się, że połączenia i czytniki są szybko usunięte oraz że baza danych może zaakceptować uzyskaną sumę dla każdej instancji aplikacji.

Aby uzyskać informacje o kluczach puli, zachowaniu tokenów, okresach blokowania, czyszczeniu i diagnostyce, zobacz SQL Server connection pooling.

Opcje odzyskiwania połączenia

Keyword Default Behavior wersja
Connect Retry Count 1 Ustala liczbę powtórek dla kwalifikujących się awarii przejściowych podczas początkowego połączenia oraz dla przywrócenia zerwanego połączenia bezczynnościowego. Obowiązującą wartością domyślną jest 2 dla rozpoznawanych punktów końcowych Azure SQL oraz 5 dla rozpoznawanych punktów końcowych Azure Synapse i punktów końcowych na żądanie. 0 wyłącza te ponowienia. Wszystkie wersje Microsoft. Data.SqlClient
Connect Retry Interval 10 sekund Ustawia opóźnienie przed kolejnymi próbami nawiązania początkowego połączenia lub wznowienia po bezczynności. Wartości poprawne to od 1 do 60 sekund. Wszystkie wersje Microsoft. Data.SqlClient

Pierwsza próba podczas odzyskiwania połączenia następuje natychmiast. Connect Retry Interval ma zastosowanie przed następnymi próbami. Aby obejść wbudowaną próbę otwierania początkowego dla jednej operacji, użyj otwartego przeciążenia z OpenWithoutRetry.

Te słowa kluczowe nie ponawiają polecenia, które zakończy się niepowodzeniem podczas wykonywania. Użyj konfigurowalnej logiki powtórek do niestandardowej polityki otwierania lub poleceń. Ponawiaj polecenia tylko wtedy, gdy powtórzenie ich skutków jest bezpieczne.

Tożsamość serwera i opcje certyfikatów

Te opcje spełniają określone wymagania dotyczące nazewnictwa certyfikatów lub nazw w protokole Kerberos. Nie zastępują standardowego uwierzytelniania ani weryfikacji certyfikatów.

Keyword Default Behavior wersja
Host Name In Certificate Nazwa hosta serwera Dostarcza oczekiwaną nazwę Common Name (CN) lub Subject Alternative Name (SAN), gdy połączenie używa aliasu DNS różniącego się od certyfikatu. Microsoft. Data.SqlClient 5.0 i nowsze wersje
Server Certificate Pusty Dostarcza plik PEM, DER lub CER, który musi dokładnie odpowiadać certyfikatowi serwera, gdy Encrypt=Mandatory lub Encrypt=Strict. Microsoft. Data.SqlClient 5.1 i nowsze wersje
Server SPN Pochodzi od nazwy serwera Nadpisuje nazwę Głównej Usługi (SPN) używaną do zintegrowanej autoryzacji do serwera głównego. Konfiguruj go tylko wtedy, gdy wdrożone nazewnictwo Kerberos wymaga wyraźnego SPN. Microsoft. Data.SqlClient 5.0 i nowsze wersje
Failover Partner SPN Pochodzi od partnera przełączania awaryjnego Nadpisuje SPN jako partnera do mirroringu bazy danych. Dublowanie bazy danych jest przestarzałe. Używaj grup dostępności do nowych wdrożeń. Microsoft. Data.SqlClient 5.0 i nowsze wersje

Host Name In Certificate zmienia nazwę używaną do dopasowywania certyfikatów. Nie ufa niezaufanemu wydawcy. Server Certificate przypina dokładny plik certyfikatu i wymaga aktualizacji aplikacji po rotacji tego certyfikatu.

Nieprawidłowe nadpisania SPN mogą uniemożliwić uwierzytelnienie Kerberos lub osłabić zamierzoną weryfikację tożsamości. Popraw rejestrację DNS i SPN zamiast ustawiać nadpisania, jeśli to możliwe.

Trzymaj stringi połączeń małe. Dodaj opcję tylko wtedy, gdy możesz podać, jakie zachowanie się zmienia i jak obciążenie to weryfikuje.

Przejrzyj zmiany opcji

Przed zmianą opcji w produkcji:

  1. Zarejestruj aktualny parametry połączenia, wersję sterownika, typ punktu końcowego oraz zaobserwowany problem.
  2. Zmieniaj jedno zachowanie na raz.
  3. Testuj nawiązywanie połączenia, uwierzytelnianie, walidację certyfikatów, pulowanie, przełączanie awaryjne, anulowanie oraz wykonywanie zapytań.
  4. Mierz twarde połączenia, oczekiwania na pulę, opóźnienia połączenia i liczby błędów.
  5. Potwierdź to ustawienie na każdej wdrożonej instancji.

Ciągi połączeń stanowią część klucza puli. Stopniowe wdrożenie może tymczasowo spowodować utworzenie zarówno starych, jak i nowych pul, co zwiększa łączną liczbę fizycznych połączeń z bazą danych.

Treści powiązane

  • Ostatnia aktualizacja o