Cadeias de ligação para Microsoft.Data.SqlClient

Uma cadeia de ligação Microsoft.Data.SqlClient indica ao controlador qual o ponto final e a base de dados compatíveis com o SQL Server a utilizar, como efetuar a autenticação e como configurar a ligação. Passa para SqlConnection ou SqlConnectionStringBuilder.

Comece com quatro decisões:

Que servidor e base de dados é que a aplicação utiliza?
Com que identidade corre a aplicação?
Como é que o cliente valida o certificado do servidor?
Que comportamento de conectividade é necessário para a carga de trabalho?

Mantenha as credenciais e os tokens de acesso fora da cadeia de ligação quando o método de autenticação escolhido suportar essa abordagem.

Escolha um padrão de autenticação

Use o padrão mais estreito que se ajuste à implementação.

Environment	Padrão preferido	Cadeia de ligaçã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 programador ligada a uma base de dados SQL no Microsoft Fabric	Cadeia de credenciais padrão Microsoft Entra ID	`Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Aplicação alojada no Azure e ligada ao SQL do Azure	Identidade gerida do Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict`
Estação de trabalho de desenvolvedor a estabelecer ligação ao SQL do Azure	Cadeia de credenciais padrão Microsoft Entra ID	`Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Ferramenta interativa de ambiente de trabalho que se liga 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 utilizador e palavra-passe 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 requerem o pacote Microsoft.Data.SqlClient.Extensions.Azure correspondente à versão para os modos de autenticação do Microsoft Entra ID fornecidos pelo controlador. Não precisa dessa extensão quando o código da aplicação fornece um token de acesso ou um callback do token de acesso.

A autenticação também requer utilizadores do lado da base 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 a base de dados

Use Server e Database como nomes-chave canónicos. O condutor também aceita pseudónimos como Data Source para Server e Initial Catalog para Database.

Formulários comuns de servidor 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 ligaçõ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 ativação pós-falha, ponto final do SQL do Azure ou outro ponto final TCP com vários endereços, consulte também MultiSubnetFailover em Opções de ligação.

Configurar encriptação e validação de certificados

Microsoft.Data.SqlClient 4.0 e versões posteriores utilizam Encrypt por predefinição para true. Microsoft.Data.SqlClient 5.0 e versões posteriores também suportam Encrypt=Strict para servidores que negoceiam TDS 8.0.

Utilização:

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

Não uses TrustServerCertificate=true como uma solução genérica para problemas de ligação. Encripta o canal, mas ignora a validação da identidade do servidor. Limite-o a ambientes de desenvolvimento controlados onde não esteja disponível um certificado de confiança.

Para requisitos de servidor, comportamento de versões e opções de certificados, consulte Encriptação e validação de certificados.

Compreender a sintaxe da cadeia de ligação

Uma cadeia de ligaçã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:

Os nomes das palavras‑chave não são sensíveis a maiúsculas e minúsculas.
Os valores podem distinguir maiúsculas de minúsculas.
Um ponto e vírgula final é opcional.
Cite um valor com aspas simples ou duplas quando contiver um ponto e vírgula ou um espaço em branco inicial ou final.
Evite a citação que envolve um valor duplicando-o.
Não uses 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 aceites pertence ao fornecedor. Uma cadeia de ligação aceite por Microsoft.Data.SqlClient pode não funcionar com System.Data.SqlClient ou com outro fornecedor de dados.

Construir cadeias de ligação de forma segura

Use SqlConnectionStringBuilder quando o código precisar de adicionar, validar ou substituir valores. Não concatenes valores não confiáveis numa cadeia de ligaçã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.
Associa aliases a propriedades canónicas.
Cita valores quando necessário.
Impede que um valor injete outra palavra-chave.

O utilitário de compilação não protege uma palavra-passe nem um token depois de estes entrarem na memória do processo. Também não decide se uma definição de servidor, identidade ou certificado é segura.

Armazenar informação de ligação fora do código

Carregar cadeias de conexão a partir do sistema de configuração utilizado pela aplicação. As aplicações .NET atuais usam frequentemente variáveis de ambiente, segredos de utilizador para desenvolvimento local, Azure App Configuration e configuração apoiada pelo Azure Key Vault.

Mantém estas regras:

Não submeta palavras-passe, segredos de cliente, tokens de acesso nem strings de ligação de produção.
Prefiro um método de autenticação baseado em identidade que não exija palavra-passe na cadeia de ligação.
Restrinja o acesso à fonte de configuração.
Efetuar a rotação dos segredos armazenados e reiniciar ou recarregar aplicações que os mantêm em cache.
Não escrevas strings de ligação em registos, exceções, rastreios ou telemetria.
Deixe Persist Security Info=false, o padrão, para que uma ligação aberta não exponha valores sensíveis à segurança através da sua cadeia de ligação.

Para fornecedores de configuração .NET, veja Configuração em .NET. Para controlos adicionais, consulte Proteger informações de ligação.

Mantenha as chaves do pool estáveis

O agrupamento de ligações recorre a uma configuração exata da ligação como parte da chave do agrupamento. Cadeias de caracteres equivalentes podem criar grupos separados quando o respetivo texto é diferente, incluindo quando as palavras-chave aparecem numa ordem diferente.

Crie uma cadeia de ligação canónica no arranque da aplicação e reutilize-a. Não adicione IDs de pedido, nomes de utilizador, tokens de acesso ou outros valores por pedido à string. Para consultar as regras principais completas, consulte agrupamento de ligações do SQL Server.

Definições separadas de ligação e comandos

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

Requisito	Configurar em
Tempo permitido para estabelecer uma ligação ou obter uma do pool	`Connect Timeout` Opção de ligação
Tempo limite de execução do comando por defeito	`Command Timeout` opção de ligação, quando suportada pela versão do driver
Tempo de espera para um comando	CommandTimeout
Cancelamento por parte do autor da chamada	`CancellationToken` passado para APIs assíncronas
Política de repetição para estabelecer uma ligação ou executar um comando	Lógica configurável de repetição para `SqlConnection` ou `SqlCommand`

Não trates um timeout mais longo como lógica de repetição. Um timeout limita uma espera. Uma repetição dá início a uma nova tentativa e tem de ser delimitada e segura de repetir.

Revisão do comportamento sensível à versão

Versão do controlador	Alteração da corda de ligação
4.0	`Encrypt` assume como padrão `true`.
5.0	`Encrypt=Strict` e `HostNameInCertificate` estão disponíveis. `SqlConnectionStringBuilder.Encrypt` utiliza `SqlConnectionEncryptOption`.
5.1	`ServerCertificate` pode comparar o certificado do servidor com um ficheiro.
5,2	AccessTokenCallback está disponível para tokens renováveis fornecidos por aplicações.
7.0	A autenticação do Microsoft Entra ID fornecida pelos controladores passa para `Microsoft.Data.SqlClient.Extensions.Azure`.
7.0.2	O driver principal e os seus pacotes complementares utilizam versões alinhadas.

Usa uma versão estável do driver suportada e lê as notas de lançamento antes de uma 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