Cadeias de conexão para Microsoft.Data.SqlClient

Uma Microsoft. Data.SqlClient cadeia de conexão informa ao driver qual endpoint e banco de dados compatíveis com SQL Server usar, como autenticar e como configurar a conexão. Passe para SqlConnection ou SqlConnectionStringBuilder.

Comece com quatro decisões:

Qual servidor e banco de dados o aplicativo usa?
Usando qual identidade o aplicativo é executado?
Como o cliente valida o certificado do servidor?
De qual comportamento de conexão a carga de trabalho precisa?

Mantenha credenciais e tokens de acesso fora da cadeia de conexão quando o método de autenticação escolhido oferecer suporte a essa abordagem.

Escolha um padrão de autenticação

Use o padrão mais estreito que se encaixe na implantação.

Ambiente	Padrão preferido	Cadeia de conexão do Core
SQL Server no Windows sob um domínio ou identidade local do Windows	Autenticação integrada do Windows	`Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true`
Estação de trabalho do desenvolvedor conectando ao banco de dados SQL no Microsoft Fabric	Microsoft Entra ID cadeia padrão de credenciais	`Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Aplicação hospedada no Azure e conectando-se ao SQL do Azure	identidade gerenciada do Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict`
Workstation de desenvolvedor conectando-se ao SQL do Azure	Microsoft Entra ID cadeia padrão de credenciais	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Ferramenta interativa de desktop conectando-se ao SQL do Azure	Autenticação interativa do Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict`
Ambiente que requer autenticação SQL	Nome de usuário e senha de uma loja secreta	`Server=<server>;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true`

Microsoft.Data.SqlClient 7.0 e versões posteriores exigem o pacote Microsoft.Data.SqlClient.Extensions.Azure correspondente à versão para os modos de autenticação do Microsoft Entra ID fornecidos pelo driver. Você não precisa dessa extensão quando o código da aplicação fornece um token de acesso ou um callback para o token de acesso.

A autenticação também requer usuários do lado do banco de dados, permissões e configuração de identidade. Para a matriz completa de escolhas e configuração, veja autenticação Microsoft Entra ID e autenticação SQL Server.

Especifique o servidor e o banco de dados

Use Server e Database como os nomes canônicos de palavras-chave. O motorista também aceita apelidos como Data Source para Server e Initial Catalog para Database.

Formulários comuns de servidores incluem:

Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB

Prefiro um protocolo explícito, nome de host e porta para conexões TCP de produção. Use um nome DNS estável que corresponda ao certificado do servidor em vez de um endereço IP.

Para um listener de grupo de disponibilidade, grupo de failover, ponto de extremidade do SQL do Azure ou outro ponto de extremidade TCP com vários endereços, consulte também MultiSubnetFailover em Opções de conexão.

Configurar criptografia e validação de certificados

Microsoft.Data.SqlClient 4.0 e versões posteriores usam true como padrão em vez de Encrypt. Microsoft.Data.SqlClient 5.0 e versões posteriores também oferecem suporte a Encrypt=Strict para servidores que negociam TDS 8.0.

Uso:

Encrypt=Strict quando o servidor suporta TDS 8.0 e possui um certificado que o cliente pode validar.
Encrypt=true para conexões criptografadas com outros servidores suportados.
TrustServerCertificate=false, o padrão, para validação de certificados de produção.

Não use TrustServerCertificate=true como uma correção genérica para problemas de conexão. Ele criptografa o canal, mas pula a validação da identidade do servidor. Limite isso a ambientes de desenvolvimento controlados onde um certificado confiável não esteja disponível.

Para requisitos de servidor, comportamento de versões e opções de certificado, veja Criptografia e validação de certificados.

Entenda a sintaxe da cadeia de conexão

Uma cadeia de conexão é uma lista delimitada por ponto e vírgula de pares de palavras-chave e valor:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=true

Siga estas regras:

Nomes-chave não são sensíveis a maiúsculas e minúsculas.
Os valores podem diferenciar maiúsculas de minúsculas.
Um ponto e vírgula final é opcional.
Cite um valor com aspas simples ou duplas quando ele contém um ponto e vírgula ou um espaço em branco inicial ou final.
Evite a citação que envolve um valor dobrando-o.
Não use palavras-chave duplicadas. O analisador usa o último valor, o que dificulta a revisão da configuração efetiva.

O conjunto de palavras-chave e pseudônimos aceitos pertence ao provedor. Uma cadeia de conexão aceita por Microsoft.Data.SqlClient pode não funcionar com System.Data.SqlClient ou com outro provedor de dados.

Construa as strings de conexão com segurança

Use SqlConnectionStringBuilder quando o código precisar adicionar, validar ou substituir valores. Não concatene valores não confiáveis em uma cadeia de conexão.

string baseConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    ApplicationName = "Orders.Api",
    ConnectTimeout = 30,
};

string connectionString = builder.ConnectionString;

O construtor:

Rejeita palavras-chave não suportadas e valores inválidos.
Mapeia aliases para propriedades canônicas.
Cite valores quando necessário.
Impede que um valor injete outra palavra-chave.

O construtor não protege uma senha ou um token depois que a senha ou o token entram na memória do processo. Também não decide se uma configuração de servidor, identidade ou certificado é segura.

Armazene informações de conexão fora do código

Carregue as strings de conexão do sistema de configuração usado pelo aplicativo. Aplicações .NET atuais comumente utilizam variáveis de ambiente, segredos de usuário para desenvolvimento local, Configuração de Aplicativos do Azure e configuração respaldada pelo Azure Key Vault.

Mantenha estas regras:

Não comprometa senhas, segredos de clientes, tokens de acesso ou strings de conexão de produção.
Prefira um método de autenticação baseado em identidade que não exija senha na cadeia de conexão.
Restringa o acesso à fonte de configuração.
Faça a rotação dos segredos armazenados e reinicie ou atualize os aplicativos que os mantêm em cache.
Não grave cadeias de conexão em logs, exceções, rastreamentos ou telemetria.
Deixe Persist Security Info=false, o padrão, para que uma conexão aberta não exponha valores sensíveis à segurança através da sua cadeia de conexão.

Para provedores de configuração .NET, veja Configuração em .NET. Para controles adicionais, veja Proteger informações de conexão.

Mantenha as chaves do pool estáveis

O pool de conexão utiliza uma configuração exata de conexão como parte de sua chave de pool. Strings equivalentes podem criar pools separados quando seu texto difere, inclusive quando palavras-chave aparecem em ordem diferente.

Construa uma cadeia de conexão canônica na inicialização do aplicativo e reutilize-a. Não adicione IDs de requisição, nomes de usuário, tokens de acesso ou outros valores por requisição à string. Para as regras completas de chaves, veja SQL Server connection pooling.

Configurações separadas de conexão e comando

Uma cadeia de conexão controla o estabelecimento de conexão e o comportamento da sessão. Um comando controla uma operação SQL.

Requirement	Configurar em
Tempo permitido para estabelecer uma conexão ou obter uma do pool	`Connect Timeout` Opção de conexão
Tempo limite padrão de execução do comando	`Command Timeout` opção de conexão, quando suportada pela versão do driver
Tempo limite de um comando	CommandTimeout
Cancelamento pelo chamador	`CancellationToken` passado para APIs assíncronas
Política de repetição para abrir uma conexão ou executar um comando	Lógica configurável de nova tentativa em `SqlConnection` ou `SqlCommand`

Não trate um tempo de espera mais longo como lógica de retentativa. Um tempo limite limita uma espera. Uma nova tentativa inicia outra tentativa e deve ser limitada e segura para ser repetida.

Analise o comportamento sensível à versão

Versão do driver	Mudança de corda de conexão
4.0	`Encrypt` usa como padrão `true`.
5.0	`Encrypt=Strict` e `HostNameInCertificate` estão disponíveis. `SqlConnectionStringBuilder.Encrypt` usa `SqlConnectionEncryptOption`.
5.1	`ServerCertificate` pode comparar o certificado do servidor com um arquivo.
5.2	AccessTokenCallback está disponível para tokens renováveis fornecidos por aplicativos.
7.0	A autenticação do Microsoft Entra ID fornecida por drivers passa para `Microsoft.Data.SqlClient.Extensions.Azure`.
7.0.2	O driver principal e seus pacotes complementares usam versões alinhadas.

Use uma versão estável de driver suportada e leia as notas de lançamento antes da atualização. Para versões atuais, veja ciclo de vida do suporte ao driver SqlClient.

Comentários

Esta página foi útil?

Last updated on 2026-09-21