Início rápido: Use o Microsoft.Data.SqlClient em um aplicativo ASP.NET Core

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

Você começa com uma pasta vazia, o SDK .NET e um banco de dados SQL Server ou SQL do Azure que pode acessar do seu computador. Você termina com uma API web que adiciona uma mensagem a uma tabela e a lê por ID.

No caminho, o app:

  • Lê sua cadeia de conexão da configuração ASP.NET Core. Para desenvolvimento local, o valor vem dos segredos do usuário, então fica fora da pasta do seu projeto.
  • Registra uma classe de dados com injeção de dependência.
  • Abre e descarta uma conexão para cada requisição, o que permite que o pool padrão de conexões reutilize conexões físicas.
  • Encaminha CancellationToken da solicitação para todas as chamadas de banco de dados.

O aplicativo usa a mesma dbo.SqlClientQuickstart tabela do Quickstart: Conectar e consultar com Microsoft.Data.SqlClient. Você pode fazer qualquer um dos guias de início rápido primeiro.

Prerequisites

O ASP.NET Core atual roda em .NET, não no .NET Framework. Para usar o driver do .NET Framework, veja projetos do .NET Framework.

A identidade do banco de dados precisa de permissão para se conectar, criar, inserir e selecionar de uma tabela.

Criar o projeto

Em uma 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 um(a) UserSecretsId ao arquivo do projeto. ASP.NET Core carrega segredos de usuário apenas quando o app roda 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 seu app usar apenas autenticação SQL, você pode omitir Microsoft.Data.SqlClient.Extensions.Azure. Quando você usar os dois pacotes, mantenha as versões iguais.

Configurar a conexão

Armazene a cadeia de conexão como ConnectionStrings:Quickstart nos segredos de usuário. Os segredos de usuário são armazenados no seu perfil de usuário, não na pasta do projeto, então eles não são confirmados no controle de versão. Não coloque uma senha ou cadeia de conexão de produção em appsettings.json.

Escolha um destes pontos de partida e substitua os espaços reservados. Os dotnet user-secrets set comandos usam aspas simples para PowerShell e Bash. No Prompt de Comando, use aspas duplas, porque o Prompt de Comando armazena aspas simples como parte da chave e do valor.

SQL do Azure com Microsoft Entra ID

Faça login com uma identidade Microsoft Entra que tenha acesso ao banco de dados. Para desenvolvimento local, use uma ferramenta de desenvolvimento como a CLI do Azure:

az login

Depois, armazene a cadeia de conexão. Copie o nome exato do servidor e do banco de dados do SQL do Azure. A mesma cadeia de conexão funciona para banco de dados SQL no Microsoft Fabric quando você usa os nomes do servidor e do banco de dados do item do banco de dados SQL, conforme descrito no quickstart do console.

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

Essa cadeia de conexão não contém um segredo. Active Directory Default usa seu login de desenvolvedor localmente. Quando você implantar no Serviço de Aplicativo do Azure ou no Aplicativos de Contêiner do Azure, conceda à identidade gerenciada do aplicativo acesso ao banco de dados, mude o valor para Authentication=Active Directory Managed Identity e defina-o na configuração do host como ConnectionStrings__Quickstart. Para outras opções, veja autenticação Microsoft Entra com Microsoft. Data.SqlClient.

SQL Server Local com autenticação SQL

Armazene a cadeia de conexão de uma instância de desenvolvimento local que não tenha um certificado confiável. Use aspas simples para evitar que o PowerShell e o Bash expandam um caractere $ na senha.

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. Use apenas com uma instância de desenvolvimento local. Para instâncias compartilhadas 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 no 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

Inicie o app em uma porta fixa:

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

Na inicialização, o app cria a tabela caso ela não exista. Quando o app está pronto, 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 o app não conseguir acessar o banco de dados, ele para na inicialização com um SqlException. Para causas comuns, consulte Solução de problemas.

Chamar a API

Deixe o app aberto e abra um segundo terminal. Adicione uma mensagem com um pedido POST e leia novamente pelo ID com um pedido GET. Se a tabela já tiver linhas, como as do quickstart do console, substitua 1 na solicitação GET pela id que sua requisição POST retorna.

Para 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 string que a API retorna. O PowerShell 7 converte isso para uma data em horário 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. Use os comandos do PowerShell ou execute curl.exe pelo Prompt de Comando.

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, então 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 o 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"}

Seus IDs e carimbos de data/hora diferem. Se você rodou o quickstart do console primeiro, os IDs continuam a partir das linhas dele. Um pedido de identificação que não existe retorna 404 Not Found. Uma mensagem vazia retorna 400 Bad Request.

Pressione Ctrl+C no primeiro terminal para parar o aplicativo.

Como o código funciona

  • O aplicativo registra MessageStore como singleton. Ela contém apenas a cadeia de conexão, da qual lê IConfiguration uma vez. Não mantém a conexão.
  • Cada método cria um SqlConnection, abre, executa um comando e o descarta com await using. Ao descartar, a conexão física retorna ao pool de conexão, e a próxima requisição a reutiliza. O pool de conexão está ativado por padrão, então você não precisa configurá-lo. Para opções de ajuste fino, veja pool de conexões do SQL Server com Microsoft.Data.SqlClient.
  • ASP.NET Core vincula o CancellationToken parâmetro à solicitação. Se o cliente desconectar, o token cancela a abertura, o comando e a leitura.
  • Os parâmetros @message e @id correspondem aos tipos e tamanhos das colunas. A API valida o comprimento da mensagem antes de enviar o valor para o banco de dados.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt retorna a linha inserida, incluindo o ID gerado pelo servidor e o carimbo de data, sem uma segunda consulta.
  • Em outros ambientes, o ASP.NET Core lê a mesma ConnectionStrings:Quickstart chave a partir de variáveis de ambiente, como ConnectionStrings__Quickstart, ou de outro provedor de configuração, como o Azure Key Vault.

Troubleshoot

Erro ou sintoma O que verificar Mais informações
Set the ConnectionStrings:Quickstart configuration value. O app não encontrou a cadeia de conexão. Execute dotnet user-secrets list na pasta do projeto e verifique se o app roda no Development ambiente. Armazenamento seguro de segredos de aplicação durante o desenvolvimento no ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' na inicialização A cadeia de conexã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 de Microsoft.Data.SqlClient. A autenticação Microsoft Entra migra para um pacote de extensão na versão 7.0
SqlException na inicialização O app não conseguia conectar nem criar a tabela. O número de erro identifica a causa, como 18456 para falha no login. Solucionar problemas no guia de início rápido do console
415 Unsupported Media Type A solicitação não define Content-Type: application/json. Referência rápida de APIs mínimas
Cannot bind parameter 'Headers' Você executou o comando curl no PowerShell do Windows, em que curl executa Invoke-WebRequest. Use os comandos do PowerShell em Chamar a API. Invoke-RestMethod
''' is an invalid start of a value Você executou o comando Bash curl no Prompt de Comando, que envia as aspas simples como parte do corpo da requisição. Use os comandos do Prompt de Comando em Chamar a API. Faça uma chamada à API

Limpar os recursos

Exclua a tabela com qualquer ferramenta de consulta:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

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

dotnet user-secrets clear

Depois, apague a pasta do projeto. Na pasta principal, execute o seguinte comando no PowerShell:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Para o Bash:

rm -rf SqlClientWebQuickstart

Próximas Etapas 

  • Última atualização em