Démarrage rapide : connectez-vous et exécutez des requêtes avec Microsoft.Data.SqlClient

Dans ce guide de démarrage rapide, vous développez une application console .NET avec Microsoft.Data.SqlClient 7.1.1.

Vous commencez avec un dossier vide, le SDK .NET, et une base de données SQL Server ou Azure SQL accessible depuis votre ordinateur. Vous terminez avec une application console qui crée une table, insère deux lignes avec des paramètres, puis les relit.

En chemin, l’application :

Lit sa chaîne de connexion à partir d’une variable d’environnement au lieu du code source.
Ouvre une connexion de façon asynchrone.
Utilise des paramètres pour chaque valeur envoyée à la base de données.
Gère les erreurs SQL et les annulations.

Pour intégrer le même accès aux données dans une API web, voir Quickstart : Utilisez Microsoft. Data.SqlClient dans une application ASP.NET Core. Il utilise le même tableau.

Prerequisites

Le SDK .NET 10 ou un SDK .NET ultérieur pris en charge. Le SDK fonctionne sous Windows, Linux et macOS. Le SDK construit également la version .NET Framework de l’exemple, qui fonctionne uniquement sous Windows et nécessite .NET Framework 4.8.1. Utilisez la version .NET pour le nouveau développement.
Un éditeur de code. Vous pouvez utiliser Visual Studio, Visual Studio Code, ou n’importe quel éditeur en même temps que la ligne de commande .NET. Cet article utilise .NET CLI.
Une base de données à laquelle vous pouvez vous connecter. Si vous n’en avez pas, créez-en un en utilisant les options suivantes.

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

Autorisations de base de données

L’application crée sa propre table, donc vous n’avez pas besoin de données d’échantillon. 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.

Dans un dossier vide, exécutez ces commandes :

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

Le modèle console n'offre pas de cibles .NET Framework. Dans un dossier vide, créez le projet :

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart

Remplacez le contenu de SqlClientQuickstart.csproj par ce fichier projet :

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net481</TargetFramework>
  </PropertyGroup>

</Project>

Ensuite, ajoutez les paquets :

dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

Le package d'extension fournit les modes d'authentification Microsoft Entra du pilote, tels que Active Directory Default. Si votre application utilise uniquement l’authentification SQL ou l’authentification intégrée Windows, vous pouvez omettre Microsoft.Data.SqlClient.Extensions.Azure. Lorsque vous utilisez les deux paquets, gardez leurs versions identiques. Pour d’autres options d’installation, voir Installer, mettre à jour et déployer Microsoft.Data.SqlClient.

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.

Azure SQL ou base de données SQL dans Fabric avec Microsoft Entra ID

Connectez-vous avec une identité Microsoft Entra 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 de la base de données depuis la base de données Azure SQL ou l’élément de la base de données SQL dans Fabric. 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, accordez à son identité managée l’accès à la base de données, puis utilisez Authentication=Active Directory Managed Identity. Pour d’autres options, voir authentification Microsoft Entra avec Microsoft.Data.SqlClient.

SQL Server avec authentification SQL

Utilisez le serveur, le port, la base de données et l’identifiant de connexion pour votre instance SQL Server. L’exemple suivant concerne une instance de développement local qui ne possède pas de certificat de confiance. 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. Pour plus d’informations, consultez Validation du chiffrement et des certificats dans Microsoft.Data.SqlClient.

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

Ajouter le code

.NET
.NET Framework

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;
        """;

    await 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);
        """;

    string[] messages =
    [
        "Hello from Microsoft.Data.SqlClient",
        "Parameters keep values out of the SQL text"
    ];

    int firstId = 0;
    await using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        SqlParameter messageParameter =
            insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

        foreach (string message in messages)
        {
            messageParameter.Value = message;
            int id = (int)(await insertCommand.ExecuteScalarAsync(
                cancellation.Token))!;
            Console.WriteLine($"Inserted row {id}.");
            firstId = firstId == 0 ? id : firstId;
        }
    }

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

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

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

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

    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);
    if (ex.InnerException is not null)
    {
        Console.Error.WriteLine(ex.InnerException.Message);
    }
    return 3;
}

Remplacez le contenu de Program.cs par ce code :

using System;
using System.Data;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task<int> Main()
    {
        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 += (sender, eventArgs) =>
            {
                eventArgs.Cancel = true;
                cancellation.Cancel();
            };

            try
            {
                await RunAsync(connectionString, cancellation.Token);
                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);
                if (ex.InnerException != null)
                {
                    Console.Error.WriteLine(ex.InnerException.Message);
                }
                return 3;
            }
        }
    }

    static async Task RunAsync(string connectionString, CancellationToken token)
    {
        using (var connection = new SqlConnection(connectionString))
        {
            await connection.OpenAsync(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(token);
            }

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

            string[] messages =
            {
                "Hello from Microsoft.Data.SqlClient",
                "Parameters keep values out of the SQL text"
            };

            int firstId = 0;
            using (var insertCommand =
                new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
            {
                SqlParameter messageParameter =
                    insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

                foreach (string message in messages)
                {
                    messageParameter.Value = message;
                    int id = (int)await insertCommand.ExecuteScalarAsync(token);
                    Console.WriteLine($"Inserted row {id}.");
                    firstId = firstId == 0 ? id : firstId;
                }
            }

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

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

                using (SqlDataReader reader =
                    await queryCommand.ExecuteReaderAsync(token))
                {
                    while (await reader.ReadAsync(token))
                    {
                        Console.WriteLine(
                            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
                            $"(created {reader.GetDateTimeOffset(2):u})");
                    }
                }
            }
        }
    }
}

Exécuter l’application

Exécutez l’application :

dotnet run

La première fois que vous lancez l’application, la table est vide et la sortie ressemble à ceci :

Inserted row 1.
Inserted row 2.
1: Hello from Microsoft.Data.SqlClient (created 2026-10-20 20:56:10Z)
2: Parameters keep values out of the SQL text (created 2026-10-20 20:56:10Z)

Vos horodatages diffèrent. Chaque exécution ultérieure ajoute deux lignes supplémentaires, de sorte que les IDs continuent à partir de la dernière exécution.

Si l’application ne peut pas se connecter, elle affiche le numéro d’erreur SQL, l’identifiant de connexion client, le message d’erreur et le message d’exception interne, puis se termine avec le code 3. Pour les erreurs courantes, voir Dépannage.

Fonctionnement du code

OpenAsync, ReadAsync, CancellationToken, ExecuteReaderAsync et ExecuteScalarAsync tous reçoivent la même ExecuteNonQueryAsync. Appuyez sur Ctrl+C pour annuler le travail en cours.
La commande insert est créée une fois et s’exécute une fois pour chaque message. Seule la valeur du paramètre change.
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 commande et aide SQL Server à réutiliser les plans de requête.
OUTPUT INSERTED.Id renvoie la nouvelle valeur d’identité, donc ExecuteScalarAsync retourne l’ID sans seconde requête.
await using libère les commandes, le lecteur de données et la connexion, même lorsqu’une exception survient. Éliminer la connexion la renvoie au pool de connexions. La version du framework .NET utilise des blocs using, car ces types n’implémentent pas IAsyncDisposable sur le framework .NET.
SqlException.Number identifie l’erreur et ClientConnectionId permet de faire correspondre une défaillance client aux journaux côté serveur. Pour les échecs de connexion sous Linux et macOS, la cause se trouve souvent uniquement dans InnerException, comme un échec de validation de certificat derrière le générique error: 35 - An internal exception was caught.

Troubleshoot

Erreur ou symptôme	Que vérifier	Plus d’informations
`The certificate chain was issued by an authority that is not trusted`Sur Windows. Sur Linux et macOS, `error: 35 - An internal exception was caught`, suivi de l’exception interne `Certificate failed chain validation` avec `UntrustedRoot`.	Le certificat serveur n'est pas approuvé par le client, ou le nom du serveur dans la chaîne de connexion ne correspond pas au certificat. Installez un certificat de confiance. À utiliser `TrustServerCertificate=true` uniquement avec une instance de développement local.	Chiffrement et validation de certificats chez Microsoft. Data.SqlClient
`SQL error 18456` avec `Login failed for user`	Le nom d’utilisateur, le mot de passe ou le nom de la base de données est incorrect, ou l’identifiant n’a pas accès à la base de données. Pour Microsoft Entra ID, vérifiez que l’identité a été ajoutée en tant qu’utilisateur de base de données.	Guide de résolution des problèmes SqlClient
`A network-related or instance-specific error occurred` avec `error: 26`, `error: 40`ou `The wait operation timed out`. Sur Linux et macOS, un dépassement de délai affiche `SQL error 258` avec `error: 35`, suivi de l’exception interne `The connection attempt timed out`.	Le nom du serveur ou du port est incorrect, le serveur n’accepte pas les connexions TCP à distance, ou un pare-feu bloque le port. Pour Azure SQL, vérifiez les règles du pare-feu serveur.	Guide de résolution des problèmes SqlClient
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	La chaîne de connexion utilise un mode d’authentification `Active Directory`, mais le projet ne fait pas référence à `Microsoft.Data.SqlClient.Extensions.Azure`. Ajoutez le package avec la même version que `Microsoft.Data.SqlClient`.	L’authentification Microsoft Entra passe à un package d’extension en 7.0
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	Le projet ne fait pas référence au `Microsoft.Data.SqlClient` paquet. Exécutez la commande `dotnet add package` depuis le dossier contenant le fichier projet.	Installer, mettre à jour et déployer Microsoft. Data.SqlClient
Restaurer les rapports `NU1902` ou `NU1903` pour un package transitif	Un paquet dont dépend le pilote a un avis de sécurité publié.	Actions lorsque des paquets présentant des vulnérabilités connues sont signalés

Nettoyer les ressources

La table reste dans votre base de données après la fermeture de l’application. Si vous ne prévoyez pas de continuer avec le guide de démarrage rapide ASP.NET Core, qui utilise la même table, supprimez-la avec n'importe quel outil de requête :

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Ensuite, supprime le dossier du projet. Depuis le dossier parent, pour PowerShell :

Remove-Item -Recurse -Force SqlClientQuickstart

Pour Bash :

rm -rf SqlClientQuickstart

Effacez la variable d’environnement pour que la chaîne de connexion ne reste pas dans votre session shell. Pour PowerShell, exécutez Remove-Item Env:\SQL_CONNECTION_STRING. Pour Bash, exécutez unset SQL_CONNECTION_STRING.

Utiliser le motif dans une application

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

Récupérez 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 ?

Dernière mise à jour : 2026-10-23

Démarrage rapide : connectez-vous et exécutez des requêtes avec Microsoft.Data.SqlClient

Prerequisites

Créer une base de données SQL

Autorisations de base de données

Créer le projet

Configurez la connexion

Azure SQL ou base de données SQL dans Fabric avec Microsoft Entra ID

SQL Server avec authentification SQL

Ajouter le code

Exécuter l’application

Fonctionnement du code

Troubleshoot

Nettoyer les ressources

Utiliser le motif dans une application

Étapes suivantes

Commentaires

Ressources supplémentaires