Microsoft.Data.SqlClient

Microsoft.Data.SqlClient to aktualna biblioteka .NET do łączenia się z SQL Server, następca System.Data.SqlClient.

Microsoft.Data.SqlClient jako klient SQL Server w aplikacjach .NET

Microsoft.Data.SqlClient jest biblioteką kliencką dla platformy .NET, przeznaczoną do komunikacji z bazą danych Microsoft SQL Server oraz usługami opartymi na SQL Server. Pakiet jest dystrybuowany za pośrednictwem NuGet, a jego główne klasy znajdują się w przestrzeni nazw Microsoft.Data.SqlClient. Biblioteka nie jest silnikiem bazy danych, nie przechowuje samodzielnie tabel i nie zastępuje działającej instancji SQL Server. Pełni funkcję warstwy pośredniej między kodem aplikacji a serwerem, obsługując połączenia, wysyłanie poleceń, odbieranie wyników i wykonywanie transakcji.

Najczęściej używane typy to SqlConnection, SqlCommand, SqlDataReader, SqlDataAdapter, SqlTransaction oraz SqlParameter. SqlConnection otwiera kanał komunikacji na podstawie parametrów połączenia, SqlCommand wykonuje instrukcje SQL albo procedury składowane, a SqlDataReader umożliwia sekwencyjny odczyt wierszy. Biblioteka korzysta z protokołu TDS używanego przez SQL Server, lecz szczegóły tego protokołu są ukryte przed typowym kodem aplikacji.

Przeniesienie kodu z System.Data.SqlClient

Microsoft.Data.SqlClient powstał jako następca System.Data.SqlClient, dlatego podstawowy model programowania pozostaje podobny. W wielu projektach migracja zaczyna się od zmiany zależności NuGet oraz przestrzeni nazw z System.Data.SqlClient na Microsoft.Data.SqlClient. Same nazwy klas, takie jak SqlConnection i SqlCommand, mogą wyglądać identycznie, ale nie oznacza to pełnej zamienności bibliotek w każdej aplikacji. Typy pochodzące z obu przestrzeni nazw są różnymi klasami i nie można mieszać ich bezpośrednio w tych samych sygnaturach metod lub deklaracjach zależności.

Podczas migracji trzeba przejrzeć fabryki połączeń, warstwę dostępu do danych, konfigurację uwierzytelniania oraz testy integracyjne. Znaczenie mają również różnice w domyślnych ustawieniach bezpieczeństwa i w obsłudze nowych funkcji SQL Server. Po zmianie pakietu warto sprawdzić logowanie za pomocą SQL Authentication, Windows Authentication lub mechanizmów Microsoft Entra, a także zachowanie aplikacji przy nieprawidłowym certyfikacie serwera. Nie należy zakładać, że sama kompilacja potwierdza poprawność migracji, ponieważ część problemów ujawnia się dopiero podczas otwierania połączenia albo wykonywania zapytania.

Połączenia, parametry i wykonywanie zapytań

Połączenie z SQL Server jest konfigurowane przez connection string, czyli ciąg parametrów określających między innymi nazwę serwera, bazę danych, sposób uwierzytelniania, szyfrowanie i wymaganie weryfikacji certyfikatu. Obiekt SqlConnection powinien być używany w kontrolowanym zakresie i poprawnie zwalniany, ponieważ biblioteka korzysta z puli połączeń. Zamknięcie obiektu zwykle zwalnia logiczne połączenie do puli, dzięki czemu następne operacje mogą ponownie wykorzystać istniejące zasoby zamiast za każdym razem tworzyć połączenie od początku.

Wartości przekazywane do zapytania powinny być reprezentowane przez SqlParameter, a nie przez konkatenację tekstu SQL i danych wejściowych. Parametryzacja oddziela instrukcję od wartości, ogranicza ryzyko wstrzyknięcia SQL i pozwala bibliotece prawidłowo przekazać typ danych do SQL Server. Przy operacjach asynchronicznych stosuje się między innymi metody OpenAsync, ExecuteReaderAsync, ExecuteNonQueryAsync i ExecuteScalarAsync. Należy przy tym poprawnie obsługiwać anulowanie, wyjątki oraz czas oczekiwania określony przez Connect Timeout i Command Timeout, ponieważ dotyczą one różnych etapów pracy.

Biblioteka obsługuje transakcje lokalne przez SqlTransaction. Transakcja pozwala zatwierdzić powiązany zestaw zmian albo wycofać go w przypadku błędu. Nie rozwiązuje jednak problemów logicznych w samym modelu danych: aplikacja nadal musi określić właściwą kolejność operacji, zakres transakcji i reakcję na konflikt współbieżności. Odczytywanie wyników przez SqlDataReader wymaga również zwracania uwagi na kolejność kolumn, wartości NULL oraz zgodność typów SQL Server z typami używanymi w kodzie .NET.

Bezpieczeństwo i rozpoznawanie problemów z biblioteką

Microsoft.Data.SqlClient obsługuje szyfrowanie połączenia z SQL Server oraz weryfikację certyfikatu serwera zgodnie z ustawieniami connection stringa i środowiska. Parametr Encrypt określa, czy komunikacja ma być szyfrowana, natomiast TrustServerCertificate wpływa na to, czy certyfikat serwera jest weryfikowany przez zaufany łańcuch certyfikatów. Ustawienie bezkrytycznego zaufania do certyfikatu może ukryć problem konfiguracyjny i nie powinno być traktowane jako uniwersalna naprawa błędu połączenia. Przy diagnozie trzeba rozdzielić problem z nazwą hosta, portem, zaporą sieciową, uwierzytelnianiem, certyfikatem i uprawnieniami do konkretnej bazy.

Biblioteka może współpracować z mechanizmami Microsoft Entra Authentication oraz z funkcją Always Encrypted, która pozwala chronić wybrane wartości podczas przechowywania i przetwarzania zgodnie z konfiguracją SQL Server i aplikacji. Te funkcje wymagają odpowiednich ustawień po obu stronach i nie są aktywowane samą instalacją pakietu. Błąd zgłoszony jako SqlException może pochodzić z serwera, sieci albo parametrów logowania, a nie z błędu w implementacji biblioteki. Przy analizie należy zapisać wersję używanego pakietu, typ aplikacji .NET, treść komunikatu, numer błędu SQL Server oraz etap, na którym operacja się zatrzymała, bez ujawniania haseł i pełnych danych uwierzytelniających.

W przypadku nieprawidłowego działania aplikacji korzystającej z Microsoft.Data.SqlClient sprawdza się najpierw zgodność pakietu z docelowym środowiskiem .NET, poprawność przestrzeni nazw i brak jednoczesnego używania niezgodnych typów obu bibliotek. Następnie weryfikuje się connection string, dostępność SQL Server, certyfikat TLS, metodę uwierzytelniania, uprawnienia konta oraz parametry czasu oczekiwania. Taka kolejność pozwala odróżnić błąd kodu od problemu konfiguracji lub dostępności samego silnika SQL Server.