Microsoft. Data.SqlClient-Namensraum und Kompatibilität

Der Namensraum Microsoft.Data.SqlClient enthält den unterstützten .NET-Datenanbieter für SQL Server-kompatible Datenbanken. Es begann als Fork des System.Data.SqlClient vertrauten ADONET-Programmiermodells und behält es bei, während es neue SQL Server-Funktionen unabhängig von der .NET-Laufzeit ausliefert.

Verwenden Sie Microsoft.Data.SqlClient für neue Entwicklungen.

Installieren und importieren Sie den Namensraum

Fügen Sie das NuGet-Paket hinzu:

dotnet add package Microsoft.Data.SqlClient

Importieren Sie den Namespace:

using Microsoft.Data.SqlClient;

Die meisten Anwendungen verwenden SqlConnection, SqlCommand, SqlParameter, , SqlDataReaderund SqlTransaction. Für die vollständige öffentliche Oberfläche siehe die Microsoft. Data.SqlClient API-Referenz.

Beziehung zu ADO.NET

ADO.NET ist das Datenzugriffsmodell, das in .NET integriert ist. Es definiert anbieterunabhängige Abstraktionen im Namensraum System.Data.Common und Microsoft.Data.SqlClient liefert die konkreten Implementierungen.

ADO.NET-Abstraktion SqlClient-Typ Purpose
DbConnection SqlConnection Öffnet eine logische Verbindung zu einer Datenbank.
DbCommand SqlCommand Führt Transact-SQL (T-SQL) Text oder eine gespeicherte Prozedur aus.
DbParameter SqlParameter Sendet einen getippten Wert getrennt vom Befehlstext.
DbDataReader SqlDataReader Überträgt Ergebniszeilen fortlaufend vom Server.
DbTransaction SqlTransaction Gruppiert Befehle zu einer Transaktion, die als Einheit bestätigt oder zurückgesetzt wird.
DbDataAdapter SqlDataAdapter Füllt nicht verbundene DataSet- und DataTable-Objekte auf und aktualisiert sie.
DbBatch SqlBatch Sendet mehrere Befehle als eine Charge auf unterstützte Zielframeworks.

Microsoft. Data.SqlClient stellt außerdem SQL Server-spezifische APIs bereit, wie zum Beispiel:

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • Unterstützung für SQL Server-spezifische Authentifizierung, Verschlüsselung und Datentypen

Programmieren Sie gegen die ADO.NET-Abstraktionen, wenn eine Bibliothek mehrere Datenbankanbieter unterstützen muss. Verwenden Sie die SqlClient-Typen, wenn eine Anwendung auf SQL Server abzielt und anbieterspezifische Funktionen benötigt, wie Microsoft Entra-Authentifizierung, Always Encrypted, Massenkopie, tabellenwertige Parameter oder konfigurierbare Wiederholungslogik. Behalten Sie anbieterspezifischen Code hinter einer Datenzugriffsgrenze, wenn der Rest der Anwendung anbieterunabhängig bleiben muss.

Verbundener und getrennter Zugriff

Connected Access hält eine Verbindung offen, während ein Befehl ausgeführt wird und während die Anwendung ihre Ergebnisse liest. Eine typische Anfrage folgt dieser Sequenz:

  1. Erstelle eine SqlConnection aus einer Verbindungszeichenfolge und öffne sie.
  2. Erstelle ein SqlCommand und füge SqlParameter Werte hinzu.
  3. Führen Sie den Befehl aus.
  4. Verarbeiten Sie einen skalaren Wert, eine betroffene Zeilenzahl oder ein SqlDataReader.
  5. Entsorgen Sie den Leser, den Befehl und die Verbindung.

Nutzen Sie Connected Access für die meisten Web-APIs, Dienste, Arbeiter und Kommandozeilenanwendungen. SqlDataReader streamt Zeilen und verbraucht in der Regel weniger Speicher als das Laden des gesamten Ergebnisses in ein DataSet.

Disconnected-Zugriff wird verwendet SqlDataAdapter , um Daten in einen In-Memory DataSet oder DataTablezu kopieren. Die Anwendung kann die Verbindung schließen, während sie die Daten im Speicher liest oder ändert, und sich dann wieder verbinden, um Updates zu senden. Nutze es für Datenbindungen, In-Memory-Relationen und Einschränkungen, Offline-Bearbeitungen, die du später abgleichst, oder für eine bestehende Anwendung, die um DataAdapters herum gebaut ist. Für neue, anfrageorientierte Dienste beginnen Sie mit SqlCommand und SqlDataReader.

Objektlebensdauer und Nebenläufigkeit

Öffnen und entsorgen Sie für jeden Arbeitsschritt ein SqlConnection. Connection Pooling verwendet die zugrundeliegende physische Verbindung wieder, daher sollten Sie keine globale Verbindung während der gesamten Lebensdauer einer Anwendung offen halten. Geben Sie Verbindungen, Befehlsobjekte, Reader, Transaktionen und BulkCopy-Objekte umgehend frei. Verwenden Sie im asynchronen Code await using für Typen, die im Zielframework IAsyncDisposable implementieren, wie SqlConnection und SqlDataReader auf .NET, und gewöhnlich using für Typen, die nur IDisposable implementieren, wie z. B. SqlBulkCopy.

SqlConnection, SqlCommand, , SqlDataReaderund SqlTransaction unterstützen keine gleichzeitige Nutzung durch mehrere Threads. Geben Sie jeder gleichzeitigen Operation eine eigene Verbindung und verlassen Sie sich auf Verbindungspooling. Multiple Active Result Sets (MARS) erlaubt mehr als ein aktives Ergebnisset auf einer Verbindung, macht SqlClient-Objekte jedoch nicht threadsicher.

Beziehung zu System.Data.SqlClient

System.Data.SqlClientist der ältere Anbieter, der mit .NET Framework und früheren .NET-Versionen ausgeliefert wird. Microsoft.Data.SqlClient verwendet viele der gleichen Typnamen, hat jedoch unterschiedliche Pakete, Namensräume, Standardwerte, Funktionen und Support-Richtlinien.

Beziehen Sie sich im neuen Anwendungscode nicht auf beide Anbieter. Typen mit demselben Namen aus den beiden Paketen sind nicht austauschbar. Ein System.Data.SqlClient.SqlConnection kann beispielsweise nicht dort übergeben werden, wo ein Microsoft.Data.SqlClient.SqlConnection erforderlich ist.

Die Migration beginnt üblicherweise mit dem Hinzufügen des Pakets Microsoft.Data.SqlClient und dem Ändern der Namensraumreferenzen, aber Sie müssen auch die Verschlüsselung der Verbindung, Parameter, Konfiguration, transitive Abhängigkeiten und das Laufzeitverhalten überprüfen. Befolgen Sie die Migration von System.Data.SqlClient zu Microsoft.Data.SqlClient, bevor Sie bereitstellen.

Versionskompatibilität

Die Version des Treiberpakets ist unabhängig von der .NET-Version der Anwendung und der Datenbank-Engine-Version. Überprüfen Sie alle drei:

Component Was zu überprüfen ist
Microsoft.Data.SqlClient Die Release-Linie wird unterstützt und enthält die Funktionen, die Ihre Anwendung verwendet.
.NET- oder .NET-Framework Die Anwendung zielt auf eine Laufzeitumgebung ab, die von diesem Treiber-Release unterstützt wird.
SQL Server-kompatible Datenbank Die Treiberversion unterstützt die Datenbankversion, und der Server unterstützt jede gewünschte Protokollfunktion, wie z. B. TDS 8.0.

Für aktuelle Matrizen siehe SqlClient-Treiber-Support-Lebenszyklus.

Versionsspezifische Änderungen

Treiber-Releases können APIs hinzufügen, optionale Abhängigkeiten verschieben und sichere Standardeinstellungen ändern. Überprüfe Änderungen vor jedem kleinen oder größeren Update.

Dazu gehören:

  • Version 4.0 änderte Encrypt so, dass standardmäßig true verwendet wird.
  • Version 5.0 führte SqlConnectionEncryptOption und Encrypt=Strict für TDS 8.0 ein.
  • Mit Version 5.2 wurde SqlBatch für unterstützte moderne .NET-Zielplattformen eingeführt.
  • Version 7.0 verschob die treibergesteuerte Microsoft Entra-Authentifizierung in Microsoft.Data.SqlClient.Extensions.Azure.

Unter Neuerungen in Microsoft.Data.SqlClient finden Sie Links zu den Versionshinweisen und eine Upgradezusammenfassung.

Einige Funktionen verwenden Typen außerhalb des Hauptnamensraums oder optionale Pakete.

Namensraum oder Paket Purpose
Microsoft.Data.SqlClient.Server SQL-Client-Implementierungen von SqlDataRecord und SqlMetaData.
Microsoft.Data.SqlTypes SQLClient-spezifische Typen wie SqlFileStream, SqlJson, und SqlVector<T>.
Microsoft.Data.SqlClient.Diagnostics Stark typisierte diagnostische Ereignisnutzlasten.
Microsoft.Data.SqlClient.Extensions.Azure Treibergesteuerte Microsoft Entra-Authentifizierung für Version 7.0 und neuer.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Integration von Azure Key Vault für Always Encrypted.

Leiten Sie Paketanforderungen nicht allein anhand eines Namensraums ab. Folgen Sie dem Feature-Artikel und den Informationen zur NuGet-Paketabhängigkeit für die von Ihnen verwendete Treiberversion.

Verwandte Inhalte

  • Zuletzt aktualisiert um