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

Uma Microsoft.Data.SqlClient cadeia de ligação é uma lista de keyword=value pares separados por ponto e vírgula. Passar para SqlConnection ou SqlConnectionStringBuilder:

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

Uma cadeia de ligação responde a quatro perguntas:

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

Este artigo aborda essas opções e as regras que o driver utiliza para ler o texto. Para cada palavra-chave, os seus sinónimos e o seu valor predefinido, veja Opções de Ligação. Para criar e alterar cadeias de ligação no código, veja Construtores de cadeias de conexão.

Escolha um padrão de autenticação

Utilize o padrão que se ajusta à implantação. Substitua cada marcador de lugar, como <server>, pelo seu valor.

Environment Pattern Cadeia de ligação
SQL Server no Windows com um domínio ou identidade local do Windows Autenticação integrada do Windows Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
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
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
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>;Password=<password>;Encrypt=true

A autenticação integrada do Windows liga-se como a identidade do processo. Para uma aplicação de desktop ou consola, normalmente é o utilizador iniciado em sessão. Para uma aplicação web ou um serviço Windows, é o pool de aplicações ou conta de serviço. A personificação pode mudar a identidade. Conceda permissões de login e de base de dados à identidade que a sua aplicação realmente utiliza.

Estas três formas de autenticação integrada no Windows são equivalentes:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Se uma cadeia de caracteres definir Integrated Security=true e também definir User ID e Password, o driver usa Windows authentication e ignora o nome de utilizador e a palavra-passe.

Microsoft.Data.SqlClient 7.0 e versões posteriores necessitam do pacote Microsoft.Data.SqlClient.Extensions.Azure compatível com a versão para os métodos de autenticação do Microsoft Entra ID fornecidos pelo controlador. Não precisas desse pacote quando o código da aplicação fornece um token de acesso ou um callback de token de acesso.

Para os valores aceites Authentication , consulte Opções de autenticação. A autenticação também requer utilizadores da base de dados, permissões e configuração de identidade no servidor. Para os passos de configuração, consulte autenticação Microsoft Entra ID e autenticação SQL Server.

Especifique o servidor e a base de dados

Server e Database são os nomes-chave mais legíveis. O construtor escreve-os como equivalentes canónicos, Data Source e Initial Catalog. Os quatro nomes funcionam numa cadeia de ligação.

Definido Server para uma destas formas:

Form Example Use
Nome do anfitrião Server=sql.example.com A instância padrão na porta 1433.
Nome do host e porta Server=tcp:sql.example.com,1433 Uma porta TCP específica. Separe o porto com uma vírgula, não com dois pontos.
Instância nomeada Server=sql.example.com\SALES Uma instância nomeada. O driver pede ao serviço SQL Server Browser na porta UDP 1434 a porta.
Servidor local Server=(local) ou Server=. A instância padrão do computador local.
LocalDB Server=(localdb)\MSSQLLocalDB SQL Server Express LocalDB no Windows. A ligação não está encriptada, mesmo com Encrypt=Mandatory, e Encrypt=Strict falha.
Pipe nomeado Server=np:\\sql.example.com\pipe\sql\query Uma ligação de tubo nomeada no Windows.

Use tcp:, um nome de host totalmente qualificado e uma porta explícita em produção. Use um nome DNS que corresponda ao certificado do servidor, não um endereço IP, porque a validação do certificado compara o nome do servidor na cadeia de ligação com os nomes no certificado.

Quando se liga ao Base de Dados SQL do Azure com autenticação SQL e um nome de utilizador no formulário user@servername, a servername parte deve corresponder ao servidor em Server.

Para um ouvinte de grupo de disponibilidade ou uma instância de cluster de failover, consulte Multi Subnet Failover também as opções de Ligação.

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

A Encrypt palavra-chave aceita os seguintes valores, em qualquer dos casos:

Value Valor do construtor Meaning
Strict Strict Usa TDS 8.0. Encripta a ligação antes do login e valida sempre o certificado do servidor.
Mandatory, true, yes True Criptografa a ligação. Esse valor é o padrão.
Optional, false, no False Só encripta toda a ligação quando o servidor precisa de encriptação. Quando o servidor suporta encriptação mas não a exige, encripta apenas o pacote de login.

Utilize Strict quando o servidor suporta TDS 8.0 e tem um certificado que o cliente pode validar. Base de Dados SQL do Azure e SQL Database no Microsoft Fabric suportam-no. Uma ligação LocalDB não está encriptada, mesmo com Mandatory, e Strict falha.

Os valores Encrypt e Trust Server Certificate combinam-se da seguinte forma:

Criptografar Certificado de servidor confiável Result
Optional false Quando o servidor necessita de encriptação, toda a ligação é encriptada e o certificado do servidor tem de ser validado. Caso contrário, a ligação falha. Quando o servidor suporta encriptação mas não a exige, apenas o pacote de login é encriptado, e o driver não valida o certificado do servidor a menos que a ligação use AccessToken ou AccessTokenCallback. Quando o servidor não suporta encriptação, nada é encriptado.
Optional true Quando o servidor necessita de encriptação, toda a ligação é encriptada. Quando o servidor suporta encriptação mas não a exige, apenas o pacote de login é encriptado. O driver não valida o certificado do servidor.
Mandatory false A encriptação ocorre apenas quando o certificado do servidor é validado. Caso contrário, a ligação falha.
Mandatory true A encriptação ocorre sempre, mas o driver não valida o certificado do servidor.
Strict Ignored A encriptação ocorre sempre, e o certificado do servidor tem de ser validado. Caso contrário, a ligação falha.

Não definas Trust Server Certificate=true para corrigir um erro de ligação em produção. Encripta o canal, mas não confirma a identidade do servidor. Limite-o a ambientes de desenvolvimento onde não esteja disponível um certificado de confiança.

Quando o nome do servidor em Data Source não corresponde ao certificado, defina Host Name In Certificate para o nome que consta no certificado. O SqlClient só verifica quando o nome do servidor não coincide, e não faz pinning de um certificado. Para aceitar apenas um certificado específico, defina Server Certificate para o caminho de um ficheiro PEM, DER ou CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

Para as regras completas de validação, veja Encriptação e validação de certificados.

Utilizar o pool de conexões

O pooling está ativado por predefinição. Quando abres um SqlConnection, o driver retira uma ligação física de um pool que corresponde a essa ligação. Quando fecha ou liberta a conexão, a conexão física regressa ao pool em vez de fechar. Uma abertura em pool ignora a ligação de rede, o handshake TLS e o login.

Siga estas regras:

  • Abra uma ligação pouco antes de precisar dela e liberte-a assim que terminar, com using ou await using. Uma ligação que não é libertada permanece alocada, e o pool pode esgotar-se.

  • Criar a cadeia de ligação assim que arranca e reutilizá-la. A chave do pool inclui o texto exato da cadeia de ligação, por isso uma ordem diferente das palavras-chave, um sinónimo ou um valor por pedido, como um ID de pedido ou nome de utilizador, cria um pool separado. O construtor escreve uma forma canónica. Para mais informações, veja Manter uma cadeia de ligação canónica.

  • Espere um pool separado para cada identidade do Windows sob autenticação integrada, cada SqlCredential instância e cada AccessToken valor. Utilize um método fornecido Authentication pelo driver ou um reutilizado AccessTokenCallback em vez de configurar AccessToken em cada ligação.

  • Procure ligações que não estejam descartadas antes de aumentar Max Pool Size, que por defeito é 100. Quando todas as ligações de um pool estão em uso, Open espera até Connect Timeout e depois lança InvalidOperationException:

    Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

  • Planeie a capacidade do servidor para cada pool. Cada processo, ou cada domínio de aplicação no .NET Framework, tem os seus próprios pools. As ligações ao servidor podem atingir Max Pool Size multiplicadas pelos pools em cada processo e pelo número de instâncias de aplicação.

  • Não definas Pooling=false para contornar um problema de pooling. Cada vez que é aberto faz então um login completo.

Para fechar ligações agrupadas que permanecem inativas por demasiado tempo, veja Limitar o tempo de inatividade da ligação. Para chaves de pool, dimensionamento, limpeza e transações, veja pooling de ligações ao 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 palavra-chave
Timeout padrão para comandos na ligação Command Timeout palavra-chave
Tempo de espera para um comando CommandTimeout
Cancelamento por parte do autor da chamada CancellationToken é passado para métodos assíncronos
Política de nova tentativa para abrir uma ligação ou executar um comando Lógica de retentativa configurável em SqlConnection ou SqlCommand

Um tempo de espera mais longo não é lógica de nova tentativa. Um timeout limita uma espera. Uma nova tentativa inicia outra tentativa, e tem de ser limitada e segura para ser repetida.

Informe a identidade da aplicação

Application Name define o nome que o servidor indica através de APP_NAME(). Utilize um nome estável para cada carga de trabalho implementada. Frameworks e ferramentas que abrem ligações para uma aplicação também podem reportar-se através da propriedade RegisteredApplication, que não tem palavra-chave da cadeia de ligação. Para mais informações, consulte Comunicar a identidade da aplicação.

Construir cadeias de ligação de forma segura

Utilize SqlConnectionStringBuilder quando o código adiciona ou altera um valor. Não junte texto não confiável a uma cadeia de ligação, porque um ponto e vírgula nesse texto pode adicionar ou substituir uma palavra-chave. O construtor valida valores, mapeia sinónimos para palavras-chave canónicas e coloca cada valor entre aspas para que o valor não possa adicionar palavras-chave. Para exemplos, veja Construtores de cadeias de ligação.

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

Carregar cadeias de ligação a partir do sistema de configuração da aplicação. As aplicações .NET utilizam frequentemente variáveis de ambiente, segredos de utilizador para desenvolvimento local, Azure App Configuration e Azure Key Vault.

Siga 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 que não precise de palavra-passe na cadeia de ligação.
  • Restrinja o acesso à fonte de configuração.
  • Roda os segredos armazenados e reinicia ou atualiza as aplicações que os armazenam 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 a palavra-passe através da sua ConnectionString propriedade.

Para fornecedores de configuração .NET, veja Configuração em .NET. Para mais controlos, veja Proteger informação de ligação.

Regras de parsing

O condutor aplica estas regras:

  • As palavras-chave não são sensíveis a maiúsculas e minúsculas. DATABASE, Database, e database são a mesma palavra-chave.
  • Muitas palavras-chave têm sinónimos. Server e Data Source definem o mesmo valor. O artigo Opções de Ligação lista os sinónimos para cada palavra-chave.
  • Quando uma palavra-chave aparece mais do que uma vez, o último valor vence. Sinónimos contam como a mesma palavra-chave.
  • O condutor ignora os espaços em torno das palavras-chave e dos valores não aspas.
  • Um ponto e vírgula final é opcional.
  • Uma palavra-chave que o condutor não reconhece aparece ArgumentException com a mensagem Keyword not supported.

Os valores podem ser sensíveis a maiúsculas e minúsculas, dependendo da palavra-chave. Uma palavra-passe é sensível a maiúsculas e minúsculas. Encrypt=STRICT e Encrypt=strict são iguais.

Este programa mostra como o construtor normaliza palavras-chave, resolve um duplicado e cita caracteres especiais. O separador .NET Framework utiliza C# 7.3. Para criar um projeto que execute as amostras, veja Criar o projeto.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

A saída é:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

A primeira linha mostra cada sinónimo substituído pela sua palavra-chave canónica: server por Data Source, DATABASE por Initial Catalog, uid por User ID, por , e timeout por Connect Timeout.

Valores de citação

Inclua um valor entre aspas duplas (") ou aspas simples (') quando contém ponto e vírgula, começa ou termina com um espaço, ou começa ou termina com aspas. Dentro de um valor citado, escreva a aspas anexa duas vezes.

Value Forma de corda de ligação
a;b Password="a;b"
abc' Password="abc'"
say "hi" Password='say "hi"'
a;b'c"d Password="a;b'c""d"

As regras de citação são fáceis de errar. Defina os valores através das propriedades SqlConnectionStringBuilder e deixe o construtor colocá-los entre aspas. Para mais informações, consulte Construir cadeias de ligação em segurança.

Especificar valores booleanos

Palavras-chave que assumem um valor booleano aceitam true, false, yes e no, independentemente de maiúsculas/minúsculas. Integrated Security também aceita sspi, o que significa true. O construtor escreve True ou False.

Use palavras-chave de outros condutores

Microsoft. O Data.SqlClient não aceita palavras-chave ODBC ou OLE DB como Driver e Provider. Remova estas palavras-chave quando mover uma cadeia de ligação de outro driver. System.Data.SqlClientas strings de ligação funcionam no Microsoft.Data.SqlClient, com estas diferenças:

  • Encrypt tem por defeito o valor Mandatory no Microsoft.Data.SqlClient. Um servidor sem um certificado fidedigno falha na validação do certificado. Instala um certificado de confiança no servidor.
  • Em .NET, Network Library, Connection Reset, e Transparent Network IP Resolution não são suportados. Remova-as.
  • Context Connection=true não é suportado.
  • Asynchronous Processing não é uma palavra-chave suportada e gera o erro ArgumentException. Tira-o. Métodos assíncronos funcionam sem isso.
  • Type System Version=SQL Server 2000 não é suportado. Criar a ligação lança ArgumentException. Utilize Latest, SQL Server 2012, SQL Server 2008, ou SQL Server 2005.

Conteúdo relacionado

  • Última atualização a