Início rápido: Use Microsoft.Data.SqlClient numa aplicação ASP.NET Core

Neste quickstart, constróis uma API ASP.NET Core minimalista com o Microsoft.Data.SqlClient 7.1.1.

Começas com uma pasta vazia, o SDK .NET e uma base de dados SQL Server ou SQL do Azure à qual podes aceder a partir do teu computador. Terminas com uma API web que adiciona uma mensagem a uma tabela e lê-a por ID.

Ao longo do caminho, a aplicação:

  • Lê a sua cadeia de ligação da configuração ASP.NET Core. Para desenvolvimento local, o valor vem dos segredos de utilizador, por isso fica fora da pasta do projeto.
  • Registra uma classe de dados com injeção de dependências.
  • Abre e fecha uma ligação para cada pedido, o que permite ao pool de conexões predefinido reutilizar ligações físicas.
  • Passa o CancellationToken do pedido em cada chamada à base de dados.

A aplicação usa a mesma tabela dbo.SqlClientQuickstart que Quickstart: Connect and query with Microsoft.Data.SqlClient. Podes fazer primeiro qualquer um dos inícios rápidos.

Prerequisites

O ASP.NET Core atual corre em .NET, não no .NET Framework. Para usar o controlador do .NET Framework, consulte .NET Framework projects.

A identidade da base de dados precisa de permissão para se ligar e criar, inserir e selecionar de uma tabela.

Criar o projeto

Numa pasta vazia, execute estes comandos:

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 Adiciona A UserSecretsId ao ficheiro do projeto. O ASP.NET Core carrega segredos de utilizador apenas quando a aplicação corre no Development ambiente, que é o padrão para dotnet run.

O pacote de extensão fornece os modos de autenticação Microsoft Entra do driver. Se a sua aplicação usar apenas autenticação SQL, pode omitir Microsoft.Data.SqlClient.Extensions.Azure. Quando usares ambos os pacotes, mantém as versões iguais.

Configurar a ligação

Armazene a cadeia de ligação como ConnectionStrings:Quickstart nos secretos de utilizador. Os segredos de utilizador estão armazenados no seu perfil de utilizador, não na pasta do projeto, por isso não são submetidos ao controlo de versão. Não coloque uma palavra-passe ou cadeia de ligação de produção em appsettings.json.

Escolhe um destes pontos de partida e substitui os marcadores de lugar. Os dotnet user-secrets set comandos usam aspas simples para PowerShell e Bash. No Prompt de Comandos, use aspas duplas, porque o Prompt armazena aspas simples como parte da chave e do valor.

SQL do Azure com Microsoft Entra ID

Inicie sessão com uma identidade Microsoft Entra que tenha acesso à base de dados. Para desenvolvimento local, utilize uma ferramenta de desenvolvimento como a CLI do Azure:

az login

Depois guarda a cadeia de ligação. Copie os nomes exatos do servidor e da base de dados da base de dados SQL do Azure. A mesma cadeia de ligação funciona para a base de dados SQL no Microsoft Fabric quando utiliza os nomes do servidor e da base de dados do item da base de dados SQL, como descrito no quickstart da consola.

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

Esta cadeia de ligação não contém um segredo. Active Directory Default utiliza localmente o teu início de sessão de programador. Quando implementa para Serviço de Aplicações do Azure ou Azure Container Apps, concede à identidade gerida da app acesso à base de dados, altera o valor para Authentication=Active Directory Managed Identity e define-o na configuração do anfitrião como ConnectionStrings__Quickstart. Para outras opções, veja autenticação Microsoft Entra com Microsoft. Data.SqlClient.

Local SQL Server com autenticação SQL

Armazene a cadeia de ligação para uma instância de desenvolvimento local que não tenha um certificado de confiança. Utilize aspas simples para evitar que o PowerShell e o Bash expandam um caráter $ na palavra-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 ignora a validação do certificado do servidor. Usa-o apenas com uma instância de desenvolvimento local. Para instâncias partilhadas ou de produção de SQL Server, instale um certificado em que o cliente confie e remova TrustServerCertificate=true. Para obter mais informações, consulte Criptografia e validação de certificado em Microsoft.Data.SqlClient.

Adicionar o código

Substitua o conteúdo de Program.cs por este código:

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

Executar o aplicativo

Inicia a aplicação numa porta fixa:

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

No arranque, a aplicação cria a tabela caso esta não exista. Quando a aplicação está pronta, a saída inclui estas linhas:

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 a aplicação não conseguir aceder à base de dados, para no arranque com um SqlException. Para causas comuns, veja Resolução de problemas.

Invoque a API

Deixe a aplicação em execução e abra um segundo terminal. Adicione uma mensagem com um pedido POST e depois leia-a por ID com um pedido GET. Se a tabela já tiver linhas, como no quickstart da consola, substitua 1 no pedido GET pelo id que o seu pedido POST devolve.

Para o 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

O PowerShell formata cada resposta JSON como uma tabela. A primeira linha é a 201 Created resposta ao pedido POST, e a segunda linha é a resposta 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

O PowerShell 5.1 do Windows aparece createdAt como a cadeia que a API devolve. O PowerShell 7 converte-o para uma data e hora local, como 10/20/2026 7:04:43 PM.

No PowerShell do Windows, curl é um alias para Invoke-WebRequest, que não aceita as opções de curl. Usa os comandos do PowerShell ou executa curl.exe a partir do Prompt de Comandos.

Para o Prompt de Comando:

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

O Prompt de Comando não trata aspas simples como caracteres de aspas, por isso o corpo JSON usa aspas duplas escapadas com barras invertidas. Cada comando imprime a resposta 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"}

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

Os teus IDs e marcas temporais diferem. Se executares o quickstart da consola primeiro, os IDs continuam a partir das suas linhas. Um pedido de um ID que não existe devolve 404 Not Found. Uma mensagem vazia devolve 400 Bad Request.

Pressiona Ctrl+C no primeiro terminal para parar a aplicação.

Como funciona o código

  • A aplicação regista MessageStore como singleton. Isto contém apenas a cadeia de ligação, da qual lê IConfiguration uma vez. Não mantém a ligação.
  • Cada método cria um SqlConnection, abre-o, executa um comando e descarta-o com await using. A libertação devolve a ligação física ao pool de ligações, e o pedido seguinte reutiliza-a. O pooling de ligações está ativado por defeito, por isso não precisa de o configurar. Para opções de ajuste, veja SQL Server connection pooling com Microsoft.Data.SqlClient.
  • O ASP.NET Core associa o CancellationToken parâmetro ao pedido. Se o cliente se desconectar, o token cancela o open, o comando e o read.
  • Os parâmetros @message e @id correspondem aos tipos e tamanhos das colunas. A API valida o comprimento da mensagem antes de a API enviar o valor para a base de dados.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt devolve a linha inserida, incluindo o ID gerado pelo servidor e o carimbo temporal, sem uma segunda consulta.
  • Noutros ambientes, o ASP.NET Core lê a mesma ConnectionStrings:Quickstart chave a partir de variáveis de ambiente, como ConnectionStrings__Quickstart, ou de outro fornecedor de configuração, como o Azure Key Vault.

Troubleshoot

Erro ou sintoma O que deve verificar Mais informações
Set the ConnectionStrings:Quickstart configuration value. A aplicação não encontrou a cadeia de ligação. Executa dotnet user-secrets list na pasta do projeto e verifica se a aplicação corre no Development ambiente. Armazenamento seguro de segredos de aplicações em desenvolvimento em ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' na inicialização A cadeia de ligação usa um modo de autenticação Active Directory, mas o projeto não faz referência a Microsoft.Data.SqlClient.Extensions.Azure. Adicione o pacote com a mesma versão como Microsoft.Data.SqlClient. A autenticação Microsoft Entra passa para um pacote de extensão na 7.0
SqlException no arranque A aplicação não conseguia estabelecer ligação nem criar a tabela. O número de erro identifica a causa, como 18456 para falha no início de sessão. Resolução de problemas no guia de início rápido da consola
415 Unsupported Media Type O pedido não define Content-Type: application/json. Referência rápida de APIs mínimas
Cannot bind parameter 'Headers' Executaste o comando curl no PowerShell do Windows, em que curl executa Invoke-WebRequest. Utilize os comandos PowerShell em Chamar a API. Invoke-RestMethod
''' is an invalid start of a value Executaste o comando Bash curl no Prompt de Comandos, que envia as aspas simples como parte do corpo do pedido. Utilize os comandos do Prompt de Comando em Chamar a API. Ligue para a API

Limpeza de recursos

Elimine a tabela com qualquer ferramenta de consulta:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Remova a cadeia de ligação armazenada. Da pasta do projeto, execute:

dotnet user-secrets clear

Depois apaga a pasta do projeto. A partir da pasta principal, execute o seguinte comando no PowerShell:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Para Bash:

rm -rf SqlClientWebQuickstart

Passos seguintes

  • Última atualização a