Microsoft. Data.SqlClient para SQL Server

Baixar ADO.NET

Microsoft. Data.SqlClient é o provedor de dados .NET suportado para SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, Azure Synapse Analytics e banco de dados SQL em Microsoft Fabric. Ele é distribuído como um pacote NuGet, evolui independentemente do tempo de execução .NET e substitui System.Data.SqlClient para novos desenvolvimentos. Use-o para abrir conexões, executar comandos, processar resultados, gerenciar transações, carregar dados em massa e usar recursos específicos do SQL Server de aplicações .NET.

Escolha o ponto de partida

• Para configurar um projeto e rodar sua primeira consulta, comece com Começando com o driver SqlClient.
• Para adicionar o driver a um projeto .NET, acesse Download Microsoft. Data.SqlClient.
• Para conectar ao SQL do Azure com autenticação sem senha, comece com a autenticação Microsoft Entra e as strings de conexão.
• Para tornar uma aplicação existente resiliente a falhas transitórias, vá para Lógica de retentativa configurável e Alta disponibilidade e recuperação de desastres.
• Para mover conjuntos de dados grandes de forma eficiente, vá para Operações de cópia em massa.
• Para migrar de System.Data.SqlClient, comece com Introdução ao namespace Microsoft.Data.SqlClient.
• Para diagnosticar um problema de conexão ou consulta, acesse o guia de solução de problemas do SqlClient e ative o rastreamento da fonte de eventos.

Linha de base de produção para SQL do Azure

Use este trecho como ponto de partida para um caminho de acesso a dados SQL do Azure orientado à produção. Ele lê os nomes dos servidores e do banco de dados a partir de IConfiguration, então os valores vêm dos provedores de configuração que o host conecta (appsettings.jsonvariáveis de ambiente, Configuração de Aplicativos do Azure, configurações suportadas pelo Key Vault, e assim por diante). A configuração combina Segurança da Camada de Transporte (TLS), identidade gerenciada, resiliência de conexão ociosa, nova tentativa de conexão inicial por meio de uma lógica de repetição configurável (CRL) com registro estruturado em log, repetição em nível de comando para erros transitórios que ocorrem no meio da consulta e recuperação rápida do grupo de failover.

Para maior segurança e suporte à configuração em diferentes ambientes, mantenha as informações de conexão fora do seu código. Em produção, armazene as informações de conexão no sistema de configuração do seu aplicativo e use o Azure Key Vault para valores sensíveis. Para obter mais informações, confira Proteger informações de conexão.

O trecho de C# deste artigo omite as diretivas using e os encapsulamentos de classe por brevidade.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Este snippet destina-se a qualquer endpoint do SQL Mecanismo de Banco de Dados configurado para a autenticação do Microsoft Entra: Banco de Dados SQL do Azure, Instância Gerenciada do SQL do Azure, banco de dados SQL no Microsoft Fabric e SQL Server 2022 e versões posteriores nas Máquinas Virtuais do Azure ou habilitado pelo Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict seleciona a criptografia TDS 8.0. Exige a Microsoft. Data.SqlClient 5.0 e versões posteriores, além de um servidor que suporta TDS 8.0 (SQL Server 2022 e versões posteriores, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric). Recorra a SqlConnectionEncryptOption.Mandatory ao se conectar a servidores mais antigos.

ConnectRetryCount e ConnectRetryInterval ativam a resiliência de conexões ociosas: após a conclusão bem-sucedida de Open(), o driver reconecta de forma transparente uma conexão ociosa interrompida no próximo comando. Eles não repetem a tentativa inicial Open(). As novas tentativas de conexão inicial partem do provedor openRetry atribuído a SqlConnection.RetryLogicProvider. As duas características são complementares.

O evento Retrying em cada provedor é acionado antes de cada nova tentativa e fornece o número de tentativas, o atraso antes da próxima tentativa e as exceções observadas até o momento. Roteie para ILogger ou para seu pipeline de telemetria para manter o loop de tentativa visível em produção.

Definido MultiSubnetFailover = true quando o alvo é Banco de Dados SQL do Azure, Instância Gerenciada do SQL do Azure, banco de dados SQL no Microsoft Fabric, um ouvinte de grupo de disponibilidade ou uma instância de cluster de failover. Ele seleciona um fluxo de código para conexões paralelas que tenta estabelecer conexões TCP com todos os endereços IP resolvidos em paralelo e usa a primeira conexão bem-sucedida, evitando o processamento sequencial e lento de cada IP, que de outra forma poderia atrasar essas conexões. Em alvos de IP único, a configuração é segura. MultiSubnetFailover não é suportado quando você se conecta a uma instância nomeada, por um protocolo diferente do TCP, ou a uma instância configurada com mais de 64 endereços IP. Você também não pode usá-lo com espelhamento de banco de dados, que está obsoleto em todas as versões suportadas do SQL Server. Use Grupos de disponibilidade AlwaysOn em vez disso. Para mais informações, veja Alta disponibilidade e recuperação em caso de desastres e Desabilitando a Resolução Transparente de IP de Redes.

Se o alvo for Banco de Dados SQL do Azure sem servidor com pausa automática ativada, aumente ConnectTimeout para pelo menos 60 segundos. Um banco de dados com pausa automática retoma no primeiro Open(), e esse primeiro Open() pode falhar com erro 40613 enquanto o banco de dados recomeça. Erro 40613 está na lista de erros transitórios embutida, então openRetry tente novamente. Os timeouts no lado do cliente se manifestam como o erro -2, que não está nessa lista, então openRetry não vai resgatar um Open() que sofre timeout no meio da retomada. A tentativa individual de contato deve ser longa o suficiente para cobrir o currículo. Para mais informações, consulte Pausa automática e retomada automática.

A nova tentativa em nível de comando fica a critério do chamador, para cada comando. Anexe commandRetry ao SqlCommand.RetryLogicProvider apenas quando o comando puder ser repetido com segurança: leituras, MERGE protegido por chave natural, operações de upsert por meio de um procedimento armazenado e outras operações idempotentes. O provedor de comandos interno não faz nova tentativa quando há uma transação ativa, portanto transações de várias instruções devem ser submetidas a nova tentativa pelo código da aplicação, que pode reabrir a transação. A configuração TransientErrors substitui a lista de erros interna do driver; para estender a linha de base interna, use SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 e versões posteriores).

Para obter mais informações sobre cada parte dessa configuração, consulte:

• Strings de conexão
• Autenticação do Microsoft Entra
• Criptografia e validação de certificado
• Lógica de repetição configurável
• Alta disponibilidade e recuperação de desastre

Características principais

• Suporte moderno para .NET: Funciona nas versões atuais do .NET e do .NET Framework. Para o detalhamento por versão, veja ciclo de vida do suporte.
• Criptografado por padrão: conexões criptografadas TLS com Encrypt=true como padrão. Defina Encrypt=Strict para a criptografia TDS 8.0 no Microsoft.Data.SqlClient 5.0 e posteriores.
• Autenticação do Microsoft Entra ID: conexões sem senha com identidade gerenciada, entidade de serviço e fluxos interativo, integrado, de cadeia de credenciais padrão e de token de acesso.
• Kerberos e NTLM: autenticação integrada do Windows para o Active Directory local e cenários legados.
• Always Encrypted: criptografia do lado do cliente para colunas sensíveis, com enclaves seguros opcionais para operações no local.
• Cópia em massa: inserções em alta taxa de transferência com SqlBulkCopy.
• Resiliência da conexão: tentativas automáticas de conexão integradas (ConnectRetryCount e ConnectRetryInterval), além de lógica de repetição opcional e configurável para conexões e comandos.
• Tipos de dados avançados do SQL Server: datetimeoffset, sql_variant, JSON, vetor, dados espaciais, XML e parâmetros com valor de tabela.
• Diagnóstico: rastreamento de fontes de eventos, contadores de diagnóstico, estatísticas de provedores e um guia dedicado à resolução de problemas.

Introdução

Configuração e conexão

Autenticar e proteger

Recuperar e atualizar dados

Tipos de dados

Confiabilidade e diagnóstico

Recursos do SQL Server

Referências e recursos

Conteúdo relacionado

• Microsoft. Data.SqlClient no GitHub
• Microsoft.Data.SqlClient no NuGet
• Notas de lançamento
• Visão geral do ADO.NET
• módulos de conexão para o Banco de Dados SQL da Microsoft