Microsoft. Data.SqlClient for SQL Server

Pobieranie ADO.NET

Microsoft. Data.SqlClient to wspierany dostawca danych .NET dla SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics oraz SQL database w Microsoft Fabric. Jest dystrybuowany jako pakiet NuGet, rozwija się niezależnie od środowiska uruchomieniowego .NET i zastępuje System.Data.SqlClient go w nowym rozwoju. Używaj go do otwierania połączeń, wykonywania poleceń, przetwarzania wyników, zarządzania transakcjami, masowego ładowania danych oraz korzystania z funkcji specyficznych dla SQL Server z aplikacji .NET.

Wybieranie punktu początkowego

Plan bazowy produkcji dla Azure SQL

Użyj tego fragmentu jako punktu wyjścia do produkcyjnej ścieżki dostępu do danych Azure SQL. Odczytuje nazwy serwerów i baz danych z IConfiguration, więc wartości pochodzą od dostawców konfiguracji, które host podłącza (appsettings.json, zmienne środowiskowe, Azure App Configuration, ustawienia wspierane przez Key Vault itd.). Konfiguracja łączy zabezpieczenia warstwy transportowej (TLS), zarządzaną tożsamość, odporność na połączenie bezczynne, próbę powtórek po początkowym połączeniu za pomocą konfigurowalnej logiki powtórek (CRL) ze strukturalnym logowaniem, powtórki na poziomie poleceń dla błędów przejściowych uruchamianych w trakcie zapytania oraz szybkie odzyskiwanie po grupie awaryjnej.

Dla wyższego bezpieczeństwa i wsparcia konfiguracji w różnych środowiskach zachowaj informacje o połączeniach poza kodem. W produkcji przechowuj informacje o połączeniach w systemie konfiguracji aplikacji i używaj Azure Key Vault dla wartości wrażliwych. Aby uzyskać więcej informacji, zobacz Ochrona informacji o połączeniu.

Fragment C# w tym artykule pomija using dyrektywy i opakowania klas dla zwięzłości.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Ten fragment jest celowany w dowolny punkt końcowy SQL Database Engine skonfigurowany pod uwierzytelnianie Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, SQL database in Microsoft Fabric oraz SQL Server 2022 i nowsze wersje na Azure Virtual Machines lub włączone przez Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict wybiera szyfrowanie TDS 8.0. Wymaga Microsoft. Data.SqlClient 5.0 i nowszych oraz serwer wspierający TDS 8.0 (wersje SQL Server 2022 i nowsze, Azure SQL Database, Azure SQL Managed Instance oraz baza danych SQL w Microsoft Fabric). Wracaj do SqlConnectionEncryptOption.Mandatory podłączania się do starszych serwerów.

ConnectRetryCount oraz ConnectRetryInterval włącz odporność połączenia bezczynnościowego: po Open() powodzeniu sterownik przezroczysto ponownie łączy zerwane połączenie bezczynnościowe w następnym poleceniu. Nie próbują ponownie z początku Open(). Próby połączeń początkowych pochodzą od dostawcy przypisanego openRetry do SqlConnection.RetryLogicProvider. Obie cechy są komplementarne.

Zdarzenie Retrying u każdego dostawcy uruchamia się przed każdą próbą powtórki i zawiera liczbę powtórzeń, opóźnienie przed kolejną próbą oraz dotychczasowe wyjątki. Przekieruj go do ILogger swojego pipeline'u telemetrycznego, aby pętla powtórek była widoczna w produkcji.

Ustaw MultiSubnetFailover = true moment, gdy celem jest Azure SQL Database, Azure SQL Managed Instance, baza danych SQL w Microsoft Fabric, nasłuchiwacz grup dostępności lub instancja klastra awaryjnego. Wybiera ścieżkę kodu równoległego połączenia, która próbuje połączyć się TCP ze wszystkimi rozwiązanymi adresami IP równolegle i wykorzystuje pierwsze udane połączenie, unikając powolnego, sekwencyjnego przejścia na adres IP, które mogłoby zatrzymać te połączenia. Na celach z pojedynczym IP ustawienie jest bezpieczne. MultiSubnetFailover nie jest obsługiwany, gdy łączysz się z nazwaną instancją, przez protokół inny niż TCP lub z instancją skonfigurowaną z więcej niż 64 adresami IP. Nie można też używać go z mirroringiem baz danych, które jest wycofane we wszystkich obsługiwanych wersjach SQL Server. Zamiast tego użyj grup dostępności Always On. Więcej informacji można znaleźć w artykule High availability and Disaster Recovery oraz Discapling Transparent Network IP Resolution.

Jeśli celem jest serwerless Azure SQL Database z włączoną automatyczną pauzą, podnieś ConnectTimeout do co najmniej 60 sekund. Automatycznie wstrzymana baza danych wznawia się na pierwszym Open(), a ten pierwszy Open() może zawiesić błąd 40613 , podczas gdy baza wraca. Błąd 40613 znajduje się na wbudowanej liście błędów przejściowych, więc openRetry próbuje go ponownie. Timeouty po stronie klienta pojawiają się jako błąd -2, którego nie ma na tej liście, więc openRetry nie uratują osoby Open() , która wygasa w trakcie CV. Indywidualna próba kontaktu powinna być wystarczająco długa, aby pokryć CV. Więcej informacji znajdziesz w sekcji Automatyczne wstrzymywanie i automatyczne wznawianie.

Ponowna próba na poziomie komendy to decyzja dzwoniącego, dla każdego polecenia. Przypisuj commandRetry się tylko SqlCommand.RetryLogicProvider wtedy, gdy powtórka polecenia jest bezpieczna: odczyty, MERGE chronione przez naturalny klucz, upserty przez procedurę przechowywaną i inne operacje idempotentne. Wbudowany dostawca poleceń pomija ponowne próby, gdy transakcja jest aktywna, więc transakcje wielopolecenia muszą być powtarzane przez kod aplikacji, który może ponownie otworzyć transakcję. Ustawienie TransientErrors zastępuje wbudowaną listę błędów sterownika; aby rozszerzyć wbudowaną linię bazową, użyj SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 i nowsze).

Aby uzyskać więcej informacji na temat każdej części tej konfiguracji, zobacz:

Kluczowe funkcje

  • Nowoczesne wsparcie .NET: Działa na aktualnych wersjach .NET i .NET Framework. Podział na każdą wersję można znaleźć w artykule cykl życia Wsparcia.
  • Domyślnie szyfrowane: połączenia szyfrowane TLS, z Encrypt=true domyślnym zaszyfrowaniem. Ustawione Encrypt=Strict na szyfrowanie TDS 8.0 w Microsoft. Data.SqlClient 5.0 i nowsze.
  • Uwierzytelnianie Microsoft Entra ID: połączenia bez użycia hasła z tożsamością zarządzaną, nazwą główną usługi, logowaniem interaktywnym, logowaniem zintegrowanym, domyślnym łańcuchem poświadczeń i przepływami tokenu dostępu.
  • Kerberos i NTLM: Zintegrowana Windows authentication dla scenariuszy lokalna usługa Active Directory i starszych serwerów.
  • Always Encrypted: szyfrowanie po stronie klienta dla kolumn poufnych z opcjonalnymi bezpiecznymi enklawami dla operacji w miejscu.
  • Kopia masowa: Wkładki o wysokiej przepustowości z SqlBulkCopy.
  • Odporność na połączenia: Wbudowane próby połączeń (ConnectRetryCount i ConnectRetryInterval) oraz konfigurowalna logika połączeń i poleceń z możliwością zgody.
  • Bogate typy danych SQL Server: datetimeoffset, sql_variant, JSON, wektorowe, przestrzenne, XML oraz parametry tabelowe.
  • Diagnostyka: śledzenie źródeł zdarzeń, liczniki diagnostyczne, statystyki dostawców oraz dedykowany przewodnik po rozwiązywaniu problemów.

Wprowadzenie

Artykuł Description
Wprowadzenie do sterownika SqlClient Ustaw projekt, stwórz bazę danych, połącz się, zapytaj i dodaj odporność na połączenia.
Omówienie sterownika SqlClient Dowiedz się, jak Microsoft. Data.SqlClient pasuje do ADO.NET.
Pobierz Microsoft. Data.SqlClient Zainstaluj pakiet NuGet i znajdź wersje źródłowe.
Cykl życia wsparcia Przejrzyj obsługiwane wersje sterowników i daty wsparcia.
Microsoft. Przestrzeń nazw Data.SqlClient Migruj z System.Data.SqlClient i przejrzyj różnice w przestrzeniach nazw.

Konfigurowanie i łączenie

Artykuł Description
Połącz się ze źródłem danych Otwieraj i zarządzaj połączeniami z SQL Server i Azure SQL.
Parametry połączenia Konfiguruj serwer, bazę danych, uwierzytelnianie, szyfrowanie i zachowanie połączenia.
Szyfrowanie i walidacja certyfikatów Konfiguruj szyfrowane połączenia i walidację certyfikatów serwera.
SQL Server connection pooling Efektywnie ponownie wykorzystuj fizyczne połączenia.
Zdarzenia łączące Odpowiadaj na komunikaty o stanie połączenia i informacjach.

Uwierzytelnianie i zabezpieczenie

Artykuł Description
Zabezpieczenia programu SQL Server Przejrzyj wytyczne dotyczące uwierzytelniania, autoryzacji i bezpieczeństwa aplikacji.
Uwierzytelnianie Microsoft Entra Połącz się z zarządzaną tożsamością, zasadą usługi, hasłem oraz interaktywnymi przepływami.
Chroń informacje o połączeniu Trzymaj dane uwierzytelniające i ustawienia połączenia poza kodem aplikacji.
Zawsze szyfrowane Chroń wrażliwe wartości kolumn przed systemem baz danych.
Ciągłe Szyfrowanie z bezpiecznymi enklawami Uruchamiaj zaawansowane operacje na zaszyfrowanych danych z bezpiecznym enklawą.

Pobieranie i aktualizacja danych

Artykuł Description
Polecenia i parametry Wykonuj parametryzowane instrukcje SQL i procedury przechowywane.
Adaptery danych i Czytniki danych Strumieniowanie zbiorów wyników lub zapełnianie rozłączonych struktur danych.
Transakcje i współbieżność Używaj lokalnych i rozproszonych transakcji oraz kontroli współbieżności.
Pobierz informacje o schemacie bazy danych Odkryj kolekcje schematów i ograniczenia.
Operacje kopiowania masowego Wydajnie ładuj duże zbiory danych za pomocą SqlBulkCopy.
Parametry wartości tabeli Wyślij wiele wierszy do parametryzowanego wyroku lub procedury przechowywanej.
Programowanie asynchroniczne Używaj asynchronicznego połączenia, poleceń i operacji danych.
Wiele aktywnych zestawów wyników (MARS) Przeklej kilka partii na jednym połączeniu.

Typy danych

Artykuł Description
Mapowania typów danych ADO.NET Przypisuj typowe języki wspólne do typów dostawców i SQL Server.
Typy danych SQL Server Pracuj z wartościami i System.Data.SqlTypes typami specyficznymi dla SQL Server.
Dane JSON Wyślij i pobierz typ danych SQL Serverjson.
Dane wektorowe Wyślij i pobierz wartości wektorowe.
Dane XML Odczytuj, zapisuj i parametryzuj wartości XML.
Dane binarne i duże wartości Przesyłanie i aktualizacja danych binarnych, FILESTREAM oraz dużych wartości.

Niezawodność i diagnostyka

Artykuł Description
Konfigurowalna logika ponawiania prób Spróbuj ponownie przejść połączenia i poleceń z ograniczonymi politykami.
Wysoka dostępność i odzyskiwanie po awarii Połącz się z grupowymi słuchaczami dostępności i partnerami do przełączania awaryjnego.
Liczniki diagnostyczne Monitoruj aktywne połączenia, połączenia w grupie oraz inne metryki sterowników.
Włącz śledzenie źródeł zdarzeń Rejestruj szczegółowe zdarzenia kierowców do diagnozy.
Śledzenie danych Śledzenie operacji ADO.NET i dostępu do danych.
Przewodnik rozwiązywania problemów z programem SqlClient Zdiagnozuj typowe problemy z połączeniem i sterownikami.
Powiadomienia zapytań Otrzymuj powiadomienia, gdy wyniki zapytań się zmienią.

Funkcje programu SQL Server

Artykuł Description
Funkcje i ADO.NET programu SQL Server Przeglądaj funkcje specyficzne dla SQL Server dostępne w SqlClient.
Lokalna baza danych Połącz się z instancjami SQL Server Express LocalDB.
Odnajdowanie i klasyfikacja danych Odczytuj metadane klasyfikacji czułości z zestawów wyników.

Dokumentacja i zasoby

Artykuł Description
Microsoft. Data.SqlClient API reference Przeglądaj referencję API .NET dla sterownika.
Przełączniki AppContext Konfiguruj kompatybilność i zachowanie bezpieczeństwa.
Znajdź dodatkowe informacje o SqlClient Znajdź kod źródłowy, wsparcie i zasoby społecznościowe.

Treści powiązane

  • Last updated on