Stringi połączeń dla Microsoft. Data.SqlClient

Parametry połączenia Microsoft.Data.SqlClient to lista par keyword=value oddzielonych średnikami. Przekaż do SqlConnection lub SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Parametry połączenia odpowiadają na cztery pytania:

  1. Jakiego serwera i bazy danych używa aplikacja?
  2. Pod jaką tożsamością działa aplikacja?
  3. Jak klient waliduje certyfikat serwera?
  4. Jakiego zachowania połączenia wymaga obciążenie robocze?

Ten artykuł omawia te wybory oraz zasady, których kierowca stosuje podczas czytania tekstu. Dla każdego słowa kluczowego, jego synonimów oraz wartości domyślnej zobacz Opcje połączenia. Aby tworzyć i zmieniać stringi połączeń w kodzie, zobacz Builders Connection string builders.

Wybierz wzorzec uwierzytelniania

Użyj wzoru pasującego do wdrożenia. Zastąp każdy zastępczy, na przykład , <server>swoją wartością.

Environment Pattern Parametry połączenia
SQL Server na Windows z domenową lub lokalną tożsamością systemu Windows Zintegrowane uwierzytelnianie systemu Windows Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
Aplikacja hostowana w Azure i łącząca się z Azure SQL Tożsamość zarządzana Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
Stacja robocza dewelopera łącząca się z Azure SQL Domyślny łańcuch poświadczeń w Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Stacja robocza dewelopera łącząca się z bazą danych SQL w Microsoft Fabric Domyślny łańcuch poświadczeń w Microsoft Entra ID Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Interaktywne narzędzie pulpitowe łączące się z Azure SQL Interaktywne uwierzytelnianie Microsoft Entra ID Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
Środowisko wymagające uwierzytelniania SQL Nazwa użytkownika i hasło z tajnego magazynu Server=<server>;Database=<database>;User ID=<user>;Password=<password>;Encrypt=true

Zintegrowane uwierzytelnianie w Windows łączy się jako tożsamość procesu. W przypadku aplikacji desktopowej lub konsolowej zwykle jest to użytkownik zalogowany. W przypadku aplikacji webowej lub usługi Windows jest to pula aplikacji lub konto usługowe. Podszywanie się może zmienić tożsamość. Przyznaj logowanie i uprawnienia do bazy danych do tożsamości, której faktycznie używa Twoja aplikacja.

Te trzy formy zintegrowanej uwierzytelniania Windows są równoważne:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Jeśli ciąg znaków set Integrated Security=true i także ustawia User ID i , Passwordsterownik używa Windows authentication i ignoruje nazwę użytkownika oraz hasło.

Microsoft. Data.SqlClient 7.0 i nowsze wersje wymagają pakietu dopasowanego Microsoft.Data.SqlClient.Extensions.Azure do wersji dla systemów uwierzytelniania Microsoft Entra ID dostarczanych przez sterownik. Nie potrzebujesz tego pakietu, gdy kod aplikacji dostarcza token dostępu lub callback tokena dostępu.

Akceptowane Authentication wartości można znaleźć w sekcji Opcje uwierzytelniania. Uwierzytelnianie wymaga również skonfigurowania użytkowników bazy danych, uprawnień oraz konfiguracji tożsamości na serwerze. Szczegóły konfiguracji można znaleźć w artykule Microsoft Entra ID authentication oraz SQL Server authentication.

Określ serwer i bazę danych

Server i Database są najbardziej czytelnymi nazwami słów kluczowych. Budowniczy zapisuje je jako ich kanoniczne odpowiedniki, Data Source oraz Initial Catalog. Wszystkie cztery nazwy działają w parametry połączenia.

Ustaw Server na jedną z tych form:

Form Example Używanie
Nazwa hosta Server=sql.example.com Domyślna instancja na porcie 1433.
Nazwa hosta i port Server=tcp:sql.example.com,1433 Konkretny port TCP. Oddziel port przecinkem, nie dwukropkiem.
Nazwana instancja Server=sql.example.com\SALES Nazwana instancja. Sterownik prosi usługę SQL Server Browser na porcie UDP 1434 o ten port.
Serwer lokalny Server=(local) lub Server=. Domyślna instancja na komputerze lokalnym.
LocalDB Server=(localdb)\MSSQLLocalDB SQL Server Express LocalDB na Windows. Połączenie nie jest szyfrowane, nawet przy Encrypt=Mandatory, i zawodzi Encrypt=Strict .
Nazwany potok Server=np:\\sql.example.com\pipe\sql\query Połączenie z potokiem nazwanym w systemie Windows.

Użyj tcp:, czyli w pełni kwalifikowanej nazwy hosta i jawnego portu, w środowisku produkcyjnym. Używaj nazwy DNS, która jest zgodna z nazwami w certyfikacie serwera, a nie adresu IP, ponieważ walidacja certyfikatów porównuje nazwę serwera w parametry połączenia z nazwami w certyfikacie.

Gdy łączysz się z Azure SQL Database za pomocą uwierzytelniania SQL i nazwy użytkownika w formie user@servername, część servername musi odpowiadać serwerowi w Server.

W przypadku nasłuchiwacza grupy dostępności lub instancji klastra trybu failover również sprawdź Multi Subnet Failover w opcjach połączenia.

Konfiguruj szyfrowanie i walidację certyfikatów

Słowo kluczowe Encrypt akceptuje następujące wartości, niezależnie od wielkości liter:

Value Wartość konstruktora Meaning
Strict Strict Korzysta z TDS 8.0. Szyfruje połączenie przed logowaniem i zawsze weryfikuje certyfikat serwera.
Mandatory, true, yes True Szyfruje połączenie. Jest to wartość domyślna.
Optional, false, no False Szyfruje całe połączenie tylko wtedy, gdy serwer wymaga szyfrowania. Gdy serwer obsługuje szyfrowanie, ale go nie wymaga, szyfrowany jest tylko pakiet logowania.

Używaj Strict , gdy serwer obsługuje TDS 8.0 i posiada certyfikat, który klient może zweryfikować. Azure SQL Database oraz SQL Database in Microsoft Fabric go obsługują. Połączenie LocalDB nie jest szyfrowane, nawet przy Mandatory, i Strict zawodzi.

Wartości Encrypt i Trust Server Certificate łączą się następująco:

Szyfrowanie Certyfikat serwera zaufania Result
Optional false Gdy serwer wymaga szyfrowania, całe połączenie jest szyfrowane, a certyfikat serwera musi zostać zweryfikowany. W przeciwnym razie połączenie się nie udaje. Gdy serwer obsługuje szyfrowanie, ale go nie wymaga, szyfrowany jest tylko pakiet logowania, a sterownik nie waliduje certyfikatu serwera, chyba że połączenie używa AccessToken lub AccessTokenCallback. Gdy serwer nie obsługuje szyfrowania, nic nie jest szyfrowane.
Optional true Gdy serwer wymaga szyfrowania, całe połączenie jest szyfrowane. Gdy serwer obsługuje szyfrowanie, ale go nie wymaga, szyfrowany jest tylko pakiet logowania. Sterownik nie waliduje certyfikatu serwera.
Mandatory false Szyfrowanie następuje tylko wtedy, gdy certyfikat serwera zostanie zweryfikowany. W przeciwnym razie połączenie się nie udaje.
Mandatory true Szyfrowanie zawsze się zdarza, ale sterownik nie weryfikuje certyfikatu serwera.
Strict Ignored Szyfrowanie zawsze występuje, a certyfikat serwera musi zostać zweryfikowany. W przeciwnym razie połączenie się nie udaje.

Nie ustawiaj Trust Server Certificate=true, aby naprawić błąd połączenia w środowisku produkcyjnym. Szyfruje kanał, ale nie potwierdza tożsamości serwera. Ogranicz to do środowisk programistycznych, gdzie nie ma zaufanego certyfikatu.

Gdy nazwa serwera w Data Source nie zgadza się z certyfikatem, ustaw Host Name In Certificate na nazwę z certyfikatu. SqlClient sprawdza to tylko wtedy, gdy nazwa serwera się nie zgadza i nie przypina certyfikatu. Aby zaakceptować tylko jeden konkretny certyfikat, ustaw Server Certificate na ścieżkę pliku PEM, DER lub CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

Pełne reguły walidacji można znaleźć w artykule Szyfrowanie i walidacja certyfikatów.

Korzystanie z buforowania połączeń

Pooling jest domyślnie włączone. Gdy otwierasz połączenie SqlConnection, sterownik pobiera fizyczne połączenie z puli, która odpowiada parametrom połączenia. Gdy zamykasz lub zwalniasz połączenie, fizyczne połączenie wraca do puli zamiast się zamykać. Otwarcie z puli pomija połączenie sieciowe, uzgadnianie TLS i logowanie.

Postępuj zgodnie z następującymi regułami:

  • Otwórz połączenie tuż przed użyciem i zamknij je, gdy skończysz, za pomocą using lub await using. Połączenie, które nie zostanie zwolnione, pozostaje wypożyczone, a pula może się wyczerpać.

  • Utwórz parametry połączenia raz przy starcie i użyj ich ponownie. Klucz puli zawiera dokładny tekst parametry połączenia, więc inna kolejność słów kluczowych, synonim lub wartość na żądanie, taka jak identyfikator żądania czy nazwa użytkownika, tworzy osobną pulę. Budowniczy pisze jedną formę kanoniczną. Więcej informacji można znaleźć w artykule Keep one canonical parametry połączenia.

  • Spodziewaj się osobnej puli dla każdej tożsamości Windows pod zintegrowaną autentyfikacją, każdej SqlCredential instancji i każdej AccessToken wartości. Stosuj metodę udostępnioną Authentication przez sterownik lub używaną ponownie AccessTokenCallback zamiast ustawiać AccessToken na każdym połączeniu.

  • Szukaj połączeń, które nie zostały zamknięte, zanim podniesiesz Max Pool Size, które domyślnie ustawia się na 100. Gdy każde połączenie w puli jest używane, oczekuje Open do Connect Timeout, a następnie zgłasza InvalidOperationException:

    Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

  • Zaplanuj wydajność serwera dla każdej puli. Każdy proces lub każda domena aplikacji w .NET Framework ma własne pule. Połączenia z serwerem mogą osiągnąć Max Pool Size pomnożone przez liczbę pul w każdym procesie oraz przez liczbę instancji aplikacji.

  • Nie ustawiaj Pooling=false, aby obejść problem z poolingiem. Każde otwarcie wymaga pełnego logowania.

Aby zamknąć połączenia w grupie, które pozostają bezczynne zbyt długo, zobacz Limit czasu bezczynności połączenia. Aby uzyskać informacje o kluczach puli, określaniu rozmiaru, czyszczeniu i transakcjach, zobacz SQL Server connection pooling.

Oddzielne ustawienia połączenia i poleceń

Parametry połączenia określają nawiązywanie połączenia i zachowanie sesji. Polecenie steruje jedną operacją SQL.

Wymaganie Skonfiguruj na
Czas na nawiązanie połączenia lub uzyskanie go z puli Connect Timeout słowo kluczowe
Domyślny limit czasu dla komend w połączeniu Command Timeout słowo kluczowe
Limit czasu dla jednego polecenia CommandTimeout
Anulowanie przez dzwoniącego CancellationToken przekazane metodom asynchronicznym
Zasady ponawiania prób przy otwieraniu połączenia lub uruchamianiu polecenia Konfigurowalna logika ponawiania prób dla SqlConnection lub SqlCommand

Dłuższy timeout to nie mechanizm ponawiania. Limit czasu na jedno czekanie. Powtórka rozpoczyna kolejną próbę, którą trzeba ograniczyć i można ją bezpiecznie powtórzyć.

Zgłoś identyfikator aplikacji

Application Name Ustala nazwę, którą serwer raportuje przez APP_NAME(). Używaj jednej stabilnej nazwy dla każdego wdrożonego obciążenia roboczego. Frameworki i narzędzia otwierające połączenia dla aplikacji mogą również zgłaszać się przez właściwość RegisteredApplication, która nie ma słowa kluczowego parametry połączenia. Więcej informacji można znaleźć w artykule Zgłoś tożsamość aplikacji.

Buduj łańcuchy połączeń bezpiecznie

Używaj SqlConnectionStringBuilder tego, gdy kod dodaje lub zmienia wartość. Nie łącz niezaufanego tekstu w parametry połączenia, ponieważ średnik w tym tekście może dodawać lub zastępować słowo kluczowe. Konstruktor weryfikuje wartości, mapuje synonimy na kanoniczne słowa kluczowe i ujmuje każdą wartość w cudzysłów, aby wartość nie mogła dodawać słów kluczowych. Przykłady można znaleźć w sekcji Konstruktory parametrów połączenia.

Przechowuj informacje o połączeniach poza kodem

Ładuj ciągi połączeń z systemu konfiguracji aplikacji. Aplikacje .NET często wykorzystują zmienne środowiskowe, sekrety użytkownika do lokalnego rozwoju, Azure App Configuration oraz Azure Key Vault.

Postępuj zgodnie z następującymi regułami:

  • Nie zapisuj haseł, sekretów klienta, tokenów dostępu ani łańcuchów połączeń produkcyjnych.
  • Preferuj metodę uwierzytelniania, która nie wymaga hasła w parametry połączenia.
  • Ogranicz dostęp do źródła konfiguracji.
  • Rotuj zapisane wpisy tajne i zrestartuj lub odśwież aplikacje, które buforują je w pamięci podręcznej.
  • Nie zapisuj parametrów połączenia w logach, wyjątkach, danych śledzenia ani telemetrii.
  • Zostaw Persist Security Info=false domyślne, aby otwarte połączenie nie ujawniało hasła poprzez swoją właściwość ConnectionString.

Aby uzyskać usługi konfiguracji .NET, zobacz Konfiguracja w .NET. Więcej ustawień można znaleźć w sekcji Ochrona informacji o połączeniu.

Zasady parsowania

Kierowca stosuje następujące zasady:

  • Słowa kluczowe nie rozróżniają wielkości liter. DATABASE, Database, oraz database to to samo słowo kluczowe.
  • Wiele słów kluczowych ma synonimy. Server i Data Source mają tę samą wartość. Artykuł Opcje połączenia wymienia synonimy dla każdego słowa kluczowego.
  • Gdy słowo kluczowe pojawia się więcej niż raz, wygrywa ostatnia wartość. Synonimy liczą się jako to samo słowo kluczowe.
  • Sterownik ignoruje spacje wokół słów kluczowych i wokół wartości niecytowanych.
  • Końcowy średnik jest opcjonalny.
  • Słowo kluczowe, którego sterownik nie rozpoznaje, powoduje zgłoszenie ArgumentException z komunikatem Keyword not supported.

Wartości mogą być zależne od wielkości liter, w zależności od słowa kluczowego. Hasło rozróżnia wielkość liter. Encrypt=STRICT i Encrypt=strict są takie same.

Program ten pokazuje, jak konstruktor normalizuje słowa kluczowe, rozwiązuje duplikat i cytuje znaki specjalne. Zakładka .NET Framework używa C# 7.3. Aby stworzyć projekt, który uruchamia próbki, zobacz Utwórz projekt.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

Dane wyjściowe to:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

Pierwsza linijka pokazuje, że każdy synonim został zastąpiony jego kanonicznym słowem kluczowym: timeout przez Connect Timeout, User ID przez uid, Initial Catalog przez DATABASE oraz Data Source przez server.

Wartości w cudzysłowie

Umieść wartość w podwójnych cudzysłowach (") lub pojedynczych cudzysłowach ('), gdy zawiera ona średnik, zaczyna się lub kończy spacją albo zaczyna lub kończy się cudzysłowem. Wewnątrz podanej wartości wpisz dwukrotnie otaczający cudzysłów.

Value Forma ciągu połączeń
a;b Password="a;b"
abc' Password="abc'"
say "hi" Password='say "hi"'
a;b'c"d Password="a;b'c""d"

Zasady cytowania łatwo pomylić. Ustalaj wartości za pomocą właściwości SqlConnectionStringBuilder i pozwól konstruktorowi ująć je w cudzysłów. Więcej informacji można znaleźć w artykule Bezpiecznie buduj łańcuchy połączeń.

Określ wartości logiczne

Słowa kluczowe przyjmujące wartość boolowską akceptują truew każdym przypadku , false, yes, oraz no, . Integrated Security akceptuje sspitakże , co oznacza true. Budowniczy zapisuje True lub False.

Używaj słów kluczowych z innych sterowników

Microsoft. Data.SqlClient nie akceptuje słów kluczowych ODBC ani OLE DB, takich jak Driver i Provider. Usuń te słowa kluczowe, gdy przenosisz parametry połączenia z innego sterownika. System.Data.SqlClientStringi połączeń działają w Microsoft. Data.SqlClient, z tymi różnicami:

  • Encrypt ma domyślnie wartość Mandatory w Microsoft.Data.SqlClient. Serwer bez zaufanego certyfikatu nie przechodzi walidacji certyfikatu. Zainstaluj zaufany certyfikat na serwerze.
  • Na .NET, Network Library, Connection Reset, i Transparent Network IP Resolution nie są obsługiwane. Usuń je.
  • Context Connection=true nie jest obsługiwany.
  • Asynchronous Processing nie jest obsługiwanym słowem kluczowym i powoduje wystąpienie błędu ArgumentException. Usuń. Metody asynchroniczne działają bez tego.
  • Type System Version=SQL Server 2000 nie jest obsługiwany. Tworzenie połączenia powoduje błąd ArgumentException. Użyj Latest, SQL Server 2012, SQL Server 2008, lub SQL Server 2005.

Treści powiązane

  • Ostatnia aktualizacja o