Microsoft. Data.SqlClient para SQL Server

Baixar ADO.NET

Microsoft.Data.SqlClient é o provedor de dados .NET com suporte para SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, Azure Synapse Analytics, banco de dados SQL no Microsoft Fabric e Data Warehouse no 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. Ele fornece conexões, comandos, processamento de resultados, transações, cópia em massa e recursos específicos do SQL Server para aplicações .NET.

Escolha o ponto de partida

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 de IConfiguration, então os valores vêm dos provedores de configuração que o host conecta, como appsettings.json, variáveis de ambiente, Configuração de Aplicativos do Azure e configurações respaldadas pelo Key Vault. A configuração combina estas características:

  • Segurança da Camada de Transporte (TLS).
  • Identidade gerenciada.
  • Resiliência da conexão ociosa.
  • Retentativa de conexão inicial por meio de lógica configurável de retentativas (CRL), com logging estruturado.
  • Retentativa em nível de comando para erros transitórios que ocorrem durante a consulta.
  • Recuperação de grupo de failover rápido.
  • Chamadas assíncronas que aceitam um token de cancelamento.

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.

O snippet pressupõe um projeto que tem como alvo versões .NET 8 ou posteriores e faz referência aos pacotes Microsoft.Data.SqlClient e Microsoft.Data.SqlClient.Extensions.Azure 7.1.1. O host, como o .NET Generic Host ou ASP.NET Core, fornece o ILogger e o IConfiguration, e a configuração fornece o nome do servidor em Sql:Server e o nome do banco de dados em Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

O método retorna o nome do banco de dados ao qual ele se conectou e registra Connected to database <database>. Quando uma nova tentativa acontece, ela também registra um aviso por nova tentativa, com a exceção que a desencadeou.

Como cada parte do trecho funciona:

  • Alvos: Qualquer endpoint do SQL Mecanismo de Banco de Dados configurado para autenticação Microsoft Entra: Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, banco de dados SQL no Microsoft Fabric e SQL Server 2022 e versões posteriores em Máquinas Virtuais do Azure ou habilitados pelo Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Seleciona criptografia TDS 8.0. Ele requer versões SQL Server 2022 e posteriores, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure ou SQL Database no Microsoft Fabric. Use SqlConnectionEncryptOption.Mandatory para servidores antigos.
  • ActiveDirectoryManagedIdentity: Funciona apenas quando uma identidade gerenciada está disponível, como Serviço de Aplicativo do Azure, Azure Functions ou uma máquina virtual Azure. Para desenvolvimento local, use SqlAuthenticationMethod.ActiveDirectoryDefault, que tenta o CLI do Azure, o login do Visual Studio e outras fontes de credenciais. Não use isso em produção porque sondar cada fonte desacelera a conexão. Para mais informações, veja Usar autenticação padrão.
  • MultiSubnetFailover = true: Tenta conexões TCP para todos os endereços IP resolvidos em paralelo e usa a primeira conexão que tem sucesso, evitando a varredura sequencial lenta de cada IP. Defina para Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, banco de dados SQL no Microsoft Fabric, ouvintes de grupos de disponibilidade e instâncias de cluster de failover. É seguro em alvos de IP único. Não é suportado para instâncias nomeadas, protocolos além do TCP, instâncias com mais de 64 endereços IP nem para espelhamento de banco de dados, que está obsoleto. 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.
  • ConnectRetryCount = 3 e ConnectRetryInterval = 10: o driver tenta novamente as falhas transitórias qualificadas durante Open() e reconecta uma conexão ociosa perdida no próximo comando. A contagem padrão é 1. Três tentativas com 10 segundos de diferença ultrapassam uma reconfiguração ou failover mais longo. O driver altera o valor de 1 para 2 somente quando o nome do servidor termina em um domínio de SQL do Azure conhecido, como .database.windows.net, portanto, um alias de DNS personalizado recebe 1.
  • openRetry: atribuído a SqlConnection.RetryLogicProvider, adiciona retirada exponencial em torno de Open(). O driver para suas tentativas internas quando ConnectTimeout expira, então o pior caso antes que OpenAsync lance uma exceção é cinco tentativas de até 30 segundos cada, mais backoff. Cada tentativa de reconexão ociosa também executa a política completa openRetry , e quando essa política esgota suas tentativas, a recuperação inativa termina.
  • Pausa automática do serverless: Para Banco de Dados SQL do Azure serverless, aumente ConnectTimeout para pelo menos 60 segundos. O primeiro Open() pode ter falha com erro 40613 enquanto o banco de dados é retomado, e openRetry tenta novamente. Um tempo limite do lado do cliente aparece como erro -2, que não é repetido, portanto, cada tentativa de conexão deve durar mais do que a retomada. Para mais informações, consulte Pausa automática e retomada automática.
  • commandRetry: anexe ao SqlCommand.RetryLogicProvider somente quando o comando puder ser reproduzido com segurança: leituras, MERGE protegido por chave natural, operações de upsert por meio de um procedimento armazenado e outras operações idempotentes. Ele ignora a tentativa de repetição dentro de uma transação, portanto, o código do aplicativo deve repetir transações de várias instruções. ExecuteReader e ExecuteScalar tentam novamente somente os erros retornados antes do início do primeiro conjunto de resultados. ExecuteNonQuery repete toda a chamada.
  • Lista de erros transitórios: A configuração TransientErrors substitui a lista embutida. Para estendê-lo em vez disso, use SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 e versões posteriores).
  • Retrying Evento: Retrying Dispara antes de cada tentativa com a contagem de tentativas, o próximo atraso e as exceções até agora. Roteie para ILogger ou para seu pipeline de telemetria.
  • Exceções: O método não captura exceções. Um provedor esgotado lança AggregateException com a exceção de cada tentativa. Um erro não transitório se propaga como a exceção original. O chamador registra isso uma vez junto com o restante do contexto da solicitação.
  • Cancelamento: O CancellationToken interrompe a espera do provedor entre as tentativas. Isso não interrompe a espera do driver ConnectRetryInterval em uma única Open tentativa. Para mais informações, veja Programação assíncrona.
  • Vida útil do provedor: O trecho cria os provedores de retentativa em cada chamada para permanecer autossuficiente. Em uma aplicação, crie-as uma vez e reutilize-as.

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

Aprenda as tarefas principais de acesso a dados

Depois de se conectar, use estes artigos em ordem:

  1. Executar um comando para escolher uma forma de resultado e executar Transact-SQL (T-SQL).
  2. Configure os parâmetros para corresponder ao contrato do banco de dados.
  3. Recupere dados com o SqlDataReader para processar linhas e múltiplos resultados.
  4. Modificar dados com procedimentos armazenados para usar parâmetros de saída e valores de retorno.
  5. Use programação assíncrona e cancelamento para adicionar cancelamento pelo chamador e tempos limite restritos.
  6. Gerencie erros e mensagens antes de adicionar retentativas ou diagnósticos de produção.

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. Configure Encrypt=Strict para criptografia TDS 8.0.
  • 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.
  • Pooling de conexão: Ativado por padrão. Um pool V2 opt-in está em avaliação.
  • 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.
  • Identidade da aplicação: Defina SqlConnection.RegisteredApplication para identificar sua biblioteca ou ferramenta para SQL Server (Microsoft. Data.SqlClient 7.1 e versões posteriores).

Introdução

Artigo Description
Comece a usar o driver SqlClient Configure um projeto, crie um banco de dados, conecte-se, consulte e adicione resiliência de conexão.
Instalar, atualizar e implantar a Microsoft. Data.SqlClient Instale pacotes NuGet, escolha uma versão, atualize o driver e prepare a saída de implantação.
Ciclo de vida do suporte Revise as versões dos drivers suportados e as datas de suporte.
Migre do System.Data.SqlClient para a Microsoft. Data.SqlClient Atualize referências de pacotes, namespaces, configuração e altere o comportamento dos drivers.
namespace Microsoft.Data.SqlClient e compatibilidade Entenda como o SqlClient implementa o ADO.NET e sua compatibilidade com System.Data.SqlClient, .NET e SQL Server.
O que há de novo na Microsoft. Data.SqlClient Encontre versões atuais, principais mudanças de atualização e notas de lançamento upstream.

Configuração e conexão

Artigo Description
Conectar-se a uma fonte de dados Abra e gerencie conexões, e responda a mudanças no estado da conexão.
Strings de conexão Configure servidor, banco de dados, autenticação, criptografia e comportamento de conexão.
Criptografia e validação de certificado Configure conexões criptografadas e validação de certificados de servidor.
Pooling de conexões do SQL Server Reutilize as conexões físicas de forma eficiente.
Lidar com erros e mensagens Detectar erros e receber mensagens informativas.

Autenticar e proteger

Artigo Description
Melhores práticas de segurança para Microsoft.Data.SqlClient Revise as orientações de autenticação, autorização e segurança de aplicações.
Autenticação do Microsoft Entra Conecte-se com identidade gerenciada, principal de serviço, senha e fluxos interativos.
Proteger as informações de conexão Mantenha credenciais e configurações de conexão fora do código da aplicação.
Sempre Criptografado Proteja valores sensíveis de colunas do sistema de banco de dados.
Always Encrypted com enclaves seguros Execute operações avançadas com dados criptografados em um enclave seguro.

Recuperar e atualizar dados

Artigo Description
Executar um comando Execute instruções SQL parametrizadas e procedimentos armazenados.
DataAdapters e DataReaders Transmitir conjuntos de resultados ou preencher estruturas de dados desconectadas.
Execute múltiplos comandos com SqlBatch Envie uma coleção ordenada de comandos e processe seus resultados.
Dados do fluxo Transfira valores grandes de binário, texto, XML e JSON sem armazenar em buffer o valor completo.
Transações e simultaneidade Use transações locais e distribuídas e controles de concorrência.
Recuperar informações do esquema do banco de dados Descubra coleções e restrições de esquemas.
Operações de cópia em massa Carregue grandes conjuntos de dados de forma eficiente com SqlBulkCopy.
Parâmetros com valor de tabela Envie várias linhas para uma instrução parametrizada ou procedimento armazenado.
MARS (conjunto de resultados ativos múltiplos) Interlaçe múltiplos lotes em uma única conexão.

Tipos de dados

Artigo Description
Mapeamentos de tipos de dados do SQL Server Mapeie os tipos de SQL Server para tipos de .NET e de System.Data.SqlTypes.
Dados JSON Envie e recupere o tipo de dado json do SQL Server.
Dados vetoriais Envie e recupere valores vetoriais.
Dados XML Leia, escreva e parametrize valores XML.
Dados binários e de grande valor Transmita e atualize dados binários, FILESTREAM e dados de grande valor.

Confiabilidade e diagnóstico

Artigo Description
Lógica de repetição configurável Tente novamente em caso de falhas transitórias de conexão e de comando com políticas com limites definidos.
Alta disponibilidade e recuperação de desastre Conecte-se a ouvintes de grupos de disponibilidade e parceiros de failover.
Contadores de eventos no SqlClient Monitore conexões ativas, conexões em pool e outras métricas do driver.
Habilitar rastreamento de fontes de eventos Capture eventos detalhados do motorista para diagnóstico.
Guia de solução de problemas do SqlClient Diagnostique problemas comuns de conexão e drivers.
Notificações de consulta Receba notificações quando os resultados da consulta mudam.

Recursos do SQL Server

Artigo Description
Recursos do SQL Server e ADO.NET Navegue por recursos específicos do SQL Server disponíveis através do SqlClient.
LocalDB Conecte-se às instâncias do SQL Server Express LocalDB.
Descoberta e classificação de dados Leia metadados de classificação de sensibilidade dos conjuntos de resultados.

Referências e recursos

Artigo Description
Referência da API Microsoft.Data.SqlClient Consulte a referência da API .NET para o driver.
Mudanças no AppContext Configure o comportamento de compatibilidade e segurança.
Repositório do GitHub do Microsoft.Data.SqlClient Leia o código-fonte do driver, as notas de lançamento e exemplos.
Exemplos do Microsoft.Data.SqlClient Veja exemplos de APIs de driver em C#.
Repositório do .NET Runtime no GitHub Leia o código-fonte das bibliotecas de runtime .NET.

Solicitar um recurso

Para solicitar um recurso, abra uma questão no repositório Microsoft. Data.SqlClient GitHub.

Conteúdo relacionado

  • Última atualização em