Migracja z System.Data.SqlClient do Microsoft. Data.SqlClient

Microsoft. Data.SqlClient jest wspieranym dostawcą nowych funkcji SQL Server w aplikacjach .NET. Zachowuje model programowania ADO.NET używany przez System.Data.SqlClient, ale pakiety, przestrzenie nazw, domyślne i niektóre typy publiczne różnią się.

Traktuj migrację jako aktualizację dostawcy, a nie tylko jako zastąpienie przestrzeni nazw.

Zaplanuj migrację

Przed zmianą kodu:

1. Zapisz wersje usług .NET, System.Data.SqlClient, SQL Server oraz Microsoft SQL, które aplikacja obsługuje.

2. Tryby uwierzytelniania, słowa kluczowe parametrów połączenia, certyfikaty niestandardowe, dostawcy funkcji Always Encrypted, konfiguracja DbProviderFactories, typy zdefiniowane przez użytkownika w SQL Server oraz użycie System.Data.SqlTypes.

3. Uruchom aktualne testy aplikacji i zapisz punkt odniesienia dla zachowania połączenia, zapytań, transakcji, ponownej próby i wydajności.

4. Wyszukaj bezpośrednie i pośrednie odwołania do pakietów:

   dotnet list package --include-transitive
   

Migruj jedną aplikację lub bibliotekę udostępniania danych na raz. Nie przekazuj obiektów właściwych dla danego dostawcy między kodem, który nadal używa System.Data.SqlClient, a kodem używającym Microsoft.Data.SqlClient.

Wymień opakowanie

Usuń jawne odwołanie System.Data.SqlClient do pakietu, jeśli jest obecne:

dotnet remove package System.Data.SqlClient

Dodaj Microsoft. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Jeśli Microsoft. Data.SqlClient 7.0 lub nowszy korzysta z trybu uwierzytelniania Microsoft Entra udostępnionego sterownikiem, dodaj także:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

Aby wybrać wersję i pakiet, zobacz Instalacja, aktualizacja i wdrożenie Microsoft. Data.SqlClient.

Aktualizowanie przestrzeni nazw

Zamień przestrzeń nazw głównego dostawcy:

-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;

Zaktualizuj w pełni kwalifikowane nazwy, aliasy, wygenerowany kod, rejestracje wstrzykiwania zależności, łańcuchy odbicia, konfigurację oraz testowe podwójne wersje odnoszące się do System.Data.SqlClient.

Nie zastępuj ogólnych przestrzeni nazw System.Data ani System.Data.Common. Microsoft.Data.SqlClientnadal używa typów ADO.NET, takich jak CommandType, DbType, IsolationLevel, DataTable, DbConnection, oraz DbCommand z tych przestrzeni nazw.

Niektóre typy specyficzne dla SQL Server zostają przeniesione do innych Microsoft.Data przestrzeni nazw:

W Microsoft.Data.SqlClient wersji 5.0 i późniejszych inne typy SQL Server common language runtime (CLR) pozostają w Microsoft.SqlServer.Server. Zaktualizuj każdy typ na podstawie błędów kompilatora oraz dokumentacji interfejsu API Microsoft.Data.SqlClient, zamiast zastępować całą przestrzeń nazw.

Aktualizacja konfiguracji .NET Framework

Aplikacja, która rozpoznaje dostawców za pomocą DbProviderFactories, może wymagać rejestracji dostawcy w App.config lub Web.config:

<configuration>
  <system.data>
    <DbProviderFactories>
      <add name="SqlClient Data Provider"
           invariant="Microsoft.Data.SqlClient"
           description=".NET data provider for SQL Server"
           type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
    </DbProviderFactories>
  </system.data>
</configuration>

Kod aktualizacji żądający inwariantnej nazwy dostawcy:

DbProviderFactory factory =
    DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");

Nie dodawaj tej konfiguracji, gdy aplikacja tworzy SqlConnection bezpośrednio i nie używa DbProviderFactories.

Przegląd szyfrowania i walidacji certyfikatów

Microsoft. Data.SqlClient używa bezpieczniejszych domyślnych ustawień niż System.Data.SqlClient.

Nie ustawiaj Encrypt=false ani TrustServerCertificate=true jako ogólnej poprawki migracji. Skonfiguruj certyfikat, któremu klient ufa i użyj nazwy serwera odpowiadającej certyfikatowi. Używaj TrustServerCertificate=true tylko w kontrolowanych środowiskach programistycznych, gdzie walidacja nie jest możliwa.

Zmiana na SqlConnectionEncryptOption jest zgodna ze źródłem w typowych przypisaniach poprzez niejawne konwersje, ale jest to zmiana łamiąca binarność. Skompiluj ponownie każdy zestaw, który uzyskuje dostęp do SqlConnectionStringBuilder.Encrypt.

Aby uzyskać szczegółowe informacje, zobacz Szyfrowanie i walidacja certyfikatu.

Przegląd stringów połączeń

Microsoft. Data.SqlClient dodaje słowa kluczowe i aliasy, których System.Data.SqlClient nie rozpoznaje. Na przykład akceptuje aliasy z spacjami takimi jak Application Intent i Multi Subnet Failover.

Nie twórz parametrów połączenia za pomocą Microsoft.Data.SqlClient.SqlConnectionStringBuilder, a następnie nie przekazuj ich do System.Data.SqlClient. Podczas migracji etapowej utrzymuj każdy builder parametry połączenia w parze ze swoim dostawcą.

Sprawdź uwierzytelnianie, szyfrowanie, próbę ponownego próbowania, przełączanie awaryjne oraz certyfikaty w kontekście składni łańcuchów połączeń.

Przejrzyj zachowanie parametru

Parametry daty i czasu testuj wyraźnie:

Określ SqlDbType, długość, precyzję i skalę dla parametrów, w których inferencja typu SQL Server może zmieniać plany zapytań lub zachowanie konwersji. Nie używaj AddWithValue jako skrótu migracyjnego, gdy typ bazy danych jest znany.

Sprawdź referencje dla dostawców tranzytywnych

Bezpośrednie usunięcie pakietu nie gwarantuje, że System.Data.SqlClient zniknie. Run:

dotnet list package --include-transitive

Jeśli obaj dostawcy pozostaną:

1. Zidentyfikuj pakiet, który wprowadza System.Data.SqlClient.
2. Aktualizuj lub wymień tę zależność, gdy to możliwe.
3. Zachowaj specyficzne dla dostawcy typy w granicach zależności, gdy oba muszą pozostać.
4. Używaj jawnych aliasów przestrzeni nazw tylko jako tymczasowego rozwiązania. Nie przekazuj połączenia, transakcji, parametru ani czytnika między operatorami.

Zwróć szczególną uwagę na biblioteki typów CLR programu SQL Server oraz starsze struktury dostępu do danych, które udostępniają typy System.Data.SqlClient w swoich publicznych interfejsach API.

Przegląd zachowań globalizacyjnych

.NET Framework i wersje .NET wcześniejsze niż .NET 5 korzystają z globalizacji NLS (National Language Support) w systemie Windows. Obecne wersje .NET domyślnie wykorzystują International Components for Unicode (ICU) na Windows, Linux i macOS.

Ta różnica czasu wykonywania może zmienić niektóre porównania SqlString. SQL Server wykorzystuje zachowanie porównawcze NLS. Jeśli porównania po stronie klienta SqlString muszą być zgodne z działaniem serwera, przetestuj wartości, których to dotyczy, i zapoznaj się z tematem Globalizacja i ICU. Aplikacja może korzystać z NLS zamiast ICU , gdy jest to potrzebne.

Tryb niezależny od globalizacji nie jest obsługiwany przez Microsoft.Data.SqlClient.

Zweryfikowaj przeniesioną aplikację

Buduj i testuj na każdym obsługiwanym frameworku docelowym i systemie operacyjnym.

Weryfikacja:

• Przywracanie pakietu i opublikowanie wyjścia.
• Uwierzytelnianie SQL, uwierzytelnianie zintegrowane systemu Windows oraz uwierzytelnianie Microsoft Entra używane przez aplikację.
• Negocjacje TLS, walidacja certyfikatów oraz parsowanie parametry połączenia.
• Pulowanie połączeń i odświeżanie tokenów dostępu.
• Typy parametrów, wartości zerowe, precyzja, skala, data i zachowanie czasowe.
• Transakcje, anulowanie, limity czasu, ponowienia i przełączanie awaryjne.
• Zawsze szyfrowane, typy CLR w SQL Server, kopiowanie masowe, powiadomienia o zapytaniach oraz inne funkcje specyficzne dla dostawcy używane przez aplikację.
• Logowanie, liczniki, śledzenie i obsługa wyjątków.

Uruchamiaj reprezentatywne zapytania dla wszystkich obsługiwanych wersji silnika baz danych. Udana kompilacja nie weryfikuje bezpieczeństwa połączenia, zależności w czasie działania ani konwersji danych.

Treści powiązane

• Przestrzeń nazw Microsoft.Data.SqlClient i zgodność
• Informacje o wydaniu i aktualizacje Microsoft.Data.SqlClient
• Ściąga dotycząca portowania w repozytorium SqlClient
• Microsoft. Data.SqlClient API reference