Microsoft. Data.SqlClient für SQL Server

Herunterladen von ADO.NET

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. Es wird als NuGet-Paket verteilt, entwickelt sich unabhängig von der .NET-Laufzeit weiter und ersetzt System.Data.SqlClient für neue Entwicklungen. Es stellt Verbindungen, Befehle, Ergebnisverarbeitung, Transaktionen, Massenkopien und SQL Server-spezifische Funktionen für .NET-Anwendungen bereit.

Auswählen des Startpunkts

Produktionsbasisplan für Azure SQL

Nutzen Sie diesen Ausschnitt als Ausgangspunkt für einen produktionsorientierten Azure SQL-Datenzugriffspfad. Er liest die Server- und Datenbanknamen aus IConfiguration, sodass die Werte von den Konfigurationsanbietern stammen, die der Host verbindet, wie z. B. appsettings.json, Umgebungsvariablen, Azure App Configuration und von Key Vault unterstützte Einstellungen. Die Konfiguration vereint folgende Merkmale:

  • Transport Layer Security (TLS).
  • Verwaltete Identität.
  • Resilienz von Verbindungen im Leerlauf.
  • Initial-Connect-Retry über konfigurierbare Retry-Logik (CRL) mit strukturiertem Logging.
  • Wiederholungsversuch auf Befehlsebene bei vorübergehenden Fehlern, die mitten in der Abfrage auftreten.
  • Schnelle Wiederherstellung von Failover-Gruppen.
  • Asynchrone Aufrufe, die ein Abbruchtoken akzeptieren.

Für höhere Sicherheit und zur Unterstützung der Konfiguration über verschiedene Umgebungen hinweg sollten Sie die Verbindungsinformationen außerhalb Ihres Codes behalten. In der Produktion speichern Sie Verbindungsinformationen im Konfigurationssystem Ihrer Anwendung und verwenden Sie Azure Key Vault für sensible Werte. Weitere Informationen finden Sie unter Schützen von Verbindungsinformationen.

Der C#-Ausschnitt in diesem Artikel lässt using aus Gründen der Kürze Direktiven und Klassenwrapper weg.

Der Snippet nimmt ein Projekt an, das .NET 8 oder neuere Versionen anspricht und verweist auf die Microsoft.Data.SqlClient und Microsoft.Data.SqlClient.Extensions.Azure 7.1.1-Pakete. Der Host, wie der .NET Generic Host oder ASP.NET Core, stellt die ILogger und die IConfiguration bereit, und die Konfiguration stellt den Servernamen in Sql:Server und den Datenbanknamen in Sql:Database bereit.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

Die Methode liefert den Namen der Datenbank, mit der sie eine Verbindung hergestellt hat, zurück und protokolliert Connected to database <database>. Wenn ein Wiederholversuch erfolgt, wird pro Wiederholversuch auch eine Warnung mit der Ausnahme protokolliert, die sie ausgelöst hat.

Wie jeder Teil des Ausschnitts funktioniert:

  • Ziele: Alle SQL Datenbank-Engine-Endpunkte, die für Microsoft Entra-Authentifizierung konfiguriert sind: Azure SQL-Datenbank, Azure SQL Managed Instance, SQL-Datenbank in Microsoft Fabric und SQL Server 2022 und spätere Versionen auf Azure Virtual Machines oder aktiviert durch Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Wählt TDS 8.0-Verschlüsselung. Sie benötigt SQL Server 2022 und spätere Versionen, Azure SQL-Datenbank, Azure SQL Managed Instance oder SQL Database in Microsoft Fabric. Verwenden Sie SqlConnectionEncryptOption.Mandatory für ältere Server.
  • ActiveDirectoryManagedIdentity: Funktioniert nur, wenn eine verwaltete Identität verfügbar ist, wie z. B. Azure App Service, Azure Functions oder eine virtuelle Azure-Maschine. Verwenden Sie für die lokale Entwicklung SqlAuthenticationMethod.ActiveDirectoryDefault, das die Azure CLI, die Anmeldung mit Visual Studio und andere Quellen für Anmeldeinformationen ausprobiert. Nicht in der Produktionsumgebung verwenden, weil das Untersuchen jeder Quelle die Verbindung verlangsamt. Für weitere Informationen siehe Standardauthentifizierung verwenden.
  • MultiSubnetFailover = true: Versucht TCP-Verbindungen parallel zu allen aufgelösten IP-Adressen und nutzt die erste erfolgreiche Verbindung, wodurch der langsame sequentielle pro-IP-Walk vermieden wird. Setze es für Azure SQL-Datenbank, Azure SQL Managed Instance, SQL-Datenbank in Microsoft Fabric, Availability Group Listener und Failover-Cluster-Instanzen ein. Es ist sicher bei Zielen mit nur einer IP. Es wird nicht für benannte Instanzen, Protokolle außer TCP, Instanzen mit mehr als 64 IP-Adressen oder Datenbankspiegelung unterstützt, die veraltet ist. Verwenden Sie stattdessen Always On-Verfügbarkeitsgruppen. Weitere Informationen finden Sie unter Hohe Verfügbarkeit und Katastrophenwiederherstellung sowie Deaktivierung transparenter Netzwerk-IP-Auflösung.
  • ConnectRetryCount = 3 und ConnectRetryInterval = 10: Der Treiber versucht während Open(), als vorübergehend eingestufte Fehler erneut auszuführen und verbindet eine unterbrochene Leerlaufverbindung beim nächsten Befehl wieder. Die Standardanzahl ist 1. Drei Versuche im Abstand von jeweils 10 Sekunden sind langwieriger als eine längere Neukonfiguration oder ein Failover. Der Treiber ändert 1 nur dann in 2, wenn der Servername in einer bekannten Azure SQL-Domäne endet, wie zum Beispiel .database.windows.net, sodass ein benutzerdefinierter DNS-Alias 1 erhält.
  • openRetry: Zugewiesen an SqlConnection.RetryLogicProvider, fügt es um Open() einen exponentiellen Backoff hinzu. Der Treiber beendet seine internen Wiederholungen, wenn ConnectTimeout abläuft, sodass der schlimmste Fall, bevor OpenAsync eine Ausnahme auslöst, fünf Versuche von jeweils bis zu 30 Sekunden plus Backoff sind. Jeder Leerlauf-Wiederverbindungsversuch führt außerdem die vollständige openRetry Richtlinie aus, und wenn diese Richtlinie ihre Wiederholungsversuche erschöpft hat, endet die Leerlauf-Wiederherstellung.
  • Serverlose automatische Pause: Für Azure SQL-Datenbank serverless erhöhen Sie ConnectTimeout auf mindestens 60 Sekunden. Das erste Open() kann mit einem 40613-Fehler fehlschlagen, während die Datenbank den Betrieb wieder aufnimmt, und openRetry versucht es erneut. Ein clientseitiger Timeout erscheint als -2-Fehler, bei dem kein erneuter Versuch erfolgt, sodass jeder Verbindungsversuch länger dauern muss als die Fortsetzung. Weitere Informationen finden Sie unter Auto-pause und Auto-resume.
  • commandRetry: Hängen Sie es nur dann an SqlCommand.RetryLogicProvider an, wenn das Wiederholen des Befehls sicher ist: Lesevorgänge, MERGE durch einen natürlichen Schlüssel abgesichert, Upserts durch eine gespeicherte Prozedur und andere idempotente Operationen. Er überspringt einen erneuten Versuch innerhalb einer Transaktion, daher muss der Anwendungscode Transaktionen mit mehreren Anweisungen erneut versuchen. ExecuteReader und ExecuteScalar versuchen nur Fehler erneut, die zurückgegeben werden, bevor der erste Ergebnissatz startet. ExecuteNonQuery wiederholt den gesamten Aufruf.
  • Vorübergehende Fehlerliste: Die Einstellung TransientErrors ersetzt die eingebaute Liste. Um es stattdessen zu erweitern, verwenden Sie SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 und später).
  • Retrying Ereignis: Retrying Wird vor jedem erneuten Versuch mit der Anzahl der Wiederholungen, der nächsten Verzögerung und den bisherigen Ausnahmen gezündet. Leiten Sie es an ILogger oder an Ihre Telemetrie-Pipeline weiter.
  • Ausnahmen: Die Methode fängt keine Ausnahmen ab. Ein ausgeschöpfter Anbieter löst eine AggregateException mit der Ausnahme aus jedem Versuch aus. Ein nicht vorübergehender Fehler wird als ursprüngliche Ausnahme weitergegeben. Der Anrufer protokolliert sie einmal zusammen mit dem restlichen Anforderungskontext.
  • Abbruch: Das CancellationToken beendet die Wartezeit des Anbieters zwischen den Wiederholversuchen. Sie unterbricht das ConnectRetryInterval Warten des Fahrers nicht bei einem einzigen Open Versuch. Weitere Informationen finden Sie unter Asynchrone Programmierung.
  • Lebensdauer des Providers: Der Codeausschnitt erstellt die Retry-Provider bei jedem Aufruf, um eigenständig zu bleiben. In einer Anwendung erstellen Sie sie einmal und verwenden Sie sie wieder.

Weitere Informationen zu den einzelnen Teilen dieser Konfiguration finden Sie unter:

Lerne die Kernaufgaben des Datenzugriffs kennen

Nachdem Sie sich verbunden haben, verwenden Sie diese Artikel der Reihe nach:

  1. Führe einen Befehl aus, um eine Ergebnisform auszuwählen, und führe Transact-SQL (T-SQL) aus.
  2. Konfigurieren Sie Parameter so, dass sie zum Datenbankvertrag passen.
  3. Rufen Sie Daten mit SqlDataReader ab, um Zeilen und mehrere Ergebnisse zu verarbeiten.
  4. Ändern Sie Daten mit gespeicherten Prozeduren , um Ausgabeparameter und Rückgabewerte zu verwenden.
  5. Verwenden Sie asynchrone Programmierung und Abbruch, um Anruferabbruch und zeitlich begrenzte Timeouts hinzuzufügen.
  6. Behandeln Sie Fehler und Nachrichten, bevor Sie Wiederholversuche oder Diagnosen für die Produktionsumgebung hinzufügen.

Wichtigste Funktionen

  • Moderne .NET-Unterstützung: Läuft auf aktuellen .NET- und .NET-Framework-Versionen. Für die Aufschlüsselung pro Version siehe Support-Lebenszyklus.
  • Standardverschlüsselt: TLS-verschlüsselte Verbindungen mit Encrypt=true als Standard. Legen Sie Encrypt=Strict für die TDS 8.0-Verschlüsselung fest.
  • Microsoft Entra ID-Authentifizierung: kennwortlose Verbindungen mit verwalteter Identität, Dienstprinzipal, interaktiven, integrierten Standard-Anmeldeinformationsketten und Zugriffstoken-Flows.
  • Kerberos und NTLM: Integrierte Windows-Authentifizierung für lokales Active Directory und Legacy-Szenarien.
  • Always Encrypted: clientseitige Verschlüsselung für vertrauliche Spalten mit optionalen sicheren Enklaven für Vorgänge direkt an Ort und Stelle.
  • Massenkopieren: Einfügungen mit hohem Durchsatz mit SqlBulkCopy.
  • Verbindungspooling: Standardmäßig aktiviert. Ein opt-in-V2-Pool befindet sich in Evaluation.
  • Verbindungsresilienz: Integrierte Wiederholungsversuche bei Verbindungen (ConnectRetryCount und ConnectRetryInterval) sowie optional konfigurierbare Wiederholungslogik für Verbindungen und Befehle.
  • Reiche SQL Server-Datentypen: datetimeoffset, sql_variant, JSON, Vektor-, räumlich-, XML- und tabellenwertige Parameter.
  • Diagnosen: Ereignisquellen-Verfolgung, Diagnosezähler, Anbieterstatistiken und ein spezieller Fehlerbehebungsleitfaden.
  • Anwendungsidentität: Legen Sie SqlConnection.RegisteredApplication fest, um Ihre Bibliothek oder Ihr Tool gegenüber SQL Server zu identifizieren (Microsoft.Data.SqlClient 7.1 und höher).

Get started

Artikel Description
Fang mit dem SqlClient-Treiber an Richte ein Projekt ein, erstelle eine Datenbank, verbinde dich, frage ab und füge Verbindungsresilienz hinzu.
Microsoft.Data.SqlClient installieren, aktualisieren und bereitstellen Installiere NuGet-Pakete, wähle eine Version, aktualisiere den Treiber und bereite die Bereitstellungsausgabe vor.
Supportlebenszyklus Überprüfen Sie unterstützte Treiberversionen und Supportdaten.
Migration von System.Data.SqlClient zu Microsoft. Data.SqlClient Aktualisieren Sie Paketreferenzen, Namensräume, Konfiguration und geändertes Treiberverhalten.
Microsoft. Data.SqlClient-Namensraum und Kompatibilität Verstehen Sie, wie SqlClient ADO.NET implementiert und seine Kompatibilität mit System.Data.SqlClient, .NET und SQL Server.
Was gibt es Neues bei Microsoft? Data.SqlClient Finden Sie aktuelle Veröffentlichungen, größere Upgrade-Änderungen und Upstream-Release-Notes.

Konfigurieren und Verbinden

Artikel Description
Mit einer Datenquelle verbinden Öffnen und verwalten Sie Verbindungen und reagieren Sie auf Änderungen des Verbindungszustands.
Verbindungszeichenfolgen Konfigurieren Sie Server-, Datenbank-, Authentifizierungs-, Verschlüsselungs- und Verbindungsverhalten.
Verschlüsselung und Zertifikatüberprüfung Konfigurieren Sie verschlüsselte Verbindungen und Serverzertifikatsvalidierung.
SQL Server-Verbindungspooling Verwenden Sie physische Verbindungen effizient wieder.
Fehler und Nachrichten behandeln Erkennen Sie Fehler und erhalten Sie Informationsnachrichten.

Authentifizieren und sichern

Artikel Description
Best Practices für die Sicherheit von Microsoft.Data.SqlClient Überprüfen Sie die Richtlinien zur Authentifizierung, Autorisierung und Anwendungssicherheit.
Microsoft Entra-Authentifizierung Verbinden Sie sich mit verwalteter Identität, Service Principal, Passwort und interaktiven Flows.
Verbindungsinformationen schützen Halten Sie Zugangsdaten und Verbindungseinstellungen aus dem Anwendungscode heraus.
Immer verschlüsselt Schütze sensible Spaltenwerte vor dem Datenbanksystem.
Immer verschlüsselt mit sicheren Enklaven Führen Sie reichhaltige Operationen auf verschlüsselten Daten mit einer sicheren Enklave aus.

Daten abrufen und aktualisieren

Artikel Description
Führe einen Befehl aus Führe parametrisierte SQL-Anweisungen und gespeicherte Prozeduren aus.
"DataAdapters" und "DataReaders" Ergebnismengen streamen oder getrennte Datenstrukturen füllen.
Führe mehrere Befehle mit SqlBatch aus Senden Sie eine geordnete Sammlung von Befehlen und verarbeiten Sie deren Ergebnisse.
Stream-Daten Übertragen Sie große Binär-, Text-, XML- und JSON-Werte, ohne den vollständigen Wert zu puffern.
Transaktionen und Parallelität Nutze lokale und verteilte Transaktionen sowie Nebenläufigkeitskontrollen.
Datenbankschema-Informationen abrufen Entdecken Sie Schema-Sammlungen und Einschränkungen.
Massenkopieroperationen Laden Sie große Datensätze effizient mit SqlBulkCopy.
Tabellenwertparameter Senden Sie mehrere Zeilen an eine parametrisierte Anweisung oder gespeicherte Prozedur.
Mehrere aktive Ergebnismengen (MARS) Mehrere Stapel über eine Verbindung verschachteln.

Datentypen

Artikel Description
SQL Server-Datentypabbildungen Ordnen Sie SQL Server-Typen .NET- und System.Data.SqlTypes-Typen zu.
JSON-Daten Senden und rufen Sie den SQL Server json-Datentyp ab.
Vektordaten Senden und holen Sie Vektorwerte ab.
XML-Daten Lesen, schreiben und parametrisieren Sie XML-Werte.
Binär- und Großwertdaten Streamen und aktualisieren Sie Binär-, FILESTREAM- und Großwertdaten.

Zuverlässigkeit und Diagnostik

Artikel Description
Konfigurierbare Wiederholungslogik Wiederholen Sie vorübergehende Verbindungs- und Befehlsfehler mit begrenzten Richtlinien.
Hohe Verfügbarkeit und Notfallwiederherstellung Stellen Sie eine Verbindung mit Verfügbarkeitsgruppen-Listenern und Failoverpartnern her.
Ereignisindikatoren in SqlClient Überwachen Sie aktive Verbindungen, gepoolte Verbindungen und andere Treibermetriken.
Ereignisquellenverfolgung aktivieren Erfassen Sie detaillierte Fahrerereignisse zur Diagnose.
Leitfaden zur Problembehandlung bei SqlClient Diagnostiziere häufige Verbindungs- und Treiberprobleme.
Abfragebenachrichtigungen Erhalten Sie Benachrichtigungen, wenn sich die Anfrageergebnisse ändern.

SQL Server Funktionen

Artikel Description
SQL Server-Features und ADO.NET Durchstöbern Sie SQL Server-spezifische Funktionen, die über SqlClient verfügbar sind.
Lokale Datenbank Verbinden Sie sich mit SQL Server Express LocalDB-Instanzen.
Datenermittlung und -klassifizierung Lesen Sie Metadaten zur Sensitivitätsklassifikation aus Ergebnissätzen.

Referenz und Ressourcen

Artikel Description
Microsoft. Data.SqlClient API-Referenz Durchsuchen Sie die .NET API-Referenz für den Treiber.
AppContext-Schalter Konfigurieren Sie Kompatibilität und Sicherheitsverhalten.
GitHub-Repository „Microsoft.Data.SqlClient“ Lies den Treibercode, die Release Notes und die Beispiele.
Microsoft.Data.SqlClient-Beispiele Durchsuchen Sie C#-Beispiele für Treiber-APIs.
.NET Runtime GitHub-Repository Lesen Sie die Quellcode für die .NET-Laufzeitbibliotheken.

Anfordern eines Features

Um eine Funktion anzufordern, öffne ein Problem im Microsoft. Data.SqlClient GitHub-Repository.

Verwandte Inhalte

  • Zuletzt aktualisiert um