Verbinden Sie sich mit einer Datenquelle mit Microsoft. Data.SqlClient

SqlConnectionstellt eine logische Verbindung zu SQL Server, Azure SQL oder einem anderen unterstützten SQL Server-kompatiblen Endpunkt dar. Das Öffnen des Objekts erhält eine physische Verbindung aus dem Verbindungspool, wenn eine verfügbar ist. Das Schließen oder Entsorgen stellt diese physische Verbindung zum Pool wieder her.

Nutze kurzlebige SqlConnection Objekte für Arbeitseinheiten. Lass keine globale Verbindung für die Anwendung offen.

Bauen Sie die Verbindungskonfiguration auf

Laden Sie eine Verbindungszeichenfolge aus dem Konfigurationssystem der Anwendung. Verwenden Sie SqlConnectionStringBuilder, wenn im Code Einstellungen überprüft oder hinzugefügt werden müssen:

string configuredConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(configuredConnectionString)
{
    ApplicationName = "Orders.Api",
};

Erstelle das SqlConnection aus builder.ConnectionString. Fügen Sie Benutzereingaben nicht in die Zeichenkette ein. Für Authentifizierungsmuster, sicheren Speicher und Syntax siehe Connection strings.

Verbindungen öffnen und schließen

Rufen Sie OpenAsync in synchronem Code oder Open in asynchronem Code auf. Öffne für jede unabhängige Operation eine neue logische Verbindung:

public static async Task<string?> LoadOrderStatusAsync(
    string connectionString,
    int orderId,
    CancellationToken cancellationToken)
{
    await using var connection = new SqlConnection(connectionString);
    await connection.OpenAsync(cancellationToken);

    const string sql = """
        SELECT Status
        FROM Sales.Orders
        WHERE OrderId = @orderId;
        """;

    using var command =
        new SqlCommand(sql, connection) { CommandTimeout = 30 };
    command.Parameters.Add(
        new SqlParameter("@orderId", SqlDbType.Int) { Value = orderId });

    object? value =
        await command.ExecuteScalarAsync(cancellationToken);
    return value is null or DBNull ? null : (string)value;
}

Die await using Anweisung gibt die Verbindung im Erfolgsfall, bei einem Fehler oder bei Abbruch frei. Mit aktiviertem Pooling setzt die Entsorgung normalerweise die physische Verbindung zurück und gibt sie zurück, anstatt den Netzwerksockel zu schließen.

Entsorgen Sie Reader und Befehlsobjekte vor der zugehörigen Verbindung. Verlassen Sie sich nicht auf die Müllabfuhr oder einen Finalizer, um die Verbindungen zum Pool zurückzugeben.

Verwenden von asynchronen APIs

Verwenden Sie asynchrone Aufrufe für netzwerkgebundene Datenbankarbeiten in Webservern, Diensten, Benutzeroberflächen und Arbeitern:

  • OpenAsync(cancellationToken)
  • ExecuteNonQueryAsync(cancellationToken)
  • ExecuteReaderAsync(cancellationToken)
  • ExecuteScalarAsync(cancellationToken)
  • ReadAsync(cancellationToken)

Du brauchst Asynchronous Processing=truenicht. Microsoft. Data.SqlClient 4.0 und neuere Versionen unterstützen dieses Verbindungszeichenfolge-Schlüsselwort nicht.

Starten Sie keine weitere Operation an einer Verbindung, einem Befehl oder einem Leser, bevor die aktuelle asynchrone Operation abgeschlossen ist.

Stornierung und Timeouts anwenden

Gib das CancellationToken des Aufrufers bei jedem asynchronen Datenbankaufruf weiter. Eine Stornierung fordert den Anbieter auf, die ausstehenden Arbeiten einzustellen, aber die sofortige Fertigstellung ist nicht garantiert. Verwende weiterhin begrenzte Zeitlimits für Verbindungen und Befehle.

Diese Steuerungen haben getrennte Umfangsbereiche:

Steuerung Umfang
Connect Timeout Verbindungsaufbau oder Warten auf eine gepoolte Verbindung
SqlCommand.CommandTimeout Eine Befehlsausführung
CancellationToken Vom Anrufer angeforderte Abbruch einer asynchronen Operation

Ein Timeout oder eine Stornierung beweist nicht, dass der Server eine Operation zurückgesetzt hat. Verwenden Sie eine Transaktion, wenn mehrere Änderungen als eine Einheit festgeschrieben oder zurückgesetzt werden müssen, und treffen Sie Wiederholungsentscheidungen auf Grundlage der Idempotenz des Vorgangs und des Transaktionsergebnisses.

Verstehen Sie den Verbindungszustand

Die Eigenschaft State liefert einen Schnappschuss aus der ConnectionState Aufzählung.

State Meaning
Closed Die logische Verbindung ist nicht offen.
Connecting Eine offene Operation ist im Gange.
Open Die logische Verbindung ist offen.

Verwenden Sie State nicht vor jedem Befehl als Integritätsprüfung. Das Netzwerk kann nach jeder Überprüfung ausfallen. Führen Sie die Operation aus und behandeln Sie die resultierende Ausnahme.

Der Fahrer meldet normalerweise Übergänge von geschlossen zu offen und von offen zu geschlossen. Betrachten Sie Executing, Fetching oder Broken nicht als Phasen des Anwendungslebenszyklus.

Das StateChangeEreignis meldet Zustandsübergänge. Das InfoMessage-Ereignis gibt Informationsmeldungen und Serverwarnungen aus, die nicht zu Ausnahmen werden. Nutze diese Ereignisse für Diagnosen, nicht für die Koordination gleichzeitiger Arbeit.

Eine Verbindung nicht gleichzeitig gemeinsam nutzen.

SqlConnection, SqlCommand, , SqlDataReaderund SqlTransaction unterstützen keine gleichzeitige Nutzung durch mehrere Threads. Geben Sie jeder gleichzeitigen Operation ihre eigene Verbindung, und lassen Sie das Verbindungspooling für die Wiederverwendung der physischen Verbindungen sorgen.

Multiple Active Result Sets (MARS) erlaubt in unterstützten Szenarien mehrere aktive Batches auf einer Verbindung. Es macht SqlClient-Objekte nicht threadsicher und fügt Session- und Transaktionsregeln hinzu. Lass es deaktiviert, es sei denn, ein Vorgang benötigt es ausdrücklich.

Registrieren Sie kein offenes SqlConnection als Singleton in der Abhängigkeitsinjektion. Registrieren Sie den Verbindungszeichenfolge, ein unveränderliches Optionsobjekt oder eine Fabrik, die eine neue Verbindung erstellt.

Nutze Transaktionen bewusst

Eine lokale Transaktion ist ihrer Verbindung zugeordnet. Jeder Befehl in der Transaktion muss diese Verbindung verwenden und deren Transaction Eigenschaft festlegen.

await using var connection = new SqlConnection(connectionString);
await connection.OpenAsync(cancellationToken);

await using SqlTransaction transaction =
    (SqlTransaction)await connection.BeginTransactionAsync(cancellationToken);

using var command = new SqlCommand(sql, connection, transaction);
command.Parameters.Add(
    new SqlParameter("@value", SqlDbType.Int) { Value = value });
await command.ExecuteNonQueryAsync(cancellationToken);

await transaction.CommitAsync(cancellationToken);

Wenn der Vorgang vor CommitAsync fehlschlägt, wird die Transaktion beim Freigeben zurückgesetzt. Halten Sie die Transaktionen kurz. Mach keine Netzwerkaufrufe, keine Benutzerinteraktionen oder nicht zusammenhängende Berechnungen, während eine Datenbanktransaktion Sperren hält.

Wenn System.Transactions.Transaction.Current aktiv ist, werden Open und OpenAsync standardmäßig automatisch registriert. Legen Sie Enlist=false nur fest, wenn der Vorgang außerhalb der umgebenden Transaktion bleiben muss.

Messung einer logischen Verbindung

StatisticsEnabled auf true festlegen, um Anbieterstatistiken für ein SqlConnection-Objekt zu erfassen:

await using var connection = new SqlConnection(connectionString)
{
    StatisticsEnabled = true,
};

await connection.OpenAsync(cancellationToken);
connection.ResetStatistics();

using var command = new SqlCommand(sql, connection);
await command.ExecuteNonQueryAsync(cancellationToken);

System.Collections.IDictionary statistics =
    connection.RetrieveStatistics();
long roundTrips =
    Convert.ToInt64(statistics["ServerRoundtrips"]);

RetrieveStatistics gibt einen Schnappschuss zurück. ResetStatistics beginnt eine neue Messgrenze. Setzen Sie StatisticsEnabled=false auf „Sammeln beenden“; die bisher erfassten Werte bleiben verfügbar. Statistiken werden pro Verbindungsobjekt erfasst und verursachen zusätzlichen Aufwand; aktivieren Sie sie daher nur für gezielte Fehlerdiagnosen statt für jede Anfrage in der Produktion.

Für prozessweite Pool- und Verbindungsmessungen verwenden Sie SqlClient-Diagnosezähler.

Verarbeiten von Verbindungsfehlern

Fangen Sie SqlException an einer Stelle ab, an der der Fehler protokolliert, übersetzt oder ein erneuter Versuch ausgelöst werden kann. Aufzeichnung:

  • Number
  • State
  • Class
  • ClientConnectionId
  • Der Operationsname sowie konfigurierte Server- und Datenbankkennungen

Protokolliere nicht die Verbindungszeichenfolge, das Passwort, das Client-Secret oder das Zugriffstoken.

Löschen Sie eine defekte Verbindung. Der Pool entfernt ungültige physische Verbindungen, sobald sie erkannt werden. Wenn sich eine Zugangsdaten, ein Token, ein Zertifikat, ein DNS-Ziel oder ein Server geändert hat, korrigieren Sie die Konfiguration, bevor Sie es erneut versuchen.

Verwenden Sie beschränkte Wiederholungslogik nur für vorübergehende Ausfälle. Wiederholungsversuch bei der ersten Verbindungsöffnung, Wiederherstellung inaktiver Verbindungen und Befehlswiederholung sind verschiedene Mechanismen. Siehe Konfigurierbare Wiederholungslogik.

Verwandte Inhalte

  • Zuletzt aktualisiert um