Verwenden Sie Microsoft. Data.SqlClient in einer .NET-App

In diesem Quickstart erstellen Sie eine .NET-Konsolenanwendung, die:

• Liest seinen Verbindungszeichenfolge aus der Umgebung statt aus dem Quellcode.
• Öffnet eine Verbindung asynchron.
• Erstellt eine Tabelle, falls sie nicht existiert.
• Fügt eine Zeile mit einem parametrisierten Befehl ein.
• Liest Zeilen mit einer parametrisierten Abfrage.
• Behandelt SQL- und Stornierungsfehler.

Das Beispiel verwendet Microsoft. Data.SqlClient 7.0.3, die aktuelle stabile Version.

Voraussetzungen

Du brauchst das .NET 10 SDK oder ein später unterstütztes .NET SDK.

Erstellen einer SQL-Datenbank

Erstellen oder verbinden Sie sich mit einer SQL-Datenbank auf einer der folgenden Plattformen:

Der Quickstart erstellt eine eigene Tabelle, sodass keine Beispieldaten erforderlich sind. Die Datenbankidentität benötigt die Berechtigung, um sich zu verbinden und eine Tabelle zu erstellen, einzufügen und daraus auszuwählen.

Für die SQL-Datenbank in Microsoft Fabric kopieren Sie die Server- und Datenbanknamen aus dem SQL-Datenbankelement. Nutze nicht den SQL-Analytics-Endpunkt. Die Identität benötigt die Berechtigung zum Lesen des Elements, die durch eine Arbeitsbereichsrolle oder eine Elementberechtigung gewährt werden kann. Weitere Informationen finden Sie unter Authentifizierung in SQL-Datenbank. SQL-Authentifizierung wird nicht unterstützt.

Für Azure SQL-Datenbank konfigurieren Sie Microsoft Entra ID-Authentifizierung und Datenbankzugriff.

Erstelle das Projekt

Führen Sie diese Befehle aus:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.0.3
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.0.3

Das Erweiterungspaket bietet vom Treiber bereitgestellte Microsoft Entra ID-Authentifizierungsmodi. Eine Anwendung, die ausschließlich die in Windows integrierte Authentifizierung oder SQL-Authentifizierung verwendet, kann Microsoft.Data.SqlClient.Extensions.Azure weglassen.

Konfigurieren Sie die Verbindung

Setze die SQL_CONNECTION_STRING Umgebungsvariable für deine Datenbank. Fügen Sie kein Passwort, kein Zugriffstoken und keine Verbindungszeichenfolge für die Produktion in den Quellcode ein.

Wählen Sie einen dieser Ausgangspunkte und ersetzen Sie die Platzhalter.

Fabric SQL oder Azure SQL mit passwortloser Authentifizierung

Melden Sie sich mit einer Identität in der Microsoft Entra ID an, die Zugriff auf die Datenbank hat. Für lokale Entwicklung verwenden Sie ein Entwickler-Tool wie die Azure CLI:

az login

Kopiere die genauen Server- und Datenbanknamen aus dem SQL-Datenbankelement in Fabric oder der Azure SQL-Datenbank. Für PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Für Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Für eine in Azure gehostete Anwendung, die eine Verbindung mit Azure SQL herstellt, gewähren Sie der verwalteten Identität Datenbankzugriff, und verwenden Sie dann Authentication=Active Directory Managed Identity. Für weitere Microsoft Entra ID-Optionen siehe Microsoft Entra ID Authentifizierung.

SQL Server über TCP

Nutze den Server, Port, die Datenbank und melde dich von deinem bestehenden SQL Server oder der Einrichtungsanleitung aus, die du befolgt hast. Das folgende SQL-Authentifizierungsbeispiel bezieht sich auf einen lokalen Entwicklungscontainer. Für PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Für Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Wenn die Umgebung integrierte Windows-Authentifizierung oder Kerberos unterstützt, ersetzen Sie User ID und Password durch Integrated Security=true. Für Einrichtungsanforderungen siehe SQL Server-Authentifizierung.

Hinzufügen des Anwendungscodes

Ersetzen Sie den Inhalt von Program.cs durch den folgenden Code:

using System.Data;
using Microsoft.Data.SqlClient;

string? connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING");

if (string.IsNullOrWhiteSpace(connectionString))
{
    Console.Error.WriteLine(
        "Set the SQL_CONNECTION_STRING environment variable.");
    return 1;
}

using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, eventArgs) =>
{
    eventArgs.Cancel = true;
    cancellation.Cancel();
};

try
{
    await using var connection = new SqlConnection(connectionString);
    await connection.OpenAsync(cancellation.Token);

    const string createTableSql = """
        IF OBJECT_ID(N'dbo.SqlClientQuickstart', N'U') IS NULL
        BEGIN
            CREATE TABLE dbo.SqlClientQuickstart
            (
                Id int IDENTITY(1, 1) PRIMARY KEY,
                Message nvarchar(200) NOT NULL,
                CreatedAt datetimeoffset NOT NULL
                    CONSTRAINT DF_SqlClientQuickstart_CreatedAt
                    DEFAULT sysdatetimeoffset()
            );
        END;
        """;

    using (var createCommand =
        new SqlCommand(createTableSql, connection) { CommandTimeout = 30 })
    {
        await createCommand.ExecuteNonQueryAsync(cancellation.Token);
    }

    const string insertSql = """
        INSERT INTO dbo.SqlClientQuickstart (Message)
        OUTPUT INSERTED.Id
        VALUES (@message);
        """;

    int insertedId;
    using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        insertCommand.Parameters.Add(
            new SqlParameter("@message", SqlDbType.NVarChar, 200)
            {
                Value = "Hello from Microsoft.Data.SqlClient"
            });

        object? result =
            await insertCommand.ExecuteScalarAsync(cancellation.Token);
        insertedId = Convert.ToInt32(result);
    }

    const string querySql = """
        SELECT Id, Message, CreatedAt
        FROM dbo.SqlClientQuickstart
        WHERE Id = @id
        ORDER BY Id;
        """;

    using var queryCommand =
        new SqlCommand(querySql, connection) { CommandTimeout = 30 };
    queryCommand.Parameters.Add(
        new SqlParameter("@id", SqlDbType.Int) { Value = insertedId });

    await using SqlDataReader reader =
        await queryCommand.ExecuteReaderAsync(cancellation.Token);

    while (await reader.ReadAsync(cancellation.Token))
    {
        Console.WriteLine(
            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
            $"at {reader.GetDateTimeOffset(2):O}");
    }

    return 0;
}
catch (OperationCanceledException)
{
    Console.Error.WriteLine("The operation was canceled.");
    return 2;
}
catch (SqlException ex)
{
    Console.Error.WriteLine(
        $"SQL error {ex.Number}, connection {ex.ClientConnectionId}: " +
        ex.Message);
    return 3;
}

Die Parametertypen und -größen stimmen mit den Tabellenspalten überein. Parameter senden Werte getrennt vom SQL-Text, was verhindert, dass diese Werte die Befehlssyntax ändern und SQL Server die Wiederverwendung von Abfrageplänen ermöglicht.

await using gibt den Reader und die Verbindung auch dann frei, wenn eine Ausnahme auftritt. Das Freigeben der Verbindung gibt ihre physische Verbindung an den Verbindungspool zurück, anstatt für die gesamte Lebensdauer der Anwendung eine Verbindung offen zu halten.

Ausführen der Anwendung

Führen Sie die Anwendung aus:

dotnet run

Die Anwendung druckt die Zeile, die sie eingefügt hat:

1: Hello from Microsoft.Data.SqlClient at <timestamp>

Der Identitätswert und der Zeitstempel unterscheiden sich in jeder Datenbank.

Wenn die Verbindung fehlschlägt, verwenden Sie die SQL-Fehlernummer und die Client-Verbindungs-ID aus der Fehlerausgabe. Überprüfen Sie Server- und Datenbanknamen, Netzwerkzugriff, Datenbankberechtigungen, Authentifizierungseinrichtung und Zertifikatskonfiguration. Füge TrustServerCertificate=true nicht als allgemeine Verbindungskorrektur zu einer Azure SQL- oder Produktionsverbindung hinzu.

Verwenden Sie das Muster in einer Anwendung

Behalten Sie diese Grenzen ein, wenn Sie die Probe in eine API, einen Dienst, eine Desktop-Anwendung oder einen Hintergrundarbeiter übertragen:

• Laden Sie die Verbindungsinformationen über das Konfigurationssystem der Anwendung.
• Öffne eine Verbindung für eine kurze Arbeitseinheit und entsorge sie dann.
• Übergeben Sie ein CancellationToken an open-, command- und reader-Aufrufe.
• Setze Kommando-Timeouts basierend auf der Operation.
• Verwenden Sie Parameter für jeden Wert, der außerhalb der SQL-Anweisung kommt.
• Protokollieren Sie SqlException.Number und ClientConnectionId, ohne Zugangsdaten oder Zugriffstoken zu protokollieren.
• Erneute Versuche nur bei vorübergehenden Ausfällen hinzufügen und nur, wenn die Wiederholung der Operation sicher ist.

Nächste Schritte

• Wähle und baue eine Verbindungszeichenfolge aus.
• Konfiguriere das Verbindungsverhalten.
• Verwalten Sie den Verbindungslebenszyklus.
• Verwenden Sie SQL Server Connection Pooling.
• Konfigurieren Sie die Wiederholungslogik.
• Verwenden Sie Befehle und Parameter.