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 und SQL Database 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. Nutzen Sie es, um Verbindungen zu öffnen, Befehle auszuführen, Ergebnisse zu verarbeiten, Transaktionen zu verwalten, Daten in großen Mengen zu laden und SQL Server-spezifische Funktionen aus .NET-Anwendungen zu nutzen.

Auswählen des Startpunkts

• Um ein Projekt einzurichten und deine erste Abfrage auszuführen, beginne mit "Starten mit dem SqlClient-Treiber".
• Um den Treiber zu einem .NET-Projekt hinzuzufügen, gehe zu Download Microsoft. Data.SqlClient.
• Um sich mit passwortloser Authentifizierung mit Azure SQL zu verbinden, beginnen Sie mit Microsoft Entra-Authentifizierung und Verbindungszeichenfolgen.
• Um eine bestehende Anwendung widerstandsfähig gegen vorübergehende Fehler zu machen, gehen Sie zu Konfigurierbarer Wiederholungs-Logik sowie High Availability und Disaster Recovery.
• Um große Datensätze effizient zu verschieben, gehen Sie zu Massenkopiervorgänge.
• Für die Migration von System.Data.SqlClient beginnen Sie mit Einführung in den Microsoft.Data.SqlClient-Namespace.
• Um ein Verbindungs- oder Abfrageproblem zu diagnostizieren, gehe zum SqlClient-Fehlerbehebungsleitfaden und aktiviere Ereignisquellen-Tracing.

Produktionsbasisplan für Azure SQL

Nutzen Sie diesen Ausschnitt als Ausgangspunkt für einen produktionsorientierten Azure SQL-Datenzugriffspfad. Es liest die Server- und Datenbanknamen aus IConfiguration, sodass die Werte von den Konfigurationsanbietern stammen, die der Host verkabelt (appsettings.json, Umgebungsvariablen, Azure App Configuration, Key Vault-gestützte Einstellungen usw.). Die Konfiguration kombiniert Transport Layer Security (TLS), die Verwendung einer verwalteten Identität, Resilienz bei Leerlaufverbindungen, Wiederholungen bei der Erstverbindung mithilfe einer konfigurierbaren Wiederholungslogik (CRL) mit strukturiertem Protokollieren, Wiederholungen auf Befehlsebene bei vorübergehenden Fehlern, die während der Abfrage auftreten, sowie die schnelle Wiederherstellung von Failovergruppen.

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.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    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 (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // 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);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Dieser Ausschnitt richtet sich an jeden SQL Datenbank-Engine-Endpunkt, der für Microsoft Entra-Authentifizierung konfiguriert ist: Azure SQL-Datenbank, Azure SQL Managed Instance, SQL Database 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. Es erfordert Microsoft. Data.SqlClient 5.0 und spätere Versionen sowie einen Server, der TDS 8.0 unterstützt (SQL Server 2022 und spätere Versionen, Azure SQL-Datenbank, Azure SQL Managed Instance und SQL Database in Microsoft Fabric). Greifen Sie auf SqlConnectionEncryptOption.Mandatory zurück, wenn Sie eine Verbindung mit älteren Servern herstellen.

ConnectRetryCount und ConnectRetryInterval aktivieren die Resilienz inaktiver Verbindungen: Nach erfolgreichem Open() stellt der Treiber beim nächsten Befehl eine getrennte inaktive Verbindung transparent wieder her. Sie versuchen den Anfangstest Open()nicht erneut. Anfängliche Verbindungs-Wiederholungen stammen vom Anbieter, der openRetry zugeordnet ist SqlConnection.RetryLogicProvider. Die beiden Merkmale ergänzen sich.

Das Retrying-Ereignis für jeden Provider wird vor jedem Wiederholungsversuch ausgelöst und enthält die Anzahl der Wiederholungsversuche, die Verzögerung vor dem nächsten Versuch und die bisher aufgetretenen Ausnahmen. Leiten Sie es an ILogger oder an Ihre Telemetrie-Pipeline weiter, damit die Retry-Schleife im Produktivbetrieb sichtbar bleibt.

Legen Sie MultiSubnetFailover = true fest, wenn das Ziel eine Azure SQL-Datenbank, eine Azure SQL Managed Instance, eine SQL-Datenbank in Microsoft Fabric, ein Verfügbarkeitsgruppenlistener oder eine Failoverclusterinstanz ist. Es wählt einen parallelen Verbindungscodepfad, der versucht, TCP-Verbindungen zu allen aufgelösten IP-Adressen parallel herzustellen, und nutzt die erste erfolgreiche Verbindung, wodurch der langsame, sequentielle pro-IP-Gang vermieden wird, der diese Verbindungen sonst blockieren könnte. Bei Single-IP-Zielen ist die Einstellung sicher. MultiSubnetFailover wird nicht unterstützt, wenn man sich mit einer benannten Instanz verbindet, über ein anderes Protokoll als TCP oder mit einer Instanz, die mit mehr als 64 IP-Adressen konfiguriert ist. Du kannst es auch nicht mit Datenbankspiegelung verwenden, das in allen unterstützten Versionen von SQL Server 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.

Wenn das Ziel Azure SQL-Datenbank serverless mit aktivierter automatischer Pause ist, erhöhen Sie ConnectTimeout auf mindestens 60 Sekunden. Eine automatisch pausierte Datenbank wird beim ersten Open() wieder aufgenommen, und der erste Open() kann mit dem Fehler 40613 fehlschlagen, während die Datenbank wieder aufgenommen wird. Der Fehler 40613 befindet sich in der eingebauten Liste der vorübergehenden Fehler, also openRetry versuche es erneut. Clientseitige Timeouts werden als Fehler -2 angezeigt, das nicht in dieser Liste enthalten ist, sodass openRetry ein Open(), bei dem während der Fortsetzung ein Timeout auftritt, nicht retten kann. Der individuelle Kontaktversuch muss lang genug sein, um den Lebenslauf abzudecken. Weitere Informationen finden Sie unter Auto-pause und Auto-resume.

Ob Wiederholungen auf Befehlsebene erfolgen, entscheidet der Aufrufer für jeden Befehl einzeln. Fügen Sie commandRetry nur dann an SqlCommand.RetryLogicProvider an, wenn das Wiederholen des Befehls sicher ist: Lesevorgänge, MERGE geschützt durch einen natürlichen Schlüssel, Upserts über eine gespeicherte Prozedur und andere idempotente Operationen. Der eingebaute Befehlsanbieter überspringt den erneuten Versuch, wenn eine Transaktion aktiv ist, sodass Multi-Statement-Transaktionen mit Anwendungscode erneut versucht werden müssen, der die Transaktion wieder öffnen kann. Die Einstellung TransientErrors ersetzt die integrierte Fehlerliste des Treibers; um stattdessen die integrierte Standardliste zu erweitern, verwenden Sie SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient ab Version 7.0).

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

• Verbindungszeichenfolgen
• Microsoft Entra-Authentifizierung
• Verschlüsselung und Zertifikatüberprüfung
• Konfigurierbare Wiederholungslogik
• Hohe Verfügbarkeit und Notfallwiederherstellung

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 in Microsoft.Data.SqlClient 5.0 und höher fest.
• Microsoft Entra ID-Authentifizierung: Kennwortlose Verbindungen mit verwalteter Identität, Dienstprinzipal, interaktiven, integrierten, Standard-Anmeldeinformationsketten- und Zugriffstoken-Abläufen.
• 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ügevorgänge mit hohem Durchsatz mit SqlBulkCopy.
• 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.

Get started

Konfigurieren und Verbinden

Authentifizieren und sichern

Daten abrufen und aktualisieren

Datentypen

Zuverlässigkeit und Diagnostik

SQL Server Funktionen

Referenz und Ressourcen

Verwandte Inhalte

• Microsoft. Data.SqlClient auf GitHub
• Microsoft. Data.SqlClient auf NuGet
• Veröffentlichungshinweise
• Überblick über ADO.NET
• Verbindungsmodule für microsoft SQL-Datenbank