Início Rápido: Conecte-se e consulte com o Microsoft.Data.SqlClient

Neste quickstart, você constrói um aplicativo de console .NET 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 um aplicativo de console que cria uma tabela, insere duas linhas com parâmetros e os lê de volta.

No caminho, o app:

Lê sua cadeia de conexão de uma variável de ambiente em vez do código-fonte.
Abre uma conexão de forma assíncrona.
Usa parâmetros para cada valor que envia ao banco de dados.
Gerencia erros de SQL e cancelamento.

Para construir o mesmo acesso a dados em uma API web, veja Quickstart: Use Microsoft. Data.SqlClient em um aplicativo ASP.NET Core. Ele usa a mesma tabela.

Prerequisites

O SDK .NET 10 ou um SDK do .NET posterior com suporte. O SDK roda no Windows, Linux e macOS. O SDK também constrói a versão do .NET Framework do exemplo, que roda apenas no Windows e precisa do .NET Framework 4.8.1. Use a versão .NET para novos desenvolvimentos.
Um editor de código. Você pode usar Visual Studio, Visual Studio Code ou qualquer editor junto com a linha de comando .NET. Este artigo utiliza a .NET CLI.
Um banco de dados ao qual você pode se conectar. Se você não tiver um, crie um usando as seguintes opções.

Criar um banco de dados SQL

Crie ou conecte-se a um banco de dados SQL em uma das seguintes plataformas:

Criar um banco de dados SQL em minutos usando o portal do Azure

Permissões de banco de dados

O app cria sua própria tabela, então você não precisa de dados de exemplo. A identidade do banco de dados precisa de permissão para se conectar, criar, inserir e selecionar de uma tabela.

Para banco de dados SQL no Microsoft Fabric, copie os nomes do servidor e do banco de dados no item de banco de dados SQL. Não use o ponto de extremidade de análise SQL. A identidade precisa da permissão de Leitura do item, que pode ser concedida por uma função no workspace ou por uma permissão de item. Para mais informações, veja Autenticação em banco de dados SQL. Autenticação SQL não é suportada.

Para o Banco de Dados SQL do Azure, configure a autenticação e o acesso ao banco de dados do Microsoft Entra ID.

Em uma pasta vazia, execute estes comandos:

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

O template do console não oferece alvos para o .NET Framework. Em uma pasta vazia, crie o projeto:

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

Substitua o conteúdo de SqlClientQuickstart.csproj por este arquivo de projeto:

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

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

</Project>

Depois, adicione os pacotes:

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

O pacote de extensão fornece os modos de autenticação Microsoft Entra do driver, como Active Directory Default. Se seu aplicativo usar apenas autenticação SQL ou autenticação integrada ao Windows, você pode omitir Microsoft.Data.SqlClient.Extensions.Azure. Quando você usar os dois pacotes, mantenha as versões iguais. Para outras opções de instalação, veja Instalar, atualizar e implantar Microsoft.Data.SqlClient.

Configurar a conexão

Defina a SQL_CONNECTION_STRING variável de ambiente para seu banco de dados. Não coloque uma senha, um token de acesso ou uma cadeia de conexão de produção no código-fonte.

Escolha um destes pontos de partida e substitua os espaços reservados.

SQL do Azure ou banco de dados SQL no Fabric 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

Copie os nomes exatos do servidor e do banco de dados do banco de dados SQL do Azure ou do item do banco de dados SQL no Fabric. Para PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Para o Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Para um aplicativo hospedado no Azure, conceda à sua identidade gerenciada acesso ao banco de dados e use Authentication=Active Directory Managed Identity. Para outras opções, veja autenticação Microsoft Entra com Microsoft. Data.SqlClient.

SQL Server com autenticação SQL

Use o servidor, porta, banco de dados e login da sua instância do SQL Server. O exemplo a seguir é para uma instância de desenvolvimento local que não possui um certificado confiável. Para PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;User ID=<user-id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Para o 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 ignora a validação do certificado do servidor. Use isso apenas com uma instância de desenvolvimento local que não tenha um certificado confiável. Para instâncias compartilhadas ou de produção de SQL Server, instale um certificado em que o cliente confie, use o nome do servidor nesse certificado e remova TrustServerCertificate=true. Para obter mais informações, consulte Criptografia e validação de certificado no Microsoft.Data.SqlClient.

Se seu ambiente suportar autenticação integrada ao Windows ou Kerberos, substitua User ID e Password por Integrated Security=true. Para requisitos de configuração, veja SQL Server e autenticação do Windows.

Adicionar o código

.NET
.NET Framework

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

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

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

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

Executar o aplicativo

Execute o aplicativo:

dotnet run

Na primeira vez que você executa o app, a tabela está vazia e a saída é a seguinte:

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)

Suas marcas de tempo diferem. Cada corrida posterior adiciona mais duas linhas, então os IDs continuam a partir da última execução.

Se o app não conseguir se conectar, ele imprime o número de erro SQL, o ID da conexão do cliente, a mensagem de erro e a mensagem de exceção interna, e então sai com o código 3. Para erros comuns, veja Solução de Problemas.

Como o código funciona

OpenAsync, ExecuteNonQueryAsync, ExecuteScalarAsync, ExecuteReaderAsync, e ReadAsync todos recebem o mesmo CancellationToken. Pressione Ctrl+C para cancelar o trabalho em andamento.
O comando insert é criado uma vez e executado uma vez para cada mensagem. Apenas o valor do parâmetro muda.
Os tipos e tamanhos dos parâmetros correspondem às colunas da tabela. Os parâmetros enviam valores separadamente do texto SQL, o que impede que esses valores alterem o comando e ajuda o SQL Server a reutilizar planos de consulta.
OUTPUT INSERTED.Id retorna o novo ID gerado, então ExecuteScalarAsync retorna o ID sem uma segunda consulta.
await using descarta os comandos, o leitor e a conexão, mesmo quando ocorre uma exceção. Descartar a conexão a retorna ao pool de conexões. A versão do .NET Framework usa blocos using, porque esses tipos não implementam IAsyncDisposable no .NET Framework.
SqlException.Number identifica o erro e ClientConnectionId permite que você compare uma falha do cliente com logs do lado do servidor. Para falhas de conexão no Linux e macOS, a causa geralmente está apenas em InnerException, como uma falha de validação de certificado atrás do genérico error: 35 - An internal exception was caught.

Troubleshoot

Erro ou sintoma	O que verificar	Mais informações
`The certificate chain was issued by an authority that is not trusted`no Windows. No Linux e macOS, `error: 35 - An internal exception was caught`, seguido da exceção interna `Certificate failed chain validation` com `UntrustedRoot`.	O certificado do servidor não é considerado confiável pelo cliente, ou o nome do servidor na cadeia de conexão não corresponde ao certificado. Instale um certificado confiável. Use `TrustServerCertificate=true` apenas com uma instância de desenvolvimento local.	Criptografia e validação de certificados na Microsoft. Data.SqlClient
`SQL error 18456` com `Login failed for user`	O nome de usuário, senha ou nome do banco de dados está errado, ou o login não tem acesso ao banco de dados. Para o Microsoft Entra ID, verifique se a identidade foi adicionada como usuário de banco de dados.	Guia de solução de problemas do SqlClient
`A network-related or instance-specific error occurred` com `error: 26`, `error: 40`, ou `The wait operation timed out`. No Linux e macOS, um timeout mostra `SQL error 258` com `error: 35`, seguido da exceção interna `The connection attempt timed out`.	O nome do servidor ou a porta está errado, o servidor não aceita conexões TCP remotas ou um firewall bloqueia a porta. Para SQL do Azure, verifique as regras do firewall do servidor.	Guia de solução de problemas do SqlClient
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	A cadeia de conexão usa um `Active Directory` modo de autenticação, 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
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	O projeto não faz referência ao `Microsoft.Data.SqlClient` pacote. Execute o comando `dotnet add package` na pasta que contém o arquivo do projeto.	Instalar, atualizar e implantar a Microsoft. Data.SqlClient
Restaurar relatórios `NU1902` ou `NU1903` para um pacote transitivo	Um pacote do qual o driver depende possui um aviso de segurança publicado.	Ações quando pacotes com vulnerabilidades conhecidas são reportados

Limpar os recursos

A tabela permanece no seu banco de dados depois que o app for fechado. Se você não pretende continuar com o quickstart do ASP.NET Core, que usa a mesma tabela, exclua-a com qualquer ferramenta de consulta:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Depois, apague a pasta do projeto. Na pasta principal, no PowerShell:

Remove-Item -Recurse -Force SqlClientQuickstart

Para o Bash:

rm -rf SqlClientQuickstart

Limpe a variável ambiente para que a cadeia de conexão não fique na sua sessão de shell. Para PowerShell, execute Remove-Item Env:\SQL_CONNECTION_STRING. Para Bash, execute unset SQL_CONNECTION_STRING.

Use o padrão em uma aplicação

Mantenha esses limites ao mover a amostra para uma API, serviço, aplicativo desktop ou worker em segundo plano:

Carregue as informações de conexão pelo sistema de configuração do app.
Abra uma conexão para uma breve unidade de trabalho e, em seguida, descarte-a.
Passe um CancellationToken nas chamadas de abertura, de comando e de leitor.
Defina tempos de espera de comando com base na operação.
Use parâmetros para cada valor que vem de fora da instrução SQL.
Logar SqlException.Number e ClientConnectionId sem registrar credenciais ou tokens de acesso.
Adicione novas tentativas apenas para falhas transitórias e apenas quando for seguro repetir a operação.

Próximas Etapas

Comentários

Esta página foi útil?

Última atualização em 2026-10-23

Início Rápido: Conecte-se e consulte com o Microsoft.Data.SqlClient

Prerequisites

Criar um banco de dados SQL

Permissões de banco de dados

Criar o projeto

Configurar a conexão

SQL do Azure ou banco de dados SQL no Fabric com Microsoft Entra ID

SQL Server com autenticação SQL

Adicionar o código

Executar o aplicativo

Como o código funciona

Troubleshoot

Limpar os recursos

Use o padrão em uma aplicação

Próximas Etapas

Comentários

Recursos adicionais