Migration von System.Data.SqlClient zu Microsoft. Data.SqlClient

Microsoft. Data.SqlClient ist der unterstützte Anbieter neuer SQL Server-Funktionen in .NET-Anwendungen. Es behält das von ADO.NET verwendete System.Data.SqlClientProgrammiermodell bei, aber die Pakete, Namensräume, Standardwerte und einige öffentliche Typen unterscheiden sich.

Behandle die Migration als Provider-Update, nicht nur als Namespace-Ersatz.

Planung der Migration

Bevor der Code geändert wird:

1. Zeichnen Sie die Versionen von .NET, System.Data.SqlClient, SQL Server und Microsoft SQL-Diensten auf, die die Anwendung unterstützt.

2. Inventar-Authentifizierungsmodi, Verbindungszeichenfolge-Schlüsselworte, benutzerdefinierte Zertifikate, Always Encrypted Providers, DbProviderFactories Konfiguration, SQL Server benutzerdefinierte Typen und System.Data.SqlTypes Nutzung.

3. Führen Sie die aktuellen Tests der Anwendung aus und speichern Sie eine Basislinie für Verbindung, Abfrage, Transaktion, Wiederholung und Leistungsverhalten.

4. Suche nach direkten und transitiven Paketreferenzen:

   dotnet list package --include-transitive
   

Migriere jeweils eine Anwendung oder eine gemeinsame Datenzugriffsbibliothek. Geben Sie keine providerspezifischen Objekte zwischen Code weiter, der noch verwendet System.Data.SqlClient , und Code, der verwendet Microsoft.Data.SqlClient.

Ersetze das Paket

Entfernen Sie eine explizite System.Data.SqlClient Paketreferenz, falls vorhanden:

dotnet remove package System.Data.SqlClient

Fügen Sie Microsoft hinzu. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Wenn Microsoft. Data.SqlClient 7.0 oder später einen vom Treiber bereitgestellten Microsoft Entra-Authentifizierungsmodus verwendet, fügen Sie außerdem hinzu:

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

Für Versions- und Paketauswahl siehe Installieren, aktualisieren und bereitstellen Microsoft aus. Data.SqlClient.

Namespaces aktualisieren

Ersetzen Sie den Namensraum des primären Anbieters:

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

Aktualisieren Sie vollständig qualifizierte Namen, Aliase, generierten Code, Abhängigkeitsinjektionsregistrierungen, Reflexionszeichenketten, Konfigurationen und Test-Doubles, die sich auf System.Data.SqlClientbeziehen.

Ersetze nicht die allgemeinen System.Data oder System.Data.Common Namensräume. Microsoft.Data.SqlClientverwendet weiterhin ADO.NET-Typen wie CommandType, DbType, , IsolationLevelDataTable, , DbConnectionund DbCommand aus diesen Namensräumen.

Einige SQL Server-spezifische Typen wechseln in andere Microsoft.Data Namensräume:

In Microsoft.Data.SqlClient Version 5.0 und später bleiben weitere SQL Server Common Language Runtime (CLR)-Typen weiterhin in Microsoft.SqlServer.Server. Aktualisieren Sie jeden Typ von Compilerfehlern und dem Microsoft. Data.SqlClient API-Referenz, anstatt den gesamten Namensraum zu ersetzen.

Aktualisierung der .NET Framework-Konfiguration

Eine Anwendung, die Anbieter über DbProviderFactories Anbieter, benötigt möglicherweise eine Anbieterregistrierung in App.config oder 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>

Update-Code, der den Anbieter invarianten Namen anfordert:

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

Füge diese Konfiguration nicht hinzu, wenn die Anwendung direkt erstellt SqlConnection und nicht .DbProviderFactories

Überprüfung der Verschlüsselung und Zertifikatsvalidierung

Microsoft. Data.SqlClient verwendet sicherere Standardeinstellungen als System.Data.SqlClient.

Setze Encrypt=false es nicht als TrustServerCertificate=true allgemeine Migrationslösung. Konfigurieren Sie ein Zertifikat, dem der Client vertraut, und verwenden Sie einen Servernamen, der dem Zertifikat entspricht. Verwenden TrustServerCertificate=true Sie nur kontrollierte Entwicklungsumgebungen, in denen eine Validierung nicht möglich ist.

Die Änderung ist SqlConnectionEncryptOption in gängigen Zuweisungen durch implizite Umwandlungen quellenkompatibel, aber es handelt sich um eine binäre Bruchänderung. Kompiliere jede Assembly, die auf zugreift SqlConnectionStringBuilder.Encrypt, neu.

Ausführliche Informationen finden Sie unter Verschlüsselung und Zertifikatüberprüfung.

Überprüfe Verbindungsstrings

Microsoft. Data.SqlClient fügt Schlüsselwörter und Aliase hinzu, die System.Data.SqlClient nicht erkennt. Zum Beispiel akzeptiert es Aliase mit Leerzeichen wie Application Intent und Multi Subnet Failover.

Baue keinen Verbindungszeichenfolge mit Microsoft.Data.SqlClient.SqlConnectionStringBuilder und übergebe ihn dann an System.Data.SqlClient. Während einer gestuften Migration sollte jeder Verbindungszeichenfolge Builder mit seinem Anbieter gepaart bleiben.

Überprüfen Sie Authentifizierung, Verschlüsselung, Wiederholung, Failover und Zertifikatsschlüsselwörter anhand der Syntax der Verbindungsstrings.

Das Verhalten der Parameter überprüfen

Testdatum und -zeitparameter explizit:

Spezifizieren Sie , Länge, Präzision und Skalierung SqlDbTypefür Parameter, bei denen die SQL Server-Typinferenz Abfragepläne oder Umwandlungsverhalten verändern kann. Verwenden AddWithValue Sie nicht als Migrationsabkürzung, wenn der Datenbanktyp bekannt ist.

Überprüfen Sie transitive Provider-Referenzen

Eine direkte Paketentfernung garantiert nicht, dass das System.Data.SqlClient verschwunden ist. Laufen:

dotnet list package --include-transitive

Wenn beide Anbieter bestehen:

1. Identifizieren Sie das Paket, das .System.Data.SqlClient
2. Aktualisieren oder ersetzen Sie diese Abhängigkeit, wenn möglich.
3. Halte anbieterspezifische Typen innerhalb der Abhängigkeitsgrenze, wenn beide bleiben müssen.
4. Verwenden Sie explizite Namensraum-Aliase nur als temporäre Hilfe. Leite keine Verbindung, Transaktion, Parameter oder Leser von einem Anbieter zum anderen weiter.

Achten Sie besonders auf SQL Server CLR-Typbibliotheken und ältere Datenzugriffsframeworks, die Typen in ihren öffentlichen APIs bereitstellenSystem.Data.SqlClient.

Überprüfen Sie das Globalisierungsverhalten

.NET Framework- und .NET-Versionen vor .NET 5 verwenden National Language Support (NLS) Globalisierung unter Windows. Aktuelle .NET-Versionen verwenden standardmäßig International Components for Unicode (ICU) auf Windows, Linux und macOS.

Dieser Laufzeitunterschied kann einige SqlString Vergleiche verändern. SQL Server verwendet NLS-Vergleichsverhalten. Wenn clientseitige SqlString Vergleiche das Serververhalten übereinstimmen müssen, testen Sie betroffene Werte und überprüfen Sie Globalisierung und ICU. Eine Anwendung kann bei Bedarf NLS anstelle von ICU verwenden .

Der Globalisierungsinvariantenmodus wird von Microsoft nicht unterstützt. Data.SqlClient.

Validiere die migrierte Anwendung

Baue und teste auf jedem unterstützten Ziel-Framework und Betriebssystem.

Überprüfen:

• Paketwiederherstellung und veröffentlichte Ausgabe.
• SQL-Authentifizierung, integrierte Windows-Authentifizierung und Microsoft Entra-Authentifizierung, die von der Anwendung verwendet werden.
• TLS-Verhandlung, Zertifikatsvalidierung und Verbindungszeichenfolge-Parsing.
• Verbindungspooling und Aktualisierung des Zugriffstokens.
• Parametertypen, Nullwerte, Genauigkeit, Skalierung, Datum und Zeitverhalten.
• Transaktionen, Stornierung, Auszeiten, Neuversuche und Failover.
• Always Encrypted, SQL Server CLR-Typen, Massenkopien, Abfragebenachrichtigungen und andere anbieterspezifische Funktionen, die von der Anwendung verwendet werden.
• Protokollierung, Zähler, Verfolgung und Exception Handling.

Führe repräsentative Abfragen gegen jede unterstützte Version der Datenbank-Engine aus. Eine erfolgreiche Kompilierung validiert weder die Verbindungssicherheit, Laufzeitabhängigkeiten noch Datenkonvertierungen.

Verwandte Inhalte

• Microsoft. Data.SqlClient-Namensraum und Kompatibilität
• Microsoft. Data.SqlClient Release Notes und Updates
• Portierungs-Spickzettel im SqlClient-Repository
• Microsoft. Data.SqlClient API-Referenz