Microsoft. Data.SqlClient for SQL Server

Pobieranie ADO.NET

Microsoft.Data.SqlClient jest obsługiwanym dostawcą danych .NET dla SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, bazy danych SQL w Microsoft Fabric oraz Magazynu danych w Microsoft Fabric. Jest dystrybuowany jako pakiet NuGet, rozwija się niezależnie od platformy uruchomieniowej .NET i zastępuje System.Data.SqlClient w przypadku nowych projektów. Zapewnia połączenia połączenia, polecenia, przetwarzanie wyników, transakcje, kopiowanie masowe oraz funkcje specyficzne dla SQL Server dla 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 konfiguruje, takich jak appsettings.json, zmienne środowiskowe, Azure App Configuration oraz ustawienia wspierane przez Key Vault. Konfiguracja łączy następujące cechy:

  • Bezpieczeństwo warstwy transportowej (TLS).
  • Tożsamość zarządzana.
  • Odporność na nieaktywne połączenie.
  • Próba ponownego połączenia za pomocą konfigurowalnej logiki powtórek (CRL), z ustrukturyzowanym logowaniem.
  • Ponowna próba na poziomie poleceń dla błędów przejściowych, które pojawiają się w trakcie zapytania.
  • Szybkie odzyskiwanie grupy trybu failover.
  • Asynchroniczne wywołania akceptujące token anulowania.

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 kodu w języku C# w tym artykule pomija dyrektywy using i deklaracje klas dla zachowania zwięzłości.

Fragment zakłada projekt przeznaczony dla platformy .NET 8 lub nowszych wersji i odwołuje się do pakietów Microsoft.Data.SqlClient i Microsoft.Data.SqlClient.Extensions.Azure 7.1.1. Host, taki jak .NET Generic Host lub ASP.NET Core, dostarcza ILogger i IConfiguration, a konfiguracja podaje nazwę serwera w Sql:Server oraz nazwę bazy danych w Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

Metoda zwraca nazwę bazy danych, do której się połączyła, i loguje Connected to database <database>. Gdy następuje ponowna próba, rejestruje też jedno ostrzeżenie na każdą próbę wraz z wyjątkiem, który ją wywołał.

Jak działa każda część fragmentu:

  • Targety: Dowolny punkt końcowy SQL Database Engine skonfigurowany do uwierzytelniania Microsoft Entra: Azure SQL Database, Azure SQL Managed Instance, baza SQL w Microsoft Fabric oraz SQL Server 2022 i nowsze wersje na Azure Virtual Machines lub obsługiwane przez Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Wybór szyfrowania TDS 8.0. Wymaga wersji SQL Server 2022 i nowszych, Azure SQL Database, Azure SQL Managed Instance lub bazy danych SQL w Microsoft Fabric. Użyj SqlConnectionEncryptOption.Mandatory na starszych serwerach.
  • ActiveDirectoryManagedIdentity: Działa tylko tam, gdzie dostępna jest zarządzana tożsamość, na przykład Azure App Service, Azure Functions lub maszyna wirtualna Azure. Do lokalnego rozwoju użyj SqlAuthenticationMethod.ActiveDirectoryDefault, który próbuje użyć interfejsu Azure CLI, logowania w programie Visual Studio i innych źródeł poświadczeń. Nie używaj tego na produkcji, bo sondowanie każdego źródła spowalnia połączenie. Więcej informacji można znaleźć w artykule Użyj domyślnego uwierzytelniania.
  • MultiSubnetFailover = true: Próbuje połączyć się TCP ze wszystkimi rozwiązanymi adresami IP równolegle i używa pierwszego udanego połączenia, unikając powolnego sekwencyjnego sprawdzania kolejnych adresów IP. Ustaw go dla Azure SQL Database, Azure SQL Managed Instance, bazy danych SQL w Microsoft Fabric, słuchaczy grup dostępności oraz wystąpień klastra trybu failover. To jest bezpieczne w przypadku celów z jednym adresem IP. Nie jest obsługiwany dla nazwanych instancji, protokołów innych niż TCP, instancji z więcej niż 64 adresami IP ani mirroringu baz danych, który jest przestarzały. Zamiast tego użyj grup dostępności Always On. Więcej informacji można znaleźć w sekcjach Wysoka dostępność i odzyskiwanie po awarii oraz Wyłączanie rozpoznawania adresu IP sieci transparentnej.
  • ConnectRetryCount = 3 oraz ConnectRetryInterval = 10: Sterownik ponawia próby w przypadku kwalifikujących się przejściowych błędów podczas Open(), a następnie ponownie nawiązuje przerwane bezczynne połączenie przy następnym poleceniu. Domyślna wartość to 1. Trzy próby w odstępach 10 sekund mogą przetrwać dłuższą rekonfigurację lub awaryjne przełączanie. Sterownik zwiększa wartość z 1 do 2 tylko wtedy, gdy nazwa serwera kończy się znaną domeną Azure SQL, np. .database.windows.net, więc niestandardowy alias DNS ma wartość 1.
  • openRetry: Przypisane do SqlConnection.RetryLogicProvider, dodaje wykładniczy backoff wokół Open(). Sterownik przerywa wewnętrzne próby, gdy ConnectTimeout wygaśnie, więc w najgorszym przypadku, zanim OpenAsync zgłosi wyjątek, nastąpi pięć prób trwających do 30 sekund każda, plus opóźnienie. Każda próba ponownego połączenia w stanie bezczynności uruchamia również pełne zasady openRetry, a gdy te zasady wyczerpią swoje próby, przywracanie połączenia w stanie bezczynności kończy się.
  • Serverless auto-pause: Dla Azure SQL Database w warstwie serverless podnieś limit czasu bezczynności ConnectTimeout do co najmniej 60 sekund. Pierwszy Open() może zawieść z błędem 40613, podczas wznawiania bazy danych, a openRetry ponawia próbę. Timeout po stronie klienta pojawia się jako błąd -2, który nie jest ponawiany, więc każda próba połączenia musi trwać dłużej niż proces wznawiania. Więcej informacji znajdziesz w sekcji Automatyczne wstrzymywanie i automatyczne wznawianie.
  • commandRetry: Dołącz to do SqlCommand.RetryLogicProvider tylko wtedy, gdy bezpieczne jest ponowne wykonanie polecenia: odczyty, MERGE chronione kluczem naturalnym, upserty realizowane przez procedurę składowaną i inne operacje idempotentne. Pomija on ponowienie próby w ramach transakcji, więc kod aplikacji musi ponownie próbować transakcje wieloinstrukcyjne. ExecuteReader i ExecuteScalar ponawiają tylko błędy zwrócone przed rozpoczęciem pierwszego zestawu wyników. ExecuteNonQuery ponawia całe wywołanie.
  • Lista błędów przejściowych: Ustawienie TransientErrors zastępuje wbudowaną listę. Aby go rozszerzyć, użyj SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 i nowszy).
  • Retrying Wydarzenie: Retrying Uruchamia się przed każdym ponowieniem z liczbą ponowień, kolejnym opóźnieniem i dotychczasowymi wyjątkami. Przekieruj go do ILogger lub swojego pipeline'u telemetrycznego.
  • Wyjątki: Metoda nie przechwytuje wyjątków. Dostawca po wyczerpaniu prób rzuca AggregateException z wyjątkiem z każdej próby. Błąd nieprzejściowy propaguje się jako pierwotny wyjątek. Wywołujący rejestruje to raz razem z resztą kontekstu żądania.
  • Anulowanie operacji: To CancellationToken zatrzymuje czas oczekiwania dostawcy między ponowieniami. Nie przerywa to oczekiwania ConnectRetryInterval kierowcy w ramach pojedynczej Open próby. Więcej informacji można znaleźć w artykule Programowanie asynchroniczne.
  • Cykl życia dostawcy: Fragment tworzy dostawców ponawiania przy każdym wywołaniu, aby zachować samodzielność. W aplikacji stwórz je raz i wykorzystaj ponownie.

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

Poznaj podstawowe zadania związane z dostępem do danych

Po połączeniu używaj następujących artykułów w kolejności:

  1. Wykonaj polecenie, aby wybrać kształt wyniku i uruchomić Transact-SQL (T-SQL).
  2. Konfiguruj parametry tak, aby odpowiadały schematowi bazy danych.
  3. Pobieraj dane za pomocą SqlDataReader, aby przetwarzać wiersze i wiele zestawów wyników.
  4. Modyfikuj dane za pomocą procedur przechowywanych , aby używać parametrów wyjściowych i zwracać wartości.
  5. Użyj programowania asynchronicznego i anulowania, aby dodać anulowanie przez wywołującego i ograniczone limity czasowe.
  6. Obsługuj błędy i komunikaty zanim dodasz ponowienia lub diagnostykę produkcyjną.

Kluczowe funkcje

  • Nowoczesne wsparcie .NET: Działa na aktualnych wersjach .NET i .NET Framework. Podział według wersji znajdziesz w artykule Cykl życia wsparcia.
  • Domyślnie szyfrowane: połączenia szyfrowane TLS, z Encrypt=true domyślnym zaszyfrowaniem. Ustaw Encrypt=Strict dla szyfrowania TDS 8.0.
  • 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: Zintegrowane uwierzytelnianie systemu Windows dla lokalnego środowiska Active Directory i starszych scenariuszy.
  • Always Encrypted: szyfrowanie po stronie klienta dla kolumn poufnych z opcjonalnymi bezpiecznymi enklawami dla operacji w miejscu.
  • Kopiowanie zbiorcze: Wydajne wstawianie rekordów za pomocą SqlBulkCopy.
  • Pula połączeń: Domyślnie włączona. Obecnie jest w trakcie oceny pula V2 typu opt-in.
  • Odporność połączeń: Wbudowane ponawianie połączeń (ConnectRetryCount i ConnectRetryInterval) oraz opcjonalna, konfigurowalna logika ponawiania dla połączeń i poleceń.
  • 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.
  • Tożsamość aplikacji: Ustaw SqlConnection.RegisteredApplication, aby zidentyfikować bibliotekę lub narzędzie wobec programu SQL Server (Microsoft.Data.SqlClient 7.1 i nowszy).

Wprowadzenie

Artykuł Description
Zacznij od sterownika SqlClient Ustaw projekt, stwórz bazę danych, połącz się, zapytaj i dodaj odporność na połączenia.
Zainstaluj, aktualizuj i wdrażaj Microsoft. Data.SqlClient Zainstaluj pakiety NuGet, wybierz wydanie, zaktualizuj sterownik i przygotuj wyjście wdrożenia.
Cykl życia wsparcia Przejrzyj obsługiwane wersje sterowników i daty wsparcia.
Migracja z System.Data.SqlClient do Microsoft. Data.SqlClient Zaktualizuj odwołania do pakietów, przestrzenie nazw, konfigurację oraz zmienione zachowanie sterownika.
Przestrzeń nazw Microsoft.Data.SqlClient i zgodność Dowiedz się, jak SqlClient implementuje ADO.NET oraz o jego kompatybilności z System.Data.SqlClient, .NET i SQL Server.
Co nowego w Microsoft. Data.SqlClient Znajdź aktualne wydania, główne zmiany w aktualizacjach oraz notatki dotyczące wydań na poziomie upstream.

Konfigurowanie i łączenie

Artykuł Description
Połącz się ze źródłem danych Otwieraj i zarządzaj połączeniami oraz reaguj na zmiany stanu połączenia.
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.
Obsługa błędów i wiadomości Wykrywaj błędy i otrzymuj komunikaty informacyjne.

Uwierzytelnianie i zabezpieczenie

Artykuł Description
Najlepsze praktyki w zakresie zabezpieczeń dla Microsoft.Data.SqlClient 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 Wykonuj zaawansowane operacje na zaszyfrowanych danych przy użyciu bezpiecznej enklawy.

Pobieranie i aktualizacja danych

Artykuł Description
Wykonaj polecenie Wykonuj parametryzowane instrukcje SQL i procedury przechowywane.
Adaptery danych i Czytniki danych Strumieniowanie zbiorów wyników lub zapełnianie rozłączonych struktur danych.
Wykonaj wiele poleceń za pomocą SqlBatch Wyślij uporządkowany zbiór poleceń i przetworz ich wyniki.
Dane strumieniowe Przesyłaj duże wartości binarne, tekstowe, XML i JSON bez buforowania pełnej wartości.
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 instrukcji parametryzowanej lub procedury składowanej.
Wiele aktywnych zestawów wyników (MARS) Przeplataj wiele partii w ramach jednego połączenia.

Typy danych

Artykuł Description
Mapowania typów danych SQL Server Mapuj typy SQL Server na .NET i System.Data.SqlTypes typy.
Dane JSON Wyślij i pobierz typ danych SQL Server json.
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 Ponawiaj próby po przejściowych awariach połączeń i wykonywania poleceń zgodnie z ograniczonymi zasadami.
Wysoka dostępność i odzyskiwanie po awarii Połącz się z nasłuchiwaczami grup dostępności i partnerami przełączenia awaryjnego.
Liczniki zdarzeń w programie SqlClient Monitoruj aktywne połączenia, połączenia w grupie oraz inne metryki sterowników.
Włącz śledzenie źródeł zdarzeń Rejestruj szczegółowe zdarzenia sterownika na potrzeby diagnostyki.
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.
Repozytorium GitHub Microsoft.Data.SqlClient Przeczytaj kod źródłowy sterownika, notatki wydania i przykłady.
Przykłady Microsoft.Data.SqlClient Przeglądaj przykłady interfejsów API sterowników w języku C#.
Repozytorium GitHub środowiska uruchomieniowego .NET Przeczytaj kod źródłowy bibliotek wykonawczych .NET.

Prośba o funkcję

Aby zgłosić propozycję funkcji, utwórz zgłoszenie w repozytorium GitHub Microsoft.Data.SqlClient.

Treści powiązane

  • Ostatnia aktualizacja o