Use a Microsoft. Data.SqlClient em um aplicativo .NET

Neste quickstart, você cria um aplicativo de console .NET que:

• Lê sua cadeia de conexão do ambiente em vez do código-fonte.
• Abre uma conexão de forma assíncrona.
• Cria uma tabela se ela não existir.
• Insere uma linha com um comando parametrizado.
• Lê linhas com uma consulta parametrizada.
• Trata erros de SQL e de cancelamento.

O exemplo usa a Microsoft. Data.SqlClient 7.0.3, a versão estável atual.

Prerequisites

Você precisa do SDK .NET 10 ou de um SDK .NET compatível posteriormente.

Criar um banco de dados SQL

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

Banco de Dados SQL do Azure

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

Banco de dados SQL no Fabric

Carregar dados de exemplo do AdventureWorks no banco de dados SQL no Microsoft Fabric

Microsoft SQL Server

Instale o SQL Server pelo Assistente de Instalação

Bancos de dados de exemplo do AdventureWorks

Contêiner SQL Server

Crie um contêiner SQL Server no Docker

Crie um contêiner SQL Server com sqlcmd

Crie um contêiner SQL Server com a extensão MSSQL para VS Code

O quickstart cria sua própria tabela, então dados de exemplo não são necessários. 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 endpoint 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.

Criar o projeto

Execute estes comandos:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.0.3
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.0.3

O pacote de extensão fornece modos de autenticação do Microsoft Entra ID fornecidos pelo driver. Um aplicativo que usa apenas autenticação integrada ao Windows ou autenticação SQL pode omitir Microsoft.Data.SqlClient.Extensions.Azure.

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.

Fabric SQL ou SQL do Azure com autenticação sem senha

Faça login com uma identidade no Microsoft Entra ID que tenha acesso ao banco de datos. 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 item de banco de dados SQL no Fabric ou do Banco de Dados SQL do Azure. 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 uma aplicação hospedada no Azure que se conecta ao SQL do Azure, conceda à identidade gerenciada acesso ao banco de dados e, em seguida, use Authentication=Active Directory Managed Identity. Para outras opções do Microsoft Entra ID, veja autenticação do Microsoft Entra ID.

SQL Server sobre TCP

Use o servidor, porta, banco de dados e login do seu SQL Server existente ou do guia de configuração que você seguiu. O exemplo a seguir de autenticação SQL é para um container de desenvolvimento local. 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.

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

Adicionar o código do aplicativo

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

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

    int insertedId;
    using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        insertCommand.Parameters.Add(
            new SqlParameter("@message", SqlDbType.NVarChar, 200)
            {
                Value = "Hello from Microsoft.Data.SqlClient"
            });

        object? result =
            await insertCommand.ExecuteScalarAsync(cancellation.Token);
        insertedId = Convert.ToInt32(result);
    }

    const string querySql = """
        SELECT Id, Message, CreatedAt
        FROM dbo.SqlClientQuickstart
        WHERE Id = @id
        ORDER BY Id;
        """;

    using var queryCommand =
        new SqlCommand(querySql, connection) { CommandTimeout = 30 };
    queryCommand.Parameters.Add(
        new SqlParameter("@id", SqlDbType.Int) { Value = insertedId });

    await using SqlDataReader reader =
        await queryCommand.ExecuteReaderAsync(cancellation.Token);

    while (await reader.ReadAsync(cancellation.Token))
    {
        Console.WriteLine(
            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
            $"at {reader.GetDateTimeOffset(2):O}");
    }

    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);
    return 3;
}

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 a sintaxe dos comandos e ajuda o SQL Server a reutilizar planos de consulta.

await using elimina o leitor e a conexão mesmo quando ocorre uma exceção. Descartar a conexão retorna sua conexão física ao pool de conexões, em vez de manter uma conexão aberta durante toda a vida útil da aplicação.

Executar o aplicativo

Execute o aplicativo:

dotnet run

A aplicação imprime a linha que inseriu:

1: Hello from Microsoft.Data.SqlClient at <timestamp>

O valor de identidade e a marca temporal variam em cada banco de dados.

Se a conexão falhar, use o número de erro SQL e o ID de conexão do cliente da saída de erro. Verifique os nomes dos servidores e bancos de dados, acesso à rede, permissões do banco de dados, configuração de autenticação e configuração de certificados. Não adicione TrustServerCertificate=true a uma conexão do SQL do Azure ou de produção como uma correção genérica de conexão.

Use o padrão em uma aplicação

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

• Carregue as informações de conexão pelo sistema de configuração da aplicação.
• Abra uma conexão para uma breve unidade de trabalho e, em seguida, descarte-a.
• Passe um CancellationToken nas chamadas de abertura, comando e 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 

• Escolha e construa uma cadeia de conexão.
• Configure o comportamento da conexão.
• Gerencie o ciclo de vida da conexão.
• Use o pool de conexões do SQL Server.
• Configurar lógica de repetição.
• Use comandos e parâmetros.