Migrer van System.Data.SqlClient naar Microsoft. Data.SqlClient

Microsoft. Data.SqlClient is de ondersteunde aanbieder van nieuwe SQL Server-functies in .NET-applicaties. Het behoudt het ADO.NET-programmeermodel dat door System.Data.SqlClientwordt gebruikt, maar de pakketten, namespaces, standaarden en sommige publieke types verschillen.

Behandel de migratie als een provider-update, niet alleen als een vervanging van de naamruimte.

De migratie plannen

Voordat je de code verandert:

1. Noteer de versies van .NET, System.Data.SqlClient, SQL Server en Microsoft SQL-diensten die de applicatie ondersteunt.

2. Inventariseer authenticatiemodi, sleutelwoorden voor verbindingsreeksen, aangepaste certificaten, Always Encrypted-providers, de configuratie van DbProviderFactories, door de gebruiker gedefinieerde typen van SQL Server en het gebruik van System.Data.SqlTypes.

3. Voer de huidige tests van de applicatie uit en sla een basislijn op voor verbindings-, query-, transactie-, herpoging- en prestatiegedrag.

4. Zoek directe en transitieve pakketreferenties:

   dotnet list package --include-transitive
   

Migreer één applicatie of gedeelde datatoegangsbibliotheek tegelijk. Geef geen provider-specifieke objecten door tussen code die nog steeds gebruikt System.Data.SqlClient en code die .Microsoft.Data.SqlClient

Vervang het pakket

Verwijder een expliciete System.Data.SqlClient pakketreferentie, indien aanwezig:

dotnet remove package System.Data.SqlClient

Voeg Microsoft toe. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Als Microsoft. Data.SqlClient 7.0 of later een door de driver geleverde Microsoft Entra-authenticatiemodus gebruikt, voeg dan ook toe:

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

Voor versie- en pakketselectie, zie Installeren, updaten en deployen Microsoft. Data.SqlClient.

Naamruimten bijwerken

Vervang de naamruimte van de primaire provider:

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

Werk de volledig gekwalificeerde namen, aliassen, gegenereerde code, registraties voor afhankelijkheidsinjectie, reflectiestrings, configuratie en testdubbels bij die verwijzen naar System.Data.SqlClient.

Vervang de algemene System.Data of System.Data.Common naamruimtes niet. Microsoft.Data.SqlClientblijft ADO.NET-typen gebruiken zoals CommandType, DbType, , IsolationLevel, DataTable, DbConnectionen DbCommand uit die naamruimtes.

Sommige SQL Server-specifieke types verplaatsen zich naar andere Microsoft.Data namespaces:

In Microsoft.Data.SqlClient 5.0 en later blijven andere SQL Server common language runtime (CLR)-typen in Microsoft.SqlServer.Server. Werk elk type bij van compilerfouten en de Microsoft. Data.SqlClient API-referentie, in plaats van de hele naamruimte te vervangen.

Update de configuratie van .NET Framework

Een applicatie die providers via DbProviderFactories omzet, heeft mogelijk een providerregistratie nodig in App.config of 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>

Werk de code bij waarmee de provider-invariante naam wordt opgevraagd:

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

Voeg deze configuratie niet toe wanneer de applicatie direct aanmaakt SqlConnection en niet gebruikt DbProviderFactories.

Bekijk encryptie en certificaatvalidatie

Microsoft. Data.SqlClient gebruikt veiligere standaardinstellingen dan System.Data.SqlClient.

Stel Encrypt=false of TrustServerCertificate=true niet in als een algemene migratieoplossing. Configureer een certificaat dat de client vertrouwt en gebruik een servernaam die overeenkomt met het certificaat. TrustServerCertificate=true Gebruik het alleen voor gecontroleerde ontwikkelomgevingen waar validatie niet mogelijk is.

De wijziging naar SqlConnectionEncryptOption is broncompatibel in veelvoorkomende toewijzingen via impliciete conversies, maar het is een binaire breuk. Compileer elke assembly die toegang heeft tot SqlConnectionStringBuilder.Encrypt opnieuw.

Voor details, zie Versleuteling en certificaatvalidatie.

Bekijk verbindingsstrings

Microsoft. Data.SqlClient voegt trefwoorden en aliassen toe die System.Data.SqlClient niet herkent. Zo accepteert het aliasen met ruimtes zoals Application Intent en Multi Subnet Failover.

Bouw geen verbindingsreeks met Microsoft.Data.SqlClient.SqlConnectionStringBuilder en geef die dan door aan System.Data.SqlClient. Houd tijdens een gefaseerde migratie elke verbindingsreeks builder gekoppeld aan zijn provider.

Controleer authenticatie, encryptie, herkansing, failover en certificaatsleutelwoorden op basis van de syntaxis van de verbindingsstring.

Bekijk het gedrag van parameters

Test datum- en tijdparameters expliciet:

Specificeer SqlDbType, lengte, precisie en schaal voor parameters waarbij SQL Server-type-inferentie queryplannen of conversiegedrag kan veranderen. Gebruik het niet AddWithValue als migratiesnelkoppeling wanneer het databasetype bekend is.

Controleer transitieve providerreferenties

Een directe verwijdering van pakketten garandeert niet dat dat System.Data.SqlClient weg is. Voer de volgende opdracht uit:

dotnet list package --include-transitive

Als beide zorgverleners blijven:

1. Identificeer het pakket dat System.Data.SqlClient installeert.
2. Werk die afhankelijkheid bij of vervang die afhankelijkheid wanneer mogelijk.
3. Houd provider-specifieke types binnen de afhankelijkheidsgrens wanneer beide moeten blijven.
4. Gebruik expliciete namespace-aliasen alleen als tijdelijke hulp. Geef geen verbinding, transactie, parameter of lezer door van de ene provider naar de andere.

Let vooral specifiek op SQL Server CLR-typebibliotheken en oudere frameworks voor gegevenstoegang die System.Data.SqlClienttypen in hun openbare API’s blootstellen.

Bekijk globaliseringsgedrag

.NET Framework en .NET-versies vóór .NET 5 gebruiken National Language Support (NLS) globalisering op Windows. De huidige .NET-versies gebruiken standaard International Components for Unicode (ICU) op Windows, Linux en macOS.

Dit verschil in runtime kan sommige SqlString vergelijkingen veranderen. SQL Server gebruikt NLS-vergelijkingsgedrag. Als vergelijkingen aan de clientzijde SqlString moeten overeenkomen met het servergedrag, test dan de betreffende waarden en raadpleeg Globalization and ICU. Een applicatie kan NLS gebruiken in plaats van ICU wanneer dat nodig is.

Globalisatie-invariante modus wordt niet ondersteund door Microsoft. Data.SqlClient.

Valideer de gemigratiede applicatie

Bouw en test op elk ondersteund doelframework en besturingssysteem.

Valideren:

• Herstellen van pakketten en gepubliceerde uitvoer.
• SQL-authenticatie, Windows-geïntegreerde authenticatie en Microsoft Entra-authenticatie die door de applicatie worden gebruikt.
• onderhandeling van TLS, certificaatvalidatie en parseren van verbindingsreeksen.
• Verbindingspooling en toegangstokenvernieuwing.
• Parametertypes, nulwaarden, precisie, schaal, datum en tijdsgedrag.
• Transacties, annulering, time-outs, herpogingen en failover.
• Always Encrypted, SQL Server CLR-typen, bulkkopieën, querymeldingen en andere provider-specifieke functies die door de applicatie worden gebruikt.
• Loggen, tellers, tracering en uitzonderingsafhandeling.

Voer representatieve queries uit op elke ondersteunde versie van de database-engine. Een succesvolle compilatie valideert geen connectiebeveiliging, runtime-afhankelijkheden of dataconversies.

Verwante onderwerpen

• Microsoft. Data.SqlClients naamruimte en compatibiliteit
• Releaseopmerkingen en updates voor Microsoft.Data.SqlClient
• Spiekbrief voor portering in de SqlClient-repository
• Microsoft. Data.SqlClient API-referentie