Gebruik Microsoft. Data.SqlClient in een .NET-app

In deze quickstart maak je een .NET-consoleapplicatie die:

• Leet zijn verbindingsreeks uit de omgeving in plaats van de broncode.
• Opent een verbinding asynchroon.
• Maakt een tabel aan als die niet bestaat.
• Voegt een rij in met een geparametriseerd commando.
• Lest rijen met een geparametriseerde query.
• Behandelt SQL- en annuleringsfouten.

Het voorbeeld gebruikt Microsoft. Data.SqlClient 7.0.3, de huidige stabiele release.

Prerequisites

Je hebt de .NET 10 SDK nodig of een later ondersteunde .NET SDK.

Een SQL-database maken

Maak een SQL-database aan of maak verbinding met een van de volgende platforms:

De quickstart maakt een eigen tabel aan, dus voorbeeldgegevens zijn niet nodig. De database-identiteit heeft toestemming nodig om verbinding te maken en om een tabel te maken, in te voegen en te selecteren.

Voor een SQL-database in Microsoft Fabric kopieert u de server- en databasenamen van het SQL-databaseitem. Gebruik het SQL analytics-endpoint niet. De identiteit heeft een machtiging nodig om items te lezen, die kan worden verleend door een werkruimterol of een itemmachtiging. Voor meer informatie, zie Authenticatie in SQL-database. SQL-authenticatie wordt niet ondersteund.

Voor Azure SQL Database configureer je Microsoft Entra ID-authenticatie en database-toegang.

Het project maken

Voer deze opdrachten uit:

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

Het extensiepakket biedt door de bestuurder geleverde Microsoft Entra ID-authenticatiemodi. Een applicatie die alleen Windows-geïntegreerde authenticatie of SQL-authenticatie gebruikt, kan . weglaten Microsoft.Data.SqlClient.Extensions.Azure

Configureer de verbinding

Stel de omgevingsvariabele SQL_CONNECTION_STRING in voor je database. Zet geen wachtwoord, toegangstoken of productie-verbindingsreeks in de broncode.

Kies een van deze startpunten en vervang de placeholders.

Fabric SQL of Azure SQL met wachtwoordloze authenticatie

Log in met een identiteit in Microsoft Entra ID die toegang heeft tot de database. Voor lokale ontwikkeling gebruik je een ontwikkelaarstool zoals de Azure CLI:

az login

Kopieer de exacte server- en databasenamen van het SQL-databaseitem in Fabric of de Azure SQL-database. Voor PowerShell:

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

Voor Bash:

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

Voor een applicatie die in Azure wordt gehost en verbinding maakt met Azure SQL, verleen de beheerde identiteitsdatabase-toegang en gebruik Authentication=Active Directory Managed Identitydan . Voor andere Microsoft Entra ID-opties, zie Microsoft Entra ID authenticatie.

SQL Server over TCP

Gebruik de server, poort, database en log in vanaf je bestaande SQL Server of de setup-gids die je hebt gevolgd. Het volgende voorbeeld van SQL-authenticatie is voor een lokale ontwikkelcontainer. Voor PowerShell:

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

Voor Bash:

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

Als de omgeving Windows-geïntegreerde authenticatie of Kerberos ondersteunt, vervang User ID dan en Password met Integrated Security=true. Voor setup-vereisten, zie SQL Server-authenticatie.

De toepassingscode toevoegen

Vervang de inhoud van Program.cs met deze 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;
}

De parametertypen en -groottes komen overeen met de kolommen van de tabel. Parameters sturen waarden los van SQL-tekst, wat voorkomt dat die waarden de commandosyntaxis veranderen en SQL Server helpt queryplannen te hergebruiken.

await using sluit de reader en de verbinding af, zelfs wanneer er een uitzondering optreedt. Het afvoeren van de verbinding geeft de fysieke verbinding terug aan de verbindingspool in plaats van één verbinding open te houden gedurende de levensduur van de applicatie.

De toepassing uitvoeren

Voer de toepassing uit:

dotnet run

De applicatie drukt de rij af die is ingevoegd:

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

De identiteitswaarde en tijdstempel verschillen per database.

Als de verbinding faalt, gebruik dan het SQL-foutnummer en de client-verbindings-ID uit de foutoutput. Controleer de server- en databasenamen, netwerktoegang, databasepermissies, authenticatie-instellingen en certificaatconfiguratie. Voeg niet toe TrustServerCertificate=true aan een Azure SQL- of productieverbinding als algemene verbindingsoplossing.

Gebruik het patroon in een applicatie

Houd deze grenzen aan wanneer je het voorbeeld verplaatst naar een API, service, desktopapplicatie of achtergrondwerker:

• Laad verbindingsinformatie via het configuratiesysteem van de applicatie.
• Open één verbinding voor een korte eenheid werk en verwijder die dan.
• Geef een CancellationToken door aan open-, opdracht- en reader-aanroepen.
• Stel commando-timeouts in op basis van de operatie.
• Gebruik parameters voor elke waarde die buiten de SQL-instructie komt.
• Registreer SqlException.Number en ClientConnectionId zonder inloggegevens of toegangstokens te registreren.
• Voeg herpogingen alleen toe bij tijdelijke storingen en alleen wanneer het herhalen van de operatie veilig is.

Volgende stappen 

• Kies en bouw een verbindingsreeks.
• Configureer het verbindingsgedrag.
• Beheer de levenscyclus van de verbinding.
• Gebruik SQL Server-verbindingenpooling.
• Configureer logica voor opnieuw proberen.
• Gebruik commando's en parameters.