Microsoft.Data.SqlClient installieren, aktualisieren und bereitstellen

Microsoft. Data.SqlClient ist der unterstützte .NET-Datenanbieter für SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance, Azure Synapse Analytics, SQL Database in Microsoft Fabric und Warehouse in Microsoft Fabric. Der Treiber wird als NuGet-Pakete unabhängig von der .NET-Laufzeit ausgeliefert.

Auswählen einer Version

Verwenden Sie eine unterstützte General Availability (GA)-Version für Produktionsanwendungen. Die neueste GA-Version ist Microsoft.Data.SqlClient 7.1.0.

Releasezeile Neueste Version Supportstufe Wählen Sie diese Option, wenn
7.1 7.1.0 Standard-Laufzeitunterstützung (STS) Du brauchst die aktuellen Treiberfunktionen und kannst im regulären Release-Rhythmus aktualisieren.
7.0 7.0.3 Standard-Laufzeitunterstützung (STS) Sie benötigen Wartungskorrekturen, während Sie sich auf ein Upgrade vorbereiten, bevor der Support am 17. Dezember 2026 endet.
6.1 6.1.7 Langfristiger Support (Long Term Support, LTS) Du bevorzugst eine längere Supportzeit und brauchst keine Funktionen, die in 7.x eingeführt wurden.

Für aktuelle Patch-Versionen, Supportdaten, Zielframeworks und Datenbankkompatibilität siehe Lebenszyklus der SqlClient-Treiberunterstützung.

Installiere das Kernpaket

Führe folgenden Befehl aus dem Verzeichnis aus, das deine Projektdatei enthält:

dotnet add package Microsoft.Data.SqlClient

Der Befehl wählt die neueste stabile Version, die mit dem Projekt kompatibel ist. Um eine Version für wiederholbare Builds zu pinnen, spezifizieren Sie die Version:

dotnet add package Microsoft.Data.SqlClient --version <version>

Abhängigkeiten wiederherstellen und das Projekt erstellen:

dotnet restore
dotnet build

Importiere den Treibernamensraum in C#:

using Microsoft.Data.SqlClient;

Für neue Anwendungen solltest du nicht auf das ältere System.Data.SqlClientPaket oder den Namensraum verweisen. Wenn Sie eine vorhandene Anwendung aktualisieren, lesen Sie Migrieren von System.Data.SqlClient zu Microsoft.Data.SqlClient.

Installieren mit Visual Studio

  1. Im Projektmappen-Explorer klicken Sie mit der rechten Maustaste auf das Projekt und wählen NuGet-Pakete verwalten aus.
  2. Im Reiter Durchsuchen , suchen Sie nach Microsoft.Data.SqlClient.
  3. Wählen Sie das Paket aus, das Microsoft gehört.
  4. Wählen Sie eine unterstützte stabile Version aus, und wählen Sie dann Installieren.

Weitere Informationen finden Sie unter Pakete in Visual Studio installieren und verwalten.

Optionale Pakete hinzufügen

Installiere optionale Pakete nur, wenn deine Anwendung die zugehörige Funktion nutzt.

Package Füge es hinzu, wenn
Microsoft.Data.SqlClient.Extensions.Azure Microsoft.Data.SqlClient 7.0 oder später verwendet einen vom Treiber bereitgestellten Microsoft Entra-Authentifizierungsmodus, wie Active Directory Default, Active Directory Interactive oder Active Directory Managed Identity.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Always Encrypted speichert Spalten-Masterschlüssel in Azure Key Vault.

Für die Microsoft Entra-Authentifizierung mit SqlClient 7.0 oder neuer, führen Sie Folgendes aus:

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

Das 7.0-Kernpaket enthält keine Azure Identity-Abhängigkeiten mehr. Ab Version 7.0.2 verwenden der Kerntreiber und die Begleitpakete abgestimmte Versionen. Beziehen Sie sich auf dieselbe Version von Microsoft.Data.SqlClient und Microsoft.Data.SqlClient.Extensions.Azure. Anwendungen, die keine treibergesteuerte Microsoft Entra-Authentifizierung verwenden, benötigen das Azure-Erweiterungspaket nicht. Informationen zur Einrichtung der Authentifizierung finden Sie unter Microsoft Entra-Authentifizierung.

Treiber aktualisieren

Bevor Sie aktualisieren:

  1. Lesen Sie Neuerungen in Microsoft.Data.SqlClient und die nachgelagerten Versionshinweise für jede Version, die von der Aktualisierung betroffen ist.

  2. Überprüfen Sie die direkten und transitiven Paketreferenzen der Anwendung.

    dotnet list package --include-transitive

  3. Aktualisieren Sie die Paketreferenz.

    dotnet add package Microsoft.Data.SqlClient --version <version>

  4. Wiederherstellen, bauen und die Tests der Anwendung ausführen.

  5. Testen Sie Verbindungsaufbau, Authentifizierung, Zertifikatsvalidierung, Verbindungspooling, Datentypkonvertierungen, Transaktionen und das Wiederholungsverhalten bei jedem unterstützten Datenbankziel.

Major- und Patch-Releases können Änderungen an Anwendungen erfordern. Beispiele: Bei Version 4.0 wurde standardmäßig die Verschlüsselung aktiviert, Version 5.0 änderte SqlConnectionStringBuilder.Encrypt von bool in SqlConnectionEncryptOption, und bei Version 7.0 wurde die treibergesteuerte Microsoft Entra-Authentifizierung in ein separates Paket verschoben.

Ab Version 7.0.2 wurden die Assemblyversionen von Microsoft.Data.SqlClient.Extensions.Azure, Microsoft.Data.SqlClient.Extensions.Abstractions und Microsoft.Data.SqlClient.Internal.Logging von 1.0.0.0 in 7.0.0.0 geändert. .NET Framework-Anwendungen müssen für die abgestimmten Pakete neu erstellt werden oder Bindungsumleitungen hinzufügen. Anwendungen auf aktuellem .NET sind von dieser Änderung der Assembly-Identität nicht betroffen.

Grundlegendes zu Zielframeworks

Microsoft. Data.SqlClient 7.1 unterstützt Anwendungen auf:

  • .NET Framework 4.6.2 oder später unter Windows.
  • .NET 8 oder neuer auf unterstützten Windows-, Linux- und macOS-Versionen.

Das NuGet-Paket enthält außerdem ein .NET Standard 2.0 Kompatibilitätsasset für Bibliotheken. Eine ausführbare Anwendung muss eine unterstützte .NET- oder .NET-Framework-Laufzeit als Ziel haben. Das .NET Standard-Ziel einer Bibliothek bedeutet nicht, dass jede nutzende Laufzeit unterstützt wird.

Das Paket stellt seine verwalteten und nativen Abhängigkeiten über NuGet wieder her. Kopiere keine einzelnen Treiberassemblys oder native SQL Network Interface (SNI)-Bibliotheken zwischen Anwendungen.

Vorbereiten der Bereitstellung

  1. Veröffentlichen Sie für dasselbe Betriebssystem und dieselbe Architektur, die in der Produktion verwendet wird. Für eine framework-abhängige Bereitstellung:

    dotnet publish --configuration Release

    Für eine laufzeitspezifische Bereitstellung:

    dotnet publish --configuration Release --runtime <runtime-identifier>

  2. Stellen Sie die vollständige Publish-Ausgabe bereit. Wählen Sie nicht nur Microsoft.Data.SqlClient.dll.

  3. Stellen Sie sicher, dass das Ziel über die erforderliche .NET-Laufzeit verfügt, es sei denn, Sie veröffentlichen eine eigenständige Anwendung.

  4. Testen Sie die veröffentlichte Ausgabe auf dem Zielbetriebssystem und der Zielarchitektur.

  5. Teste jeden in der Produktion verwendeten Authentifizierungsmodus. Integrierte Authentifizierung, Kerberos, Zertifikate, verwaltete Identität und Azure Key Vault-Zugriff hängen von der Bereitstellungsumgebung ab.

  6. Scannen Sie den aufgelösten Abhängigkeitsgraphen nach bekannten Schwachstellen, und aktualisieren Sie unterstützte Paketversionen, sobald Korrekturen verfügbar sind.

Der globalisierungsinvariante Modus wird nicht unterstützt. Für aktuelle Plattformqualifikationen siehe Unterstützte Betriebssysteme.

Offline-Paketinstallation

Laden Sie das Paket und seine Abhängigkeiten von NuGet.org herunter, kopieren Sie sie in eine interne Paketquelle, und stellen Sie sie aus dieser Quelle wieder her. Für wiederholbare Offline-Builds werden Paketversionen gepinnt und die vollständige Abhängigkeitsmenge erhalten.

Verwandte Inhalte

  • Zuletzt aktualisiert um