Przestrzeń nazw Microsoft.Data.SqlClient i zgodność

Przestrzeń nazw Microsoft.Data.SqlClient zawiera obsługiwanego dostawcę danych .NET dla baz danych zgodnych z SQL Server. Początkowo był forkiem System.Data.SqlClient i zachowuje znany model programowania ADO.NET, jednocześnie wprowadzając nowe funkcje SQL Server niezależnie od środowiska uruchomieniowego .NET.

Użyj Microsoft.Data.SqlClient do nowych opracowań.

Zainstaluj i zaimportuj przestrzeń nazw

Dodaj pakiet NuGet:

dotnet add package Microsoft.Data.SqlClient

Zaimportuj przestrzeń nazw:

using Microsoft.Data.SqlClient;

Większość aplikacji używa SqlConnection, SqlCommand, SqlParameter, SqlDataReader, oraz .SqlTransaction Pełny publiczny interfejs API opisano w dokumentacji interfejsu API Microsoft.Data.SqlClient.

Związek z ADO.NET

ADO.NET to model dostępu do danych wbudowany w .NET. Definiuje abstrakcje niezależne od dostawcy w przestrzeni nazw System.Data.Common, a Microsoft.Data.SqlClient dostarcza konkretne implementacje.

Abstrakcja ADO.NET Typ SqlClient Purpose
DbConnection SqlConnection Otwiera logiczne połączenie z jedną bazą danych.
DbCommand SqlCommand Wykonuje tekst Transact-SQL (T-SQL) lub procedurę przechowywaną.
DbParameter SqlParameter Wysyła wpisaną wartość oddzielnie od tekstu polecenia.
DbDataReader SqlDataReader Strumieniuje wiersze wyników z serwera.
DbTransaction SqlTransaction Grupuje polecenia w jedną transakcję, dzięki czemu są zatwierdzane lub wycofywane jako całość.
DbDataAdapter SqlDataAdapter Wypełnia i aktualizuje odłączone obiekty DataSet i DataTable.
DbBatch SqlBatch Wysyła wiele poleceń w jednej partii w obsługiwanych platformach docelowych.

Microsoft. Data.SqlClient oferuje także specyficzne dla SQL Server API takie jak:

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • Specyficzna dla SQL Server uwierzytelnianie, szyfrowanie i wsparcie dla typów danych

Programuj przeciwko abstrakcjom ADO.NET, gdy biblioteka musi obsługiwać wielu dostawców baz danych. Używaj typów SqlClient, gdy aplikacja celuje w SQL Server i potrzebuje funkcji specyficznych dla dostawcy, takich jak uwierzytelnianie Microsoft Entra, Always Encrypted, kopiowanie masowe, parametry tabelowe lub konfigurowalna logika ponawiania prób. Zachowaj kod specyficzny dla dostawcy za granicą dostępu do danych, jeśli reszta aplikacji musi pozostać niezależna od dostawcy.

Dostęp online i offline

Dostęp połączony utrzymuje połączenie otwarte podczas wykonywania polecenia i podczas odczytywania jego wyników przez aplikację. Typowe żądanie przebiega następująco:

  1. Utwórz SqlConnection z parametrów połączenia, a następnie go otwórz.
  2. Utwórz SqlCommand i dodaj wartości SqlParameter.
  3. Wykonaj polecenie .
  4. Przetwórz wartość skalarną, liczbę zmienionych wierszy lub SqlDataReader.
  5. Usuń czytnik, polecenie i połączenie.

Korzystaj z dostępu połączonego do większości API webowych, usług, pracowników i aplikacji wiersza poleceń. SqlDataReader przetwarza wiersze strumieniowo i zwykle zużywa mniej pamięci niż ładowanie całego wyniku do DataSet.

Dostęp rozłączony używa SqlDataAdapter do kopiowania danych do znajdującego się w pamięci DataSet lub DataTable. Aplikacja może zamknąć połączenie podczas odczytu lub zmiany danych w pamięci, a następnie ponownie się połączyć, aby przesłać aktualizacje. Używaj go do wiązania danych, relacji i ograniczeń w pamięci, edycji offline, których zmiany później scalasz, lub istniejącej aplikacji opartej na DataAdapterach. Dla nowych usług zorientowanych na żądania zaczynamy od SqlCommand i SqlDataReader.

Czas życia obiektu i współbieżność

Otwórz i zwolnij po jednym SqlConnection dla każdej jednostki pracy. Pula połączeń ponownie wykorzystuje bazowe połączenie fizyczne, więc nie trzymaj jednego globalnego połączenia otwartego przez cały okres życia aplikacji. Szybko usuwaj połączenia, polecenia, czytniki, transakcje i kopiuj obiekty masowo. W kodzie asynchronicznym używamy await using dla typów, które implementują IAsyncDisposable w docelowym środowisku, takich jak SqlConnection i SqlDataReader na platformie .NET, oraz zwykłych using dla typów implementujących tylko IDisposable, takich jak SqlBulkCopy.

SqlConnection, SqlCommand, SqlDataReader oraz SqlTransaction nie obsługują współbieżnego użycia przez wiele wątków. Zapewnij każdej współbieżnej operacji osobne połączenie i korzystaj z puli połączeń. Multiple Active Result Sets (MARS) umożliwia uzyskanie więcej niż jednego aktywnego zestawu wyników w ramach jednego połączenia, ale nie sprawia, że obiekty SqlClient są bezpieczne wątkowo.

Związek z System.Data.SqlClient

System.Data.SqlClient jest starszym dostawcą, który wchodzi w skład platformy .NET Framework oraz wcześniejszych wydań platformy .NET. Microsoft.Data.SqlClient używa wielu tych samych nazw typów, ale posiada różne pakiety, przestrzenie nazw, domyślne konfiguracje, funkcje i polityki wsparcia.

Nie odwołuj się do obu dostawców w nowym kodzie aplikacji. Typy o tej samej nazwie z obu pakietów nie są wymienne. System.Data.SqlClient.SqlConnection, na przykład, nie może zostać przekazane w miejscu, w którym wymagane jest Microsoft.Data.SqlClient.SqlConnection.

Migracja zwykle zaczyna się od dodania pakietu Microsoft.Data.SqlClient i zmiany odniesień do przestrzeni nazw, ale musisz także przejrzeć szyfrowanie połączenia, parametry, konfigurację, zależności tranzytywne oraz zachowanie w czasie działania. Postępuj zgodnie z instrukcjami w Migracja z System.Data.SqlClient do Microsoft.Data.SqlClient przed wdrożeniem.

Zgodność wersji

Wersja pakietu sterownika jest niezależna od wersji .NET aplikacji oraz wersji silnika bazy danych. Sprawdź wszystkie trzy:

Component Co należy zweryfikować
Microsoft.Data.SqlClient Linia wydania jest obsługiwana i zawiera funkcje, z których korzysta Twoja aplikacja.
.NET lub .NET Framework Aplikacja celuje w czas działania obsługiwany przez tę wersję sterownika.
Baza danych zgodna z SQL Server Wersja sterownika obsługuje wersję bazy danych, a serwer obsługuje dowolną żądaną funkcję protokołu, taką jak TDS 8.0.

Aktualne macierze można znaleźć w cyklu życia wsparcia sterowników SqlClient.

Zmiany specyficzne dla wersji

Wersje sterowników mogą dodawać API, przenosić opcjonalne zależności oraz zmieniać bezpieczne domyślne ustawienia. Przeglądaj zmiany przed każdą drobną lub większą aktualizacją.

Oto kilka przykładów:

  • W wersji 4.0 ustawienie Encrypt zostało zmienione tak, aby domyślnie miało wartość true.
  • Wersja 5.0 wprowadziła SqlConnectionEncryptOption i Encrypt=Strict dla TDS 8.0.
  • Wersja 5.2 wprowadziła SqlBatch dla obsługiwanych nowoczesnych platform docelowych .NET.
  • Wersja 7.0 przeniosła uwierzytelnianie Microsoft Entra udostępniane przez sterownik do Microsoft.Data.SqlClient.Extensions.Azure.

Zobacz Co nowego w produkcie Microsoft.Data.SqlClient, aby uzyskać linki do informacji o wydaniu oraz podsumowanie aktualizacji.

Niektóre funkcje wykorzystują typy poza główną przestrzenią nazw lub opcjonalne pakiety.

Przestrzeń nazw lub pakiet Purpose
Microsoft.Data.SqlClient.Server Implementacje SqlClient elementów SqlDataRecord i SqlMetaData.
Microsoft.Data.SqlTypes Typy specyficzne dla SqlClient, takie jak SqlFileStream, SqlJson, oraz SqlVector<T>.
Microsoft.Data.SqlClient.Diagnostics Silnie typowane ładunki zdarzeń diagnostycznych.
Microsoft.Data.SqlClient.Extensions.Azure Uwierzytelnianie Microsoft Entra zapewniane przez sterownik dla wersji 7.0 i nowszych.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Integracja z usługą Azure Key Vault dla funkcji Always Encrypted.

Nie wyciągaj wniosków o wymaganiach pakietu tylko na podstawie przestrzeni nazw. Podążaj za artykułem o funkcjach oraz informacjami o zależności pakietu NuGet dla wersji sterownika, której używasz.

Treści powiązane

  • Ostatnia aktualizacja o