Avvio rapido: Usa Microsoft. Data.SqlClient in un'app ASP.NET Core

In questo quickstart, costruisci un'API ASP.NET Core minimal con Microsoft. Data.SqlClient 7.1.1.

Si parte da una cartella vuota, dall'SDK .NET e da un database SQL Server o Azure SQL a cui puoi accedere dal computer. Concludi con un'API web che aggiunge un messaggio a una tabella e lo legge per ID.

Durante il processo, l'app:

  • Legge la sua stringa di connessione dalla configurazione ASP.NET Core. Per lo sviluppo locale, il valore deriva dai segreti utente, quindi resta fuori dalla cartella del progetto.
  • Registra una data class con dependency injection.
  • Apre e chiude una connessione per ogni richiesta, permettendo al pool di connessione predefinito di riutilizzare le connessioni fisiche.
  • Passa il CancellationToken della richiesta a ogni chiamata al database.

L'app utilizza la stessa dbo.SqlClientQuickstart tabella usata in Quickstart: Connetti e consulta con Microsoft.Data.SqlClient. Puoi prima fare una delle due guide rapide.

Prerequisiti

L'attuale ASP.NET Core gira su .NET, non su .NET Framework. Per utilizzare il driver con .NET Framework, vedi progetti .NET Framework.

L'identità del database necessita del permesso per connettersi e creare, inserire e selezionare da una tabella.

Creare il progetto

In una cartella vuota, esegui questi comandi:

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 Aggiunge UserSecretsId al file del progetto. ASP.NET Core carica i segreti utente solo quando l'app viene eseguita nell'ambiente Development, che è l'impostazione predefinita per dotnet run.

Il pacchetto di estensione fornisce le modalità di autenticazione Microsoft Entra del driver. Se la tua app usa solo l'autenticazione SQL, puoi omettere Microsoft.Data.SqlClient.Extensions.Azure. Quando usi entrambi i pacchetti, mantieni le loro versioni uguali.

Configura la connessione

Memorizza la stringa di connessione come ConnectionStrings:Quickstart nei segreti utente. I segreti utente sono memorizzati nel tuo profilo utente, non nella cartella del progetto, quindi non sono sottoposti al controllo del codice sorgente. Non inserire una password o una stringa di connessione di produzione in appsettings.json.

Scegli uno di questi punti di partenza e sostituisci i segnaposto. I comandi dotnet user-secrets set usano virgolette singole per PowerShell e Bash. Nel Prompt dei Comandi, usa le virgolette doppie, perché il Prompt memorizza gli apici singoli come parte della chiave e del valore.

Azure SQL con Microsoft Entra ID

Accedi con un'identità Microsoft Entra che abbia accesso al database. Per lo sviluppo locale, usa uno strumento per sviluppatori come interfaccia della riga di comando di Azure:

az login

Poi memorizza la stringa di connessione. Copia i nomi esatti dei server e del database dal database Azure SQL. La stessa stringa di connessione funziona per il database SQL in Microsoft Fabric quando usi i nomi server e database dall'elemento SQL database, come descritto nel quickstart della console.

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

Questa stringa di connessione non contiene un segreto. Active Directory Default utilizza localmente il tuo accesso sviluppatore. Quando distribuisci su Servizio app di Azure o App contenitore di Azure, concedi all'identità gestita dell'app l'accesso al database, cambia il valore in Authentication=Active Directory Managed Identity e impostalo nella configurazione dell'host come ConnectionStrings__Quickstart. Per altre opzioni, vedi autenticazione Microsoft Entra con Microsoft.Data.SqlClient.

Local SQL Server con autenticazione SQL

Memorizza la stringa di connessione per un'istanza di sviluppo locale che non ha un certificato affidabile. Usa virgolette singole per impedire che PowerShell e Bash espandano un carattere $ nella password.

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 Salta la validazione dei certificati del server. Usalo solo con un'istanza di sviluppo locale. Per istanze SQL Server condivise o di produzione, installa un certificato considerato attendibile dal client e rimuovi TrustServerCertificate=true. Per altre informazioni, vedere Crittografia e convalida dei certificati in Microsoft.Data.SqlClient.

Aggiungi il codice

Sostituire il contenuto di Program.cs con questo codice:

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

Eseguire l'app

Avvia l'app su una porta fissa:

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

All'avvio, l'app crea la tabella se non esiste. Quando l'app è pronta, l'output include queste righe:

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

Se l'app non riesce a raggiungere il database, si ferma all'avvio con un SqlException. Per le cause comuni, vedi Troubleshoot.

Chiamare l'API

Lascia l'app aperta e apri un secondo terminale. Aggiungi un messaggio con una richiesta POST, e poi leggilo per ID con una richiesta GET. Se la tabella ha già righe, come quella del quickstart della console, sostituisci 1 nella richiesta GET con il valore id restituito dalla tua richiesta POST.

Per 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 formatta ogni risposta JSON come una tabella. La prima riga è la 201 Created risposta alla richiesta POST, e la seconda riga è la risposta 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 mostra createdAt come stringa restituita dall'API. PowerShell 7 lo converte in una data e ora locali, come 10/20/2026 7:04:43 PM.

In Windows PowerShell, curl è un alias per Invoke-WebRequest, che non accetta le opzioni di curl. Usa i comandi PowerShell o esegui curl.exe dal prompt dei comandi.

Per il Prompt dei comandi:

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

Il prompt dei comandi non tratta le virgolette singole come caratteri di virgolette, quindi il corpo JSON usa virgolette doppie con escape tramite barre rovesciate. Ogni comando stampa la risposta 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"}

Per 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"}

I tuoi ID e i tuoi timestamp differiscono. Se hai eseguito prima il quickstart della console, gli ID continuano dalle sue righe. Una richiesta di un ID inesistente restituisce 404 Not Found. Un messaggio vuoto restituisce 400 Bad Request.

Premi Ctrl+C nel primo terminale per fermare l'app.

Funzionamento del codice

  • L'app viene MessageStore registrata come singleton. Contiene solo la stringa di connessione, che legge da IConfiguration una sola volta. Non mantiene una connessione.
  • Ogni metodo crea un SqlConnection, lo apre, esegue un comando e lo rilascia con await using. La chiusura restituisce la connessione fisica al pool di connessioni e la richiesta successiva la riutilizza. Il pool di connessione è attivo di default, quindi non serve configurarlo. Per le opzioni di regolazione, vedi pooling delle connessioni di SQL Server con Microsoft.Data.SqlClient.
  • ASP.NET Core associa il CancellationToken parametro alla richiesta. Se il client si disconnette, l'apertura, il comando e la lettura vengono annullati dal token.
  • I parametri @message e @id corrispondono ai tipi e alle dimensioni delle colonne. L'API valida la lunghezza del messaggio prima di inviare il valore al database.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt restituisce la riga inserita, inclusi l'ID generato dal server e il timestamp, senza una seconda interrogazione.
  • In altri ambienti, ASP.NET Core legge la stessa ConnectionStrings:Quickstart chiave da variabili di ambiente, come ConnectionStrings__Quickstart, o da un altro provider di configurazione, come Azure Key Vault.

Troubleshoot

Errore o sintomo Controlli da eseguire Ulteriori informazioni
Set the ConnectionStrings:Quickstart configuration value. L'app non ha trovato la stringa di connessione. Esegui dotnet user-secrets list nella cartella del progetto e controlla che l'app giri nell'ambiente Development . Archiviazione sicura dei segreti dell'app in fase di sviluppo in ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' All'avvio La stringa di connessione utilizza una modalità di autenticazione Active Directory, ma il progetto non fa riferimento a Microsoft.Data.SqlClient.Extensions.Azure. Aggiungi il package con la stessa versione di Microsoft.Data.SqlClient. L'autenticazione Microsoft Entra passa a un pacchetto di estensione nella 7.0
SqlException All'avvio L'app non riusciva a connettersi né creare la tabella. Il numero di errore identifica la causa, ad esempio 18456 per un accesso fallito. Risoluzione dei problemi nella guida rapida della console
415 Unsupported Media Type La richiesta non imposta Content-Type: application/json. Informazioni di riferimento rapido sulle API minime
Cannot bind parameter 'Headers' Hai eseguito il comando curl in PowerShell di Windows, dove curl esegue Invoke-WebRequest. Usa i comandi PowerShell in Chiama l'API. Invoke-RestMethod
''' is an invalid start of a value Hai eseguito il comando Bash curl nel Prompt dei Comandi, che invia le virgolette singole come parte del corpo. Usa i comandi del prompt dei comandi in Chiama l'API. Chiama l'API

Pulire le risorse

Esegui il drop della tabella utilizzando uno qualsiasi degli strumenti di query:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Rimuovi la stringa di connessione memorizzata. Dalla cartella del progetto, esegui:

dotnet user-secrets clear

Poi elimina la cartella del progetto. Dalla cartella genitore, esegui il seguente comando in PowerShell:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Per Bash:

rm -rf SqlClientWebQuickstart

Passaggi successivi

  • Ultimo aggiornamento: