Utilisez Microsoft. Data.SqlClient dans une application .NET

Dans ce démarrage rapide, vous créez une application console .NET qui :

Lit sa chaîne de connexion depuis l’environnement au lieu du code source.
Ouvre une connexion de façon asynchrone.
Crée une table si elle n’existe pas.
Insère une ligne avec une commande paramétrée.
Lit les lignes avec une requête paramétrée.
Gère les erreurs SQL et d’annulation.

L’exemple utilise Microsoft. Data.SqlClient 7.0.3, la version stable actuelle.

Prerequisites

Vous avez besoin du SDK .NET 10 ou d’un SDK .NET compatible plus récent.

Créer une base de données SQL

Créer ou connecter une base de données SQL sur l’une des plateformes suivantes :

Créer une base de données SQL en quelques minutes à l’aide du portail Azure

Le démarrage rapide crée sa propre table, donc les données d’exemple ne sont pas nécessaires. L’identité de la base de données nécessite une autorisation pour se connecter, créer, insérer et sélectionner dans une table.

Pour la base de données SQL dans Microsoft Fabric, copiez les noms du serveur et de la base de données à partir de l’élément de la base SQL. N’utilisez pas le point d’accès SQL analytics. L’identité nécessite une permission de lecture d’élément, qu’un rôle d’espace de travail ou une permission d’élément peut fournir. Pour plus d’informations, voir Authentification dans la base de données SQL. L’authentification SQL n’est pas prise en charge.

Pour Azure SQL Database, configurez l’authentification et l’accès à la base de données Microsoft Entra ID.

Créer le projet

Exécutez les commandes suivantes :

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

Le package d’extension fournit des modes d’authentification Microsoft Entra ID fournis par les pilotes. Une application qui utilise uniquement l’authentification intégrée Windows ou l’authentification SQL peut omettre Microsoft.Data.SqlClient.Extensions.Azure.

Configurez la connexion

Définissez la SQL_CONNECTION_STRING variable environnement pour votre base de données. Ne mettez pas de mot de passe, de token d'accès ou de chaîne de connexion de production dans le code source.

Choisissez l’un de ces points de départ et remplacez les espaces réservés.

Fabric SQL ou Azure SQL avec authentification sans mot de passe

Connectez-vous avec une identité dans Microsoft Entra ID qui a accès à la base de données. Pour le développement local, utilisez un outil de développement tel que l’Azure CLI :

az login

Copiez les noms exacts des serveurs et des bases de données depuis l’élément SQL dans Fabric ou la base de données Azure SQL. Pour PowerShell :

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

Pour Bash :

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

Pour une application hébergée dans Azure qui se connecte à Azure SQL, accordez à sa base d’identité gérée l’accès à la base de données, puis utilisez Authentication=Active Directory Managed Identity. Pour d’autres options de Microsoft Entra ID, voir authentification Microsoft Entra ID.

SQL Server sur TCP

Utilisez le serveur, le port, la base de données et la connexion depuis votre SQL Server existant ou le guide de configuration que vous avez suivi. L’exemple d’authentification SQL suivant concerne un conteneur de développement local. Pour PowerShell :

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

Pour Bash :

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

Caution

TrustServerCertificate=true Ignore la validation des certificats serveur. Utilisez-le uniquement avec une instance de développement local qui n’a pas de certificat de confiance. Pour les instances SQL Server partagées ou de production, installez un certificat auquel le client fait confiance, utilisez le nom du serveur sur ce certificat, puis supprimez TrustServerCertificate=true.

Si l’environnement supporte l’authentification intégrée Windows ou Kerberos, remplacez User ID et Password par Integrated Security=true. Pour les exigences d’installation, voir authentification SQL Server.

Ajouter le code de l’application

Remplacez le contenu de Program.cs par ce 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;
}

Les types et tailles des paramètres correspondent aux colonnes du tableau. Les paramètres envoient des valeurs séparément du texte SQL, ce qui empêche ces valeurs de modifier la syntaxe des commandes et aide SQL Server à réutiliser les plans de requête.

await using élimine le lecteur et la connexion même lorsqu’une exception survient. La suppression de la connexion renvoie sa connexion physique au pool de connexions au lieu de laisser une seule connexion ouverte pendant toute la durée de vie de l’application.

Exécuter l’application

Exécutez l’application :

dotnet run

L’application affiche la ligne qu’elle a insérée :

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

La valeur d’identité et l’horodatage diffèrent selon chaque base de données.

Si la connexion échoue, utilisez le numéro d’erreur SQL et l’identifiant de connexion client provenant de la sortie d’erreur. Vérifiez les noms des serveurs et des bases de données, l’accès réseau, les permissions à la base de données, la configuration de l’authentification et la configuration des certificats. N’ajoutez pas TrustServerCertificate=true à une connexion Azure SQL ou à une connexion de production comme correctif générique de connexion.

Utiliser le motif dans une application

Conservez ces limites lorsque vous déplacez l’échantillon dans une API, un service, une application de bureau ou un travailleur en arrière-plan :

Chargez les informations de connexion via le système de configuration de l’application.
Ouvrez une connexion pour une brève opération, puis fermez-la.
Transmettez un CancellationToken via les appels open, command et reader.
Définissez des délais de commande en fonction de l’opération.
Utilisez des paramètres pour chaque valeur provenant de l’extérieur de l’instruction SQL.
Consignez SqlException.Number et ClientConnectionId sans consigner les identifiants ni les jetons d’accès.
Ajouter des réessais uniquement en cas d’échecs transitoires et seulement lorsque la répétition de l’opération ne présente aucun risque.

Étapes suivantes

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-09-21