Démarrage rapide : Utilisez Microsoft. Data.SqlClient dans une application ASP.NET Core

Dans ce démarrage rapide, vous construisez une API minimale ASP.NET Core 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 API web qui ajoute un message à une table et le lit par ID.

En chemin, l’application :

  • Lit sa chaîne de connexion depuis la configuration ASP.NET Core. Pour le développement local, la valeur vient des secrets utilisateur, donc elle reste hors de votre dossier de projet.
  • Enregistre une classe de données avec injection de dépendances.
  • Ouvre et ferme une connexion pour chaque requête, ce qui permet au pool de connexions par défaut de réutiliser les connexions physiques.
  • Il transmet le CancellationToken de la requête à chaque appel de base de données.

L’application utilise la même dbo.SqlClientQuickstart table que Démarrage rapide : se connecter et exécuter des requêtes avec Microsoft.Data.SqlClient. Vous pouvez commencer par n’importe lequel des guides de démarrage rapide.

Prerequisites

Le ASP.NET Core actuel fonctionne sur .NET, pas sur .NET Framework. Pour utiliser le pilote avec le .NET Framework, voir les projets .NET Framework.

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.

Créer le projet

Dans un dossier vide, exécutez ces commandes :

dotnet new web --framework net10.0 --name SqlClientWebQuickstart
cd SqlClientWebQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1
dotnet user-secrets init

dotnet user-secrets init Ajoute UserSecretsId au fichier projet. ASP.NET Core charge les secrets utilisateur uniquement lorsque l’application s’exécute dans l’environnement Development, ce qui est le cas par défaut pour dotnet run.

Le package d'extension fournit les modes d'authentification Microsoft Entra du pilote. Si votre application utilise uniquement l’authentification SQL, vous pouvez omettre Microsoft.Data.SqlClient.Extensions.Azure. Lorsque vous utilisez les deux paquets, gardez leurs versions identiques.

Configurez la connexion

Stockez la chaîne de connexion comme ConnectionStrings:Quickstart dans les secrets utilisateur. Les secrets utilisateur sont stockés dans votre profil utilisateur, pas dans le dossier du projet, donc ils ne sont pas validés dans le contrôle de code source. Ne mettez pas de mot de passe ni de chaîne de connexion de production dans appsettings.json.

Choisissez l’un de ces points de départ et remplacez les espaces réservés. Les dotnet user-secrets set commandes utilisent des guillemets simples pour PowerShell et Bash. Dans l’invite de commande, utilisez plutôt des guillemets doubles, car l’invite de commande stocke des guillemets simples comme partie de la clé et de la valeur.

Azure SQL 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

Ensuite, stockez la chaîne de connexion. Copiez les noms exacts des serveurs et de la base de données à partir de la base de données Azure SQL. La même chaîne de connexion fonctionne pour la base de données SQL dans Microsoft Fabric lorsque vous utilisez les noms du serveur et de la base de données de l’élément de base de données SQL, comme décrit dans le démarrage rapide de la console.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;Connect Timeout=30'

Cette chaîne de connexion ne contient pas de secret. Active Directory Default Utilise votre connexion développeur localement. Lorsque vous déployez sur Azure App Service ou Azure Container Apps, accordez à l’identité gérée de l’application l’accès à la base de données, changez la valeur en Authentication=Active Directory Managed Identity, et définissez-la dans la configuration de l’hôte sous la forme ConnectionStrings__Quickstart. Pour d’autres options, voir authentification Microsoft Entra avec Microsoft.Data.SqlClient.

SQL Server local avec authentification SQL

Stockez la chaîne de connexion pour une instance de développement locale qui ne possède pas de certificat de confiance. Utilisez des guillemets simples pour empêcher PowerShell et Bash d’étendre un $ caractère dans le mot de passe.

dotnet user-secrets set 'ConnectionStrings:Quickstart' '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. Pour les instances SQL Server partagées ou de production, installez un certificat approuvé par le client et supprimez TrustServerCertificate=true. Pour plus d’informations, consultez Validation du chiffrement et des certificats dans Microsoft.Data.SqlClient.

Ajouter le code

Remplacez le contenu de Program.cs par ce code :

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<MessageStore>();

var app = builder.Build();

await app.Services.GetRequiredService<MessageStore>()
    .EnsureTableAsync(app.Lifetime.ApplicationStopping);

app.MapPost("/messages", async (
    NewMessage input, MessageStore store, CancellationToken cancellationToken) =>
{
    if (string.IsNullOrWhiteSpace(input.Text) || input.Text.Length > 200)
    {
        return Results.BadRequest("Text must be 1 to 200 characters.");
    }

    Message message = await store.AddAsync(input.Text, cancellationToken);
    return Results.Created($"/messages/{message.Id}", message);
});

app.MapGet("/messages/{id:int}", async (
    int id, MessageStore store, CancellationToken cancellationToken) =>
    await store.GetAsync(id, cancellationToken) is Message message
        ? Results.Ok(message)
        : Results.NotFound());

app.Run();

record NewMessage(string Text);

record Message(int Id, string Text, DateTimeOffset CreatedAt);

sealed class MessageStore(IConfiguration configuration)
{
    private readonly string _connectionString =
        configuration.GetConnectionString("Quickstart")
        ?? throw new InvalidOperationException(
            "Set the ConnectionStrings:Quickstart configuration value.");

    public async Task EnsureTableAsync(CancellationToken cancellationToken)
    {
        const string sql = """
            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 connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        await command.ExecuteNonQueryAsync(cancellationToken);
    }

    public async Task<Message> AddAsync(
        string text, CancellationToken cancellationToken)
    {
        const string sql = """
            INSERT INTO dbo.SqlClientQuickstart (Message)
            OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt
            VALUES (@message);
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@message", SqlDbType.NVarChar, 200).Value = text;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        await reader.ReadAsync(cancellationToken);
        return new Message(
            reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2));
    }

    public async Task<Message?> GetAsync(
        int id, CancellationToken cancellationToken)
    {
        const string sql = """
            SELECT Id, Message, CreatedAt
            FROM dbo.SqlClientQuickstart
            WHERE Id = @id;
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@id", SqlDbType.Int).Value = id;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        return await reader.ReadAsync(cancellationToken)
            ? new Message(
                reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2))
            : null;
    }
}

Exécuter l’application

Démarrez l’application sur un port fixe :

dotnet run --urls http://localhost:5000

Au démarrage, l’application crée la table si elle n’existe pas. Lorsque l’application est prête, la sortie inclut ces lignes :

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Si l’application ne peut pas accéder à la base de données, elle s’arrête au démarrage avec un SqlException. Pour connaître les causes courantes, voir Résolution des problèmes.

Appeler l’API

Laissez l’application tourner et ouvrez un second terminal. Ajoutez un message avec une requête POST, puis lisez-le par ID avec une requête GET. Si la table contient déjà des lignes, comme celles du quickstart de la console, remplacez 1 dans la requête GET par le id renvoyé par votre requête POST.

Pour PowerShell :

Invoke-RestMethod -Method Post -Uri http://localhost:5000/messages -ContentType application/json -Body (@{ text = 'Hello from ASP.NET Core' } | ConvertTo-Json)
Invoke-RestMethod http://localhost:5000/messages/1

PowerShell formate chaque réponse JSON sous forme de tableau. La première ligne correspond à 201 Created la réponse à la requête POST, et la seconde ligne est la réponse GET :

id text                    createdAt
-- ----                    ---------
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00

Windows PowerShell 5.1 affiche createdAt comme la chaîne renvoyée par l’API. PowerShell 7 la convertit en date à l’heure locale, comme 10/20/2026 7:04:43 PM.

Dans Windows PowerShell, curl c'est un alias pour Invoke-WebRequest, qui n'accepte pas les options de curl. Utilisez les commandes PowerShell, ou lancez curl.exe depuis l’invite de commandes.

Pour l’invite de commandes :

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d "{\"text\":\"Hello from ASP.NET Core\"}"
curl http://localhost:5000/messages/1

Command Prompt ne traite pas les guillemets simples comme des caractères de guillemet, donc le corps JSON utilise des guillemets doubles échappés avec des barres obliques inverses. Chaque commande imprime la réponse JSON :

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}

Pour Bash :

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d '{"text":"Hello from ASP.NET Core"}'
curl http://localhost:5000/messages/1

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}

Vos identifiants et les horodatages diffèrent. Si vous avez lancé le guide de démarrage rapide de la console en premier, les identifiants continuent à partir de ses lignes. Une demande d’un identifiant qui n’existe pas renvoie 404 Not Found. Un message vide renvoie 400 Bad Request.

Appuyez sur Ctrl+C dans le premier terminal pour arrêter l’application.

Fonctionnement du code

  • L’application enregistre MessageStore en tant que singleton. Il ne contient que la chaîne de connexion, qu'il lit une seule fois depuis IConfiguration. Il ne maintient pas la connexion.
  • Chaque méthode crée un SqlConnection, l’ouvre, exécute une commande, puis le libère avec await using. La libération renvoie la connexion physique au pool de connexions, et la requête suivante la réutilise. Le pooling de connexion est activé par défaut, donc vous n’avez pas besoin de le configurer. Pour les options d’ajustement, voir pooling de connexions SQL Server avec Microsoft.Data.SqlClient.
  • ASP.NET Core lie le paramètre CancellationToken à la requête. Si le client se déconnecte, le jeton annule l’ouverture, la commande et la lecture.
  • Les paramètres @message et @id correspondent aux types et tailles de colonnes. L’API valide la longueur du message avant d’envoyer la valeur à la base de données.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt renvoie la ligne insérée, incluant l’ID généré par le serveur et l’horodatage, sans seconde requête.
  • Dans d’autres environnements, ASP.NET Core lit la même ConnectionStrings:Quickstart clé à partir de variables d’environnement, telles que ConnectionStrings__Quickstart, ou d’un autre fournisseur de configuration, comme Azure Key Vault.

Troubleshoot

Erreur ou symptôme Que vérifier Plus d’informations
Set the ConnectionStrings:Quickstart configuration value. L'application n'a pas trouvé la chaîne de connexion. Exécutez dotnet user-secrets list dans le dossier projet et vérifiez que l’application tourne dans l’environnement Development . Stockage sécurisé des secrets d’application dans le développement dans ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' Au démarrage 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
SqlException Au démarrage L’application ne pouvait ni se connecter ni créer la table. Le numéro d’erreur identifie la cause, comme 18456 pour une connexion échouée. Résolution des problèmes dans le guide de démarrage rapide de la console
415 Unsupported Media Type La requête ne définit pas Content-Type: application/json. Informations de référence rapides sur les API minimales
Cannot bind parameter 'Headers' Vous avez exécuté la commande curl dans Windows PowerShell, où curl exécute Invoke-WebRequest. Utilisez les commandes PowerShell dans Appeler l’API. Invoke-RestMethod
''' is an invalid start of a value Vous avez lancé la commande Bash curl dans l’invite de commande, qui envoie les guillemets simples dans le corps. Utilisez les commandes de l’Invite de commandes dans Appeler l’API. Appeler l’API

Nettoyer les ressources

Supprimez la table à l’aide de n’importe quel outil de requête :

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Retirez la chaîne de connexion stockée. Depuis le dossier du projet, exécutez :

dotnet user-secrets clear

Ensuite, supprime le dossier du projet. Depuis le dossier parent, exécutez la commande suivante dans PowerShell :

Remove-Item -Recurse -Force SqlClientWebQuickstart

Pour Bash :

rm -rf SqlClientWebQuickstart

Étapes suivantes

  • Dernière mise à jour :