Migrera från System.Data.SqlClient till Microsoft. Data.SqlClient

Microsoft. Data.SqlClient är den stödda leverantören av nya SQL Server-funktioner i .NET-applikationer. Den bevarar ADO.NET-programmeringsmodellen som används av System.Data.SqlClient, men paket, namnrymder, standardinställningar och vissa publika typer skiljer sig åt.

Behandla migreringen som en uppdatering av leverantören, inte bara som en namnrymdsersättning.

Planera migreringen

Innan du ändrar koden:

  1. Registrera de versioner av .NET, System.Data.SqlClient, SQL Server och Microsoft SQL-tjänster som applikationen stödjer.

  2. Inventarieautentiseringslägen, nyckelord för reťazec pripojenia, anpassade certifikat, Always Encryption-leverantörer, DbProviderFactories konfiguration, användardefinierade SQL Server-typer och System.Data.SqlTypes användning.

  3. Kör applikationens aktuella tester och spara en baslinje för anslutning, förfrågan, transaktion, omförsök och prestandabeteende.

  4. Sök direkta och transitiva paketreferenser:

    dotnet list package --include-transitive

Migrera en applikation eller ett delat dataåtkomstbibliotek åt gången. Skicka inte leverantörsspecifika objekt mellan kod som fortfarande använder System.Data.SqlClient och kod som använder Microsoft.Data.SqlClient.

Byt ut paketet

Ta bort en explicit System.Data.SqlClient paketreferens, om den finns:

dotnet remove package System.Data.SqlClient

Lägg till Microsoft. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Om Microsoft. Data.SqlClient 7.0 eller senare använder ett drivrutinstillhandahållet Microsoft Entra-autentiseringsläge, lägg också till följande:

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

För versions- och paketval, se Installera, uppdatera och distribuera Microsoft. Data.SqlClient.

Uppdatera namnområden

Byt ut namnrymden för primär leverantör:

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

Uppdatera fullt kvalificerade namn, alias, genererad kod, beroendeinjektionsregistreringar, reflektionssträngar, konfiguration och testdubblar som refererar till System.Data.SqlClient.

Byt inte ut general- System.Data eller System.Data.Common namnrymder. Microsoft.Data.SqlClientfortsätter att använda ADO.NET-typer såsom CommandType, DbType, , IsolationLevel, DataTable, DbConnectionoch DbCommand från dessa namnrymder.

Vissa SQL Server-specifika typer flyttar till andra Microsoft.Data namnrymder:

Type Föregående namnområde Microsoft.Data.SqlClient-namnrymd
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

I Microsoft.Data.SqlClient 5.0 och senare finns andra SQL Server common language runtime (CLR)-typer kvar i Microsoft.SqlServer.Server. Uppdatera varje typ utifrån kompilatorfel och Microsoft.Data.SqlClient API-referensen, i stället för att ersätta hela namnrymden.

Uppdatera konfigurationen av .NET Framework

Ett program som slår upp providers via DbProviderFactories kan behöva en providerregistrering i App.config eller 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>

Uppdatera koden som begär det leverantörsinvarianta namnet:

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

Lägg inte till denna konfiguration när applikationen skapar SqlConnection direkt och inte använder DbProviderFactories.

Granska kryptering och certifikatvalidering

Microsoft. Data.SqlClient använder säkrare standardinställningar än System.Data.SqlClient.

Behavior System.Data.SqlClient Microsoft.Data.SqlClient
Standardkryptering Encrypt=false Encrypt=true Med start från version 4.0
Verifiering av servercertifikat Validerar certifikatet endast när klientkryptering är aktiverad Från och med version 2.0 valideras certifikatet enligt TrustServerCertificate när servern tvingar kryptering, även om Encrypt=false
Strikt kryptering Stöds ej Encrypt=Strict med start från version 5.0 för TDS 8.0-kompatibla servrar
Typ: SqlConnectionStringBuilder.Encrypt bool SqlConnectionEncryptOption Med start från version 5.0

Ange inte vare sig Encrypt=false eller TrustServerCertificate=true som en allmän lösning för migrering. Konfigurera ett certifikat som klienten litar på och använd ett servernamn som matchar certifikatet. Använd TrustServerCertificate=true endast för kontrollerade utvecklingsmiljöer där validering inte är möjlig.

Ändringen till SqlConnectionEncryptOption är källkodskompatibel i vanliga tilldelningar genom implicita konverteringar, men det är en binär brytande förändring. Kompilera om varje assembly som har åtkomst till SqlConnectionStringBuilder.Encrypt.

Mer information finns i Kryptering och certifikatverifiering.

Granska anslutningssträngar

Microsoft. Data.SqlClient lägger till nyckelord och alias som System.Data.SqlClient inte känner igen. Till exempel accepterar den aliaser med mellanrum som Application Intent och Multi Subnet Failover.

Bygg inte en reťazec pripojenia med Microsoft.Data.SqlClient.SqlConnectionStringBuilder och skicka den sedan till System.Data.SqlClient. Under en stegvis migrering, håll varje reťazec pripojenia-byggare ihopparad med dess leverantör.

Granska autentisering, kryptering, omförsök, failover och certifikatnyckelord mot anslutningssträngens syntax.

Granska parameterbeteende

Testdatum och tidparameter explicit:

Parameter System.Data.SqlClient-beteende Microsoft.Data.SqlClient-beteende
DbType.Time med ett DateTime värde Accepterar värdet Använd ett TimeSpan värde
DbType.Date med ett DateTime värde Kan skicka datum- och tidkomponenter Trunkerar tidskomponenterna

Specificera SqlDbType, längd, precision och skala för parametrar där SQL Server-typinferens kan ändra frågeplaner eller konverteringsbeteende. Använd inte AddWithValue som en genväg för migration när databastypen är känd.

Kontrollera referenser för transitiva leverantörer

Att ta bort ett paket garanterar inte att System.Data.SqlClient försvinner. Run:

dotnet list package --include-transitive

Om båda vårdgivarna kvarstår:

  1. Identifiera paketet som tar in System.Data.SqlClient.
  2. Uppdatera eller byt ut det beroendet när det är möjligt.
  3. Håll leverantörsspecifika typer inom beroendegränsen när båda måste finnas kvar.
  4. Använd explicita namnrymdalias endast som ett tillfälligt hjälpmedel. Skicka inte en anslutning, transaktion, parameter eller läsare från en leverantör till en annan.

Var särskilt uppmärksam på SQL Server CLR-typbibliotek och äldre dataåtkomstramverk som exponerar System.Data.SqlClient typer i sina publika API:er.

Granska globaliseringsbeteende

.NET Framework och .NET-versioner före .NET 5 använder National Language Support (NLS) globalisering på Windows. Nuvarande .NET-versioner använder International Components for Unicode (ICU) som standard på Windows, Linux och macOS.

Denna skillnad i körtid kan ändra vissa SqlString jämförelser. SQL Server använder NLS-jämförelsebeteende. Om klientjämförelser måste matcha serverbeteendeSqlString, testa påverkade värden och granska Globalization och ICU. En applikation kan använda NLS istället för intensivvård vid behov.

Globaliseringsinvariant läge stöds inte av Microsoft. Data.SqlClient.

Validera den migrerade applikationen

Bygg och testa på varje stödd målramverk och operativsystem.

Validera:

  • Paketåterställning och publicerade utdata.
  • SQL-autentisering, Windows-integrerad autentisering och Microsoft Entra-autentisering används av applikationen.
  • TLS-förhandling, certifikatvalidering och reťazec pripojenia-parsing.
  • Anslutningspoolning och uppdatering av access-token.
  • Parametertyper, nollvärden, precision, skala, datum och tidsbeteende.
  • Transaktioner, annullering, tidsgränser, nya försök och automatisk växling vid fel.
  • Always Encrypted, SQL Server CLR-typer, masskopiering, frågeaviseringar och andra leverantörsspecifika funktioner som används av applikationen.
  • Loggning, räknare, spårning och hantering av undantag.

Kör representativa frågor mot alla stödda databasmotorversioner. En lyckad kompilering validerar inte anslutningssäkerhet, beroenden i körtid eller datakonverteringar.

Relaterat innehåll

  • Last updated on