Migrace ze System.Data.SqlClient na Microsoft. Data.SqlClient

Microsoft. Data.SqlClient je podporovaný poskytovatel nových funkcí SQL Server v .NET aplikacích. Zachovává programovací model ADO.NET používaný System.Data.SqlClient, ale balíčky, jmenné prostory, výchozí verze a některé veřejné typy se liší.

Migraci berte jako aktualizaci poskytovatele, ne jen jako náhradu jmenného prostoru.

Plánování migrace

Před změnou kódu:

  1. Zaznamenejte verze služeb .NET, System.Data.SqlClient, SQL Server a Microsoft SQL, které aplikace podporuje.

  2. Přehled režimů ověřování, klíčových slov připojovacího řetězce, vlastních certifikátů, poskytovatelů Always Encrypted, konfigurace DbProviderFactories, uživatelsky definovaných typů SQL Serveru a použití System.Data.SqlTypes.

  3. Spusť aktuální testy aplikace a ulož si základní hodnotu pro připojení, dotazy, transakce, opakování a výkonnostní chování.

  4. Vyhledejte přímé a tranzitivní reference balíčků:

    dotnet list package --include-transitive

Migrujte jednu aplikaci nebo sdílenou knihovnu pro přístup k datům najednou. Nepředávajte objekty specifické pro poskytovatele mezi kód, který stále používá System.Data.SqlClient , a kódem, který používá Microsoft.Data.SqlClient.

Vyměňte balíček

Odstraňte explicitní System.Data.SqlClient odkaz na balík, pokud je přítomen:

dotnet remove package System.Data.SqlClient

Přidejte Microsoft. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Pokud Microsoft. Data.SqlClient 7.0 nebo novější používá autentizační režim Microsoft Entra poskytovaný ovladačem, přidejte také:

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

Pro výběr verze a balíčku viz Instalace, aktualizace a nasazení Microsoft. Data.SqlClient.

Aktualizovat obory názvů

Nahraďte primární jmenný prostor poskytovatele:

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

Aktualizujte plně kvalifikovaná jména, aliasy, generovaný kód, registrace závislostních injekcí, reflexní řetězce, konfigurace a testovací dvojníky, které odkazují na System.Data.SqlClient.

Nenahrazujte obecné System.Data ani System.Data.Common jmenné prostory. Microsoft.Data.SqlClientnadále používá typy ADO.NET jako CommandType, DbType, IsolationLevel, DataTable, DbConnection, a DbCommand z těchto jmenných prostorů.

Některé typy specifické pro SQL Server se přesouvají do jiných Microsoft.Data jmenných prostorů:

Typ Předchozí jmenný prostor Obor názvů Microsoft.Data.SqlClient
SqlDataRecord, SqlMetaData Microsoft.SqlServer.Server Microsoft.Data.SqlClient.Server
SqlFileStream System.Data.SqlTypes Microsoft.Data.SqlTypes
SqlNotificationRequest System.Data.Sql Microsoft.Data.Sql
OperationAbortedException System.Data Microsoft.Data

Ve verzi 5.0 a novějších systému Microsoft.Data.SqlClient zůstávají ostatní typy modulu common language runtime (CLR) serveru SQL Server v Microsoft.SqlServer.Server. Aktualizujte jednotlivé typy podle chyb kompilátoru a referenční dokumentace k rozhraní API Microsoft.Data.SqlClient, namísto nahrazení celého oboru názvů.

Aktualizace konfigurace .NET Framework

Aplikace, která řeší poskytovatele skrz DbProviderFactories , může vyžadovat registraci poskytovatele v App.config nebo 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>

Aktualizujte kód, který požaduje invariantní název poskytovatele:

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

Nepřidávejte tuto konfiguraci, když aplikace vytváří SqlConnection přímo a nepoužívá DbProviderFactories.

Kontrola šifrování a ověřování certifikátů

Microsoft. Data.SqlClient používá bezpečnější výchozí nastavení než System.Data.SqlClient.

Chování System.Data.SqlClient Microsoft.Data.SqlClient
Výchozí šifrování Encrypt=false Encrypt=true Od verze 4.0
Ověření certifikátu serveru Certifikát ověřuje pouze tehdy, když je povoleno šifrování klienta Počínaje verzí 2.0 se certifikát ověřuje podle TrustServerCertificate, když server vynutí šifrování, i když Encrypt=false
Přísné šifrování Nepodporováno Encrypt=Strict počínaje verzí 5.0 pro servery podporující TDS 8.0
typ SqlConnectionStringBuilder.Encrypt bool SqlConnectionEncryptOption Od verze 5.0

Nenastavujte Encrypt=false ani TrustServerCertificate=true jako obecné řešení migrace. Nakonfigurujte certifikát, kterému klient důvěřuje, a použijte název serveru, který odpovídá certifikátu. Používejte TrustServerCertificate=true pouze pro kontrolovaná vývojová prostředí, kde validace není možná.

Změna na SqlConnectionEncryptOption je při běžném přiřazení díky implicitním konverzím kompatibilní na úrovni zdrojového kódu, ale narušuje binární kompatibilitu. Překompilujte každé sestavení, které přistupuje k SqlConnectionStringBuilder.Encrypt.

Podrobnosti najdete v tématu Šifrování a ověření certifikátu.

Zkontrolujte spojovací řetězce

Microsoft. Data.SqlClient přidává klíčová slova a aliasy, které System.Data.SqlClient nerozpoznává. Například přijímá aliasy s mezerami jako Application Intent a Multi Subnet Failover.

Nevytvářejte připojovací řetězec pomocí Microsoft.Data.SqlClient.SqlConnectionStringBuilder a pak ho nepředávejte do System.Data.SqlClient. Během postupné migrace ponechte každý tvůrce připojovacího řetězce spárovaný s odpovídajícím poskytovatelem.

Zkontrolujte autentizaci, šifrování, opakované pokusy, failover a certifikační klíčová slova vůči syntaxi spojovacích řetězců.

Zkontrolovat chování parametrů

Testujte parametry data a času explicitně:

Parameter Chování System.Data.SqlClient Chování Microsoft.Data.SqlClient
DbType.Time s hodnotou DateTime Přijímá hodnotu Použijte TimeSpan hodnotu
DbType.Date s hodnotou DateTime Může posílat složky data a času Zkracuje časové složky

Specifikujte SqlDbType, délku, přesnost a měřítko pro parametry, kde může inference typu SQL Server změnit plány dotazů nebo chování konverze. Nepoužívejte AddWithValue je jako zkratku pro migraci, když je typ databáze známý.

Zkontrolujte tranzitivní odkazy na poskytovatele

Přímé odstranění balíčku nezaručuje, že je to System.Data.SqlClient pryč. Běh:

dotnet list package --include-transitive

Pokud oba poskytovatelé zůstanou:

  1. Identifikujte balíček, který přináší System.Data.SqlClient.
  2. Aktualizujte nebo vyměňte tuto závislost, pokud je to možné.
  3. Udržujte typy specifické pro poskytovatele v rámci hranic závislostí, pokud musí zůstat obě varianty.
  4. Používejte explicitní aliasy jmenného prostoru pouze jako dočasnou pomůcku. Nepředávajte spojení, transakci, parametr nebo čtečku od jednoho poskytovatele k druhému.

Věnujte zvláštní pozornost knihovnám typu SQL Server CLR a starším datovým přístupovým rámcům, které zpřístupňují System.Data.SqlClient typy ve svých veřejných API.

Zkontrolujte chování globalizace

.NET Framework a verze .NET před .NET 5 používají pro globalizaci v systému Windows technologii National Language Support (NLS). Současné verze .NET používají ve výchozím nastavení International Components for Unicode (ICU) napříč Windows, Linuxem a macOS.

Tento rozdíl v čase běhu může ovlivnit některá SqlString srovnání. SQL Server používá způsob porovnávání NLS. Pokud se porovnání na straně klienta SqlString musí shodovat s chováním serveru, otestujte dotčené hodnoty a projděte si Globalizaci a ICU. Aplikace může v případě potřeby použít NLS místo JIP.

Režim nezávislý na globalizaci není v Microsoft.Data.SqlClient podporován.

Validace migrované aplikace

Postavte a testujte na všech podporovaných cílových frameworkech a operačních systémech.

Ověření:

  • Obnova balíčku a publikovaný výstup.
  • SQL autentizace, integrovaná autentizace Windows a Microsoft Entra autentizace používaná aplikací.
  • Vyjednávání TLS, ověřování certifikátů a parsování připojovacího řetězce.
  • Poolování spojení a obnova přístupového tokenu.
  • Typy parametrů, nulové hodnoty, přesnost, škála, datum a časové chování.
  • Transakce, zrušení, časové limity, opakovaní a failover.
  • Always Encrypted, typy CLR pro SQL Server, hromadné kopírování, oznámení o dotazech a další funkce specifické pro poskytovatele používané aplikací.
  • Záznamy, počítadla, trasování a zpracování výjimek.

Spusť reprezentativní dotazy na všech podporovaných verzích databázového enginu. Úspěšná kompilace nevaliduje bezpečnost spojení, závislosti v běhu ani převody dat.

Související obsah

  • Last updated on