Microsoft. Data.SqlClient para SQL Server

Baixar ADO.NET

Microsoft.Data.SqlClient é o fornecedor de dados do .NET suportado para SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance, Azure Synapse Analytics, base de dados SQL na Microsoft Fabric e Warehouse na Microsoft Fabric. É distribuído como um pacote NuGet, evolui independentemente do runtime .NET e substitui System.Data.SqlClient para novos desenvolvimentos. Fornece ligações, comandos, processamento de resultados, transações, cópia em massa e funcionalidades específicas do SQL Server para aplicações .NET.

Escolhe o teu ponto de partida

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

Use este excerto como ponto de partida para um caminho de acesso a dados SQL do Azure orientado para produção. Lê os nomes dos servidores e da base de dados a partir de IConfiguration, pelo que os valores vêm dos fornecedores de configuração que o host liga, como appsettings.json, variáveis de ambiente, Azure App Configuration e definições suportadas pelo Key Vault. A configuração combina estas características:

  • Segurança da Camada de Transporte (TLS).
  • Identidade gerenciada.
  • Resiliência da ligação inativa.
  • Retentar a ligação inicial através de lógica de retentativa configurável (CRL), com registo estruturado.
  • Retentativa ao nível de comando para erros transitórios que ocorrem a meio da consulta.
  • Recuperação rápida do grupo de failover.
  • Chamadas assíncronas que aceitam um token de cancelamento.

Para maior segurança e para suportar configurações em vários ambientes, mantenha a informação de ligação fora do seu código. Em produção, armazene a informação de ligação no sistema de configuração da sua aplicação e use o Azure Key Vault para valores sensíveis. Para obter mais informações, consulte Proteger informações de conexão.

O excerto de C# neste artigo omite using diretivas e envelopes de classe para maior 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 o ASP.NET Core, fornece o ILogger e o IConfiguration, e a configuração fornece o nome do servidor em Sql:Server e o nome da base 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 devolve o nome da base de dados a que se ligou e regista Connected to database <database>. Quando ocorre uma nova tentativa, também regista um aviso por cada nova tentativa, com a exceção que a originou.

Como funciona cada parte do excerto:

  • Destinos: Qualquer endpoint do SQL Database Engine configurado para autenticação Microsoft Entra: Base de Dados SQL do Azure, Azure SQL Managed Instance, base de dados SQL em Microsoft Fabric, e SQL Server 2022 e versões posteriores em Máquinas Virtuais do Azure ou habilitado pelo Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Seleciona encriptação TDS 8.0. Requer SQL Server 2022 e versões posteriores, Base de Dados SQL do Azure, Azure SQL Managed Instance ou base de dados SQL no Microsoft Fabric. Use SqlConnectionEncryptOption.Mandatory para servidores mais antigos.
  • ActiveDirectoryManagedIdentity: Funciona apenas quando existe uma identidade gerida disponível, como Serviço de Aplicações do Azure, Funções do Azure 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. Mantém-no fora do ambiente de produção porque sondar cada origem atrasa a ligação. Para mais informações, consulte Usar autenticação por defeito.
  • MultiSubnetFailover = true: Tenta ligações TCP a todos os endereços IP resolvidos em paralelo e usa a primeira ligação que tem sucesso, evitando a caminhada sequencial lenta por IP. Define-o para Base de Dados SQL do Azure, Azure SQL Managed Instance, base 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 que não sejam TCP, instâncias com mais de 64 endereços IP ou espelhamento de bases de dados, que está obsoleto. Em vez disso, use os grupos de disponibilidade Always On. Para mais informações, consulte Alta disponibilidade e recuperação de desastres e Desabilitação da Resolução IP de Rede Transparente.
  • ConnectRetryCount = 3 e ConnectRetryInterval = 10: O driver tenta novamente operações que falham com falhas transitórias qualificadas durante Open(), e reconecta uma conexão inativa caída no comando seguinte. A contagem padrão é 1. Três tentativas com 10 segundos de intervalo ultrapassam a duração de uma reconfiguração ou failover mais longo. O driver aumenta 1 para 2 apenas quando o nome do servidor termina num domínio SQL do Azure conhecido, como .database.windows.net, por isso um alias DNS personalizado fica com 1.
  • openRetry: Atribuído a SqlConnection.RetryLogicProvider, adiciona um backoff exponencial em torno de Open(). O driver para as tentativas internas quando ConnectTimeout expira, por isso o pior caso antes de OpenAsync lançar uma exceção são cinco tentativas de até 30 segundos cada, mais o recuo. Cada tentativa de reconexão inativa também executa a política completa openRetry e, quando essa política esgota as suas tentativas de repetição, a recuperação inativa termina.
  • Pausa automática serverless: Para Base de Dados SQL do Azure serverless, aumente ConnectTimeout para pelo menos 60 segundos. O primeiro Open() pode falhar com erro 40613 enquanto a base de dados retoma, e openRetry repete a tentativa. Um timeout do lado do cliente surge como erro -2, que não é repetido, pelo que cada tentativa de ligação deve durar mais do que a retomada. Para mais informações, veja Pausa automática e retomada automática.
  • commandRetry: Anexe-o SqlCommand.RetryLogicProvider apenas quando reproduzir o comando for seguro: leituras, MERGE protegidos por uma chave natural, upserts através de um procedimento armazenado, e outras operações idempotentes. Ignora a repetição dentro de uma transação, pelo que o código da aplicação tem de repetir transações com múltiplas instruções. ExecuteReader e ExecuteScalar repetem apenas 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 incorporada. Para o estender, 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 atraso seguinte e as exceções até agora. Encaminha para ILogger ou para o teu pipeline de telemetria.
  • Exceções: O método não captura exceções. Um fornecedor esgotado lança AggregateException com a exceção de cada tentativa. Um erro não temporário propaga-se como a exceção original. O chamador regista-o uma vez com o resto do contexto do pedido.
  • Cancelamento: O CancellationToken impede a espera do fornecedor entre tentativas. Não interrompe a espera do ConnectRetryInterval controlador numa única Open tentativa. Para mais informações, consulte Programação assíncrona.
  • Tempo de vida do fornecedor: O fragmento cria os fornecedores de repetição em cada chamada para se manter autocontido. Numa aplicação, cria-os uma vez e reutiliza-os.

Para mais informações sobre cada parte desta configuração, veja:

Aprenda as tarefas principais de acesso a dados

Depois de estabelecer ligação, use estes artigos por ordem:

  1. Executar um comando para escolher um formato do resultado e executar Transact-SQL (T-SQL).
  2. Configure os parâmetros para corresponder ao contrato da base de dados.
  3. Recuperar 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. Utilize programação assíncrona e cancelamento para adicionar cancelamento de chamadas e timeouts limitados.
  6. Lida com erros e mensagens antes de adicionares retentativas ou diagnósticos de produção.

Principais características

  • Suporte moderno para .NET: Funciona nas versões atuais de .NET e .NET Framework. Para a divisão por versão, veja Ciclo de vida de Suporte.
  • Cifrado por predefinição: ligações cifradas com TLS e Encrypt=true por predefinição. Defina Encrypt=Strict para a encriptação TDS 8.0.
  • Autenticação Microsoft Entra ID: Ligações sem palavra-passe com identidade gerida, principal de serviço, fluxos interativos e integrados, cadeia de credenciais predefinida e fluxos de token de acesso.
  • Kerberos e NTLM: autenticação integrada do Windows para o Active Directory no local e cenários legados.
  • Always Encrypted: Encriptação do lado do cliente para colunas sensíveis, com enclaves seguros opcionais para operações no local.
  • Cópia em massa: Inserções de alto débito com SqlBulkCopy.
  • Pooling de ligações: Ativado por defeito. Está em avaliação um pool V2 opt-in.
  • Resiliência da ligação: novas tentativas de ligação integradas (ConnectRetryCount e ConnectRetryInterval), além de lógica de repetição configurável, ativada opcionalmente, para ligações e comandos.
  • Tipos de dados enriquecidos do SQL Server: datetimeoffset, sql_variant, JSON, vetorial, espacial, XML e parâmetros com valores em tabelas.
  • Diagnóstico: rastreio de fontes de eventos, contadores de diagnóstico, estatísticas de fornecedores e um guia dedicado à resolução de problemas.
  • Identidade da aplicação: Definir SqlConnection.RegisteredApplication para identificar a 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 Configura um projeto, cria uma base de dados, liga-te, consulta e adiciona resiliência na ligação.
Instalar, atualizar e implementar a Microsoft. Data.SqlClient Instale pacotes NuGet, escolha uma release, atualize o driver e prepare a saída da implementação.
Ciclo de vida do suporte Consulte as versões dos drivers suportados e as datas de suporte.
Migrar do System.Data.SqlClient para a Microsoft. Data.SqlClient Atualize referências de pacotes, namespaces, configuração e altere o comportamento dos drivers.
Espaço de nomes Microsoft.Data.SqlClient e compatibilidade Compreenda como o SqlClient implementa o ADO.NET e a sua compatibilidade com System.Data.SqlClient, .NET e SQL Server.
Novidades na Microsoft. Data.SqlClient Encontre lançamentos atuais, grandes alterações de atualização e notas de lançamento a montante.

Configurar e ligar

Artigo Description
Liga-te a uma fonte de dados Abra e gere conexões, e responda a alterações no estado da conexão.
Cadeias de ligação Configurar servidor, base de dados, autenticação, encriptação e comportamento de ligação.
Encriptação e validação de certificados Configurar ligações encriptadas e validação de certificados do servidor.
Agrupamento de ligações do SQL Server Reutilize as ligações físicas de forma eficiente.
Lidar com erros e mensagens Detetar erros e receber mensagens informativas.

Autenticar e proteger

Artigo Description
Boas práticas de segurança para Microsoft.Data.SqlClient Revise as orientações de autenticação, autorização e segurança da aplicação.
Autenticação do Microsoft Entra Ligue-se à identidade gerida, principal de serviço, palavra-passe e fluxos interativos.
Proteger a informação da ligação Mantenha credenciais e definições de ligação fora do código da aplicação.
Sempre criptografado Proteger valores sensíveis das colunas do sistema de base de dados.
Sempre criptografado com enclaves seguros Efetue operações avançadas em dados encriptados com um enclave seguro.

Recuperar e atualizar dados

Artigo Description
Executar um comando Executar instruções SQL parametrizadas e procedimentos armazenados.
Adaptadores de Dados e Leitores de Dados Transmitir conjuntos de resultados em fluxo ou preencher estruturas de dados desconectadas.
Executar múltiplos comandos com SqlBatch Envie uma coleção ordenada de comandos e processe os seus resultados.
Dados em fluxo Transferir valores grandes de binário, texto, XML e JSON sem colocar o valor completo em buffer.
Transações e concorrência Use transações locais e distribuídas e controlos de concorrência.
Recuperar informação do esquema da base de dados Descubra coleções e restrições de esquemas.
Operações de cópia em massa Carregar grandes conjuntos de dados eficientemente com SqlBulkCopy.
Parâmetros com valores de tabela Envie várias linhas para uma instrução parametrizada ou procedimento armazenado.
Vários conjuntos de resultados ativos (MARS) Intercalar vários lotes numa só ligação.

Tipos de dados

Artigo Description
Mapeamentos de tipos de dados do SQL Server Mapeie os tipos do SQL Server para os tipos .NET e System.Data.SqlTypes.
Dados JSON Envie e recupere o tipo de dado json do SQL Server.
Dados vetoriais Enviar e recuperar valores de vetores.
Dados XML Lê, escreve e parametriza valores XML.
Dados binários e de grande valor Transmitir e atualizar dados binários, FILESTREAM e dados de grande valor.

Fiabilidade e diagnóstico

Artigo Description
Lógica de repetição de tentativas configurável Repita falhas transitórias de conexão e de comando com políticas limitadas.
Alta disponibilidade e recuperação de desastres Ligue-se a ouvintes de grupos de disponibilidade e parceiros de failover.
Contadores de eventos no SqlClient Monitorizar ligações ativas, ligações em pool e outras métricas de controladores.
Ativar rastreio de fontes de eventos Capturar eventos detalhados do controlador para diagnóstico.
Guia de resolução de problemas do SqlClient Diagnosticar problemas comuns de conetividade e de controladores.
Notificações de consulta Receba notificações quando os resultados da consulta mudam.

Funcionalidades do SQL Server

Artigo Description
Funcionalidades e ADO.NET do SQL Server Explore funcionalidades específicas do SQL Server disponíveis através do SqlClient.
LocalDB Ligue-se às instâncias do SQL Server Express LocalDB.
Deteção e classificação de dados Leia metadados de classificação de sensibilidade a partir de conjuntos de resultados.

Referência e recursos

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

Pedir uma funcionalidade

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

Conteúdo relacionado

  • Última atualização a