Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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
- Para configurar um projeto e rodar sua primeira consulta, comece com Comece com o driver SqlClient.
- Para criar um banco de dados ao qual se conectar, consulte os pré-requisitos em Introdução ao driver SqlClient.
- Para adicionar ou atualizar o driver em um projeto .NET, vá em Instalar, atualizar e implantar 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 Migrar de System.Data.SqlClient para 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 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 o .NET 8 ou versões posteriores e faz referência aos pacotes Microsoft.Data.SqlClient e Microsoft.Data.SqlClient.Extensions.Azure 7.1.2. 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 ocorre uma nova tentativa, também registra um aviso por nova tentativa, com a exceção que a acionou.
Como cada parte do trecho funciona:
- Destinos: 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. UseSqlConnectionEncryptOption.Mandatorypara servidores mais antigos. -
ActiveDirectoryManagedIdentity: Funciona apenas onde uma identidade gerenciada está disponível, como Serviço de Aplicativo do Azure, Azure Functions ou uma máquina virtual Azure. Para desenvolvimento local, useSqlAuthenticationMethod.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 tiver sucesso, evitando a caminhada sequencial lenta por 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 = 3eConnectRetryInterval = 10: O driver tenta novamente as falhas transitórias qualificadoras duranteOpen(), e reconecta uma conexão ociosa caída no comando seguinte. A contagem padrão é 1. Três tentativas com 10 segundos de intervalo são suficientes para cobrir uma reconfiguração ou failover mais longo. O driver altera de 1 para 2 apenas quando o nome do servidor termina em um domínio SQL do Azure conhecido, como.database.windows.net, portanto, um alias DNS personalizado fica em 1. -
openRetry: Atribuído a SqlConnection.RetryLogicProvider, adiciona backoff exponencial em torno deOpen(). O driver para suas tentativas internas quandoConnectTimeoutexpira, então o pior caso antes queOpenAsynclance uma exceção é cinco tentativas de até 30 segundos cada, mais backoff. Cada tentativa de reconexão ociosa também executa a política completaopenRetry, e quando essa política esgota suas tentativas, a recuperação inativa termina. -
Pausa automática sem servidor: Para Banco de Dados SQL do Azure sem servidor, aumente
ConnectTimeoutpara pelo menos 60 segundos. O primeiroOpen()pode falhar com erro40613enquanto o banco de dados retoma eopenRetrytenta novamente. Um timeout do lado do cliente aparece como erro-2, que não é repetido, então cada tentativa de conexão deve durar mais que a retomada. Para mais informações, consulte Pausa automática e retomada automática. -
commandRetry: Anexe-o SqlCommand.RetryLogicProvider apenas quando reproduzir o comando estiver seguro: lês,MERGEprotegido por uma chave natural, upserts por meio de um procedimento armazenado e outras operações idempotentes. Ele não faz nova tentativa dentro de uma transação, então o código da aplicação precisa repetir transações com múltiplas instruções.ExecuteReadereExecuteScalartentam novamente apenas em caso de erros retornados antes que o primeiro conjunto de resultados comece.ExecuteNonQuerytenta novamente a chamada inteira. -
Lista de erros transitórios: A configuração
TransientErrorssubstitui a lista embutida. Para estendê-lo em vez disso, use SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 e versões posteriores). -
RetryingEvento: Retrying É disparado antes de cada tentativa com a contagem de tentativas, o próximo atraso e as exceções até o momento. 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: CancellationToken interrompe a espera do provedor entre as tentativas. Isso não interrompe a espera do driver
ConnectRetryIntervalem uma únicaOpententativa. 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 autônomo. Em uma aplicação, crie-as uma vez e reutilize-as.
Para obter mais informações sobre cada parte dessa configuração, consulte:
- Cadeias de conexão
- Autenticação do Microsoft Entra
- Criptografia e validação de certificados
- Lógica de retentativa configurável
- Alta disponibilidade e recuperação de desastre
Aprenda as tarefas principais de acesso a dados
Depois de se conectar, use estes artigos em ordem:
- Execute um comando para escolher uma forma de resultado e executar Transact-SQL (T-SQL).
- Configure parâmetros para corresponder ao contrato do banco de dados.
- Recupere dados com o SqlDataReader para processar linhas e múltiplos resultados.
- Modifique dados com procedimentos armazenados para usar parâmetros de saída e valores de retorno.
- Use programação assíncrona e cancelamento para adicionar cancelamento pelo chamador e timeouts limitados.
- Trate erros e mensagens antes de adicionar retentativas ou diagnósticos de produção.
Características principais
- Suporte moderno a .NET: Roda 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 por TLS com
Encrypt=truecomo padrão. DefinaEncrypt=Strictpara criptografia TDS 8.0. - Autenticação Microsoft Entra ID: Conexões sem senha com fluxos de identidade gerenciada, principal de serviço, interativo, integrado, cadeia de credenciais padrão e tokens de acesso.
- Kerberos e NTLM: autenticação do Windows integrada 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 de alta taxa de transferência com SqlBulkCopy.
- Agrupamento de conexão: Ativado por padrão. Um pool V2 opt-in está em avaliação.
-
Resiliência de conexão: Retentativas de conexão embutidas (
ConnectRetryCounteConnectRetryInterval) mais lógica de retentativa configurável para conexões e comandos. -
Tipos de dados ricos do SQL Server:
datetimeoffset,sql_variant, JSON, vetor, espacial, XML e parâmetros com valor de tabela. - Diagnóstico: rastreamento da fonte de eventos, contadores de diagnóstico, estatísticas do provedor e um guia dedicado para solução de problemas.
-
Identidade do aplicativo: Defina
SqlConnection.RegisteredApplicationpara identificar sua biblioteca ou ferramenta para o SQL Server (Microsoft.Data.SqlClient 7.1 e 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 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 Microsoft.Data.SqlClient | Atualize referências de pacotes, namespaces, configuração e altere o comportamento dos drivers. |
| namespace e compatibilidade do Microsoft.Data.SqlClient | Entenda como o SqlClient implementa o ADO.NET e sua compatibilidade com System.Data.SqlClient, .NET e SQL Server. |
| Novidades em 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. |
| Cadeias de conexão | Configure servidor, banco de dados, autenticação, criptografia e comportamento de conexão. |
| Criptografia e validação de certificados | Configure conexões criptografadas e validação de certificados de servidor. |
| Agrupamento 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. |
| Proteção das informações de conexão | Mantenha credenciais e configurações de conexão fora do código da aplicação. |
| Always Encrypted | 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. |
| Executar múltiplos comandos com SqlBatch | Envie uma coleção ordenada de comandos e processe seus resultados. |
| Dados em fluxo | Transfira valores grandes de binário, texto, XML e JSON sem armazenar em buffer o valor completo. |
| Transações e concorrência | 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. |
| Múltiplos Conjuntos de Resultados Ativos (MARS) | Interlaçe múltiplos lotes em uma única conexão. |
Tipos de dados
| Artigo | Description |
|---|---|
| Mapeamentos de tipos de dados do SQL Server | Mapear os tipos do SQL Server para os tipos do .NET e 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 grandes valores | Transmita e atualize dados binários, FILESTREAM e dados de grande valor. |
Confiabilidade e diagnóstico
| Artigo | Description |
|---|---|
| Lógica de retentativa 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 da fonte 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. |
| Switches 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 exemplos. |
| Exemplos do Microsoft.Data.SqlClient | Veja exemplos de APIs de driver em C#. |
| Repositório .NET runtime do 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.