Usa a Microsoft. Data.SqlClient numa aplicação .NET

Neste guia de início rápido, vai criar uma aplicação de consola .NET que:

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

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

Pré-requisitos

Precisas do SDK .NET 10 ou de um SDK .NET suportado mais tarde.

Criar um banco de dados SQL

Criar ou ligar-se a uma base de dados SQL numa das seguintes plataformas:

O quickstart cria a sua própria tabela, por isso não são necessários dados de exemplo. A identidade da base de dados precisa de permissão para se ligar e criar, inserir e selecionar de uma tabela.

Para base de dados SQL no Microsoft Fabric, copie os nomes do servidor e da base de dados a partir do item da base de dados SQL. Não utilizes o endpoint de análise de SQL. A identidade precisa da permissão de leitura do item, que pode ser concedida por uma função do espaço de trabalho ou por uma permissão do item. Para mais informações, veja Autenticação na base de dados SQL. A autenticação SQL não é suportada.

Para o Base de Dados SQL do Azure, configure a autenticação do Microsoft Entra ID e o acesso à base de dados.

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 Microsoft Entra ID fornecidos pelo driver. Uma aplicação que utiliza apenas autenticação integrada no Windows ou autenticação SQL pode omitir Microsoft.Data.SqlClient.Extensions.Azure.

Configurar a ligação

Define a SQL_CONNECTION_STRING variável ambiente para a tua base de dados. Não inclua uma palavra-passe, um token de acesso nem uma cadeia de ligação de produção no código-fonte.

Escolhe um destes pontos de partida e substitui os marcadores de lugar.

Fabric SQL ou SQL do Azure com autenticação sem palavra-passe

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

az login

Copie os nomes exatos do servidor e da base de dados a partir do item da base de dados SQL no Fabric ou na base de dados SQL do Azure. Para o PowerShell:

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

Para 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 alojada no Azure que se liga ao SQL do Azure, conceda à sua identidade gerida acesso à base de dados e, em seguida, utilize Authentication=Active Directory Managed Identity. Para outras opções do Microsoft Entra ID, veja autenticação do Microsoft Entra ID.

SQL Server sobre TCP

Usa o servidor, porta, base de dados e login do teu SQL Server existente ou do guia de configuração que seguiste. O seguinte exemplo de autenticação SQL é para um contentor de desenvolvimento local. Para o 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 Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

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

Adicionar o código da aplicação

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 ligação mesmo quando ocorre uma exceção. Eliminar a ligação devolve a sua ligação física ao pool de ligações em vez de manter uma ligação aberta durante toda a vida útil da aplicação.

Execute o aplicativo

Execute a aplicação:

dotnet run

A aplicação imprime a linha que inseriu:

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

O valor de identidade e o carimbo temporal diferem em cada base de dados.

Se a ligação falhar, use o número do erro SQL e o ID de ligação do cliente indicados na saída de erro. Verifique os nomes dos servidores e bases de dados, acesso à rede, permissões à base de dados, configuração da autenticação e configuração do certificado. Não adicione TrustServerCertificate=true a uma ligação ao SQL do Azure ou de produção como uma correção genérica para problemas de ligação.

Use o padrão numa aplicação

Mantenha estes limites quando mover a amostra para uma API, serviço, aplicação de ambiente de trabalho ou trabalhador em segundo plano:

• Carregar a informação de ligação através do sistema de configuração da aplicação.
• Abra uma conexão para uma breve unidade de trabalho e, em seguida, elimine-a.
• Passe um CancellationToken através das chamadas open, command e reader.
• Defina os tempos de espera dos comandos com base na operação.
• Use parâmetros para cada valor que venha de fora da instrução SQL.
• Faça login SqlException.Number e ClientConnectionId sem credenciais de registo ou tokens de acesso.
• Adicione novas tentativas apenas para falhas transitórias e só quando repetir a operação for seguro.

Passos seguintes

• Escolher e criar uma cadeia de ligação.
• Configurar o comportamento da ligação.
• Gerir o ciclo de vida da ligação.
• Usa o pool de ligações do SQL Server.
• Configurar a lógica de repetição.
• Utilize comandos e parâmetros.