Opções de ligação para Microsoft. Data.SqlClient

As opções de ligação do Microsoft.Data.SqlClient controlam a forma como o controlador estabelece, identifica, encaminha, repete as tentativas e gere o agrupamento de uma ligação. Defina-as numa cadeia de ligação ou nas propriedades SqlConnectionStringBuilder correspondentes.

Para autenticação Microsoft Entra ID, consulte autenticação Microsoft Entra ID. Para definições TLS, veja Encriptação e validação de certificados.

Definir opções com SqlConnectionStringBuilder

Utilize o construtor em vez de concatenar fragmentos da cadeia de ligação:

var builder = new SqlConnectionStringBuilder
{
    DataSource = "tcp:sql.example.com,1433",
    InitialCatalog = "Orders",
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Mandatory,
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    ConnectRetryCount = 3,
    ConnectRetryInterval = 10,
    MultiSubnetFailover = true,
};

O código utiliza nomes de propriedades dos construtores. As tabelas usam formas comuns de escrever cadeias de ligação. O condutor também aceita pseudónimos documentados.

Opções de limite de tempo

Keyword Default Comportamento Versão
Connect Timeout 15 segundos Limita o tempo para estabelecer uma ligação. Quando o pool está em Max Pool Size, também limita o tempo de espera por uma ligação utilizável do pool. Connection Timeout e Timeout são pseudónimos. Todas as versões de Microsoft.Data.SqlClient
Command Timeout 30 segundos Define o timeout padrão para comandos associados à ligação. Defina CommandTimeout num comando quando uma operação precisar de um limite diferente. Um valor de 0 não tem limite de tempo e pode deixar o trabalho à espera indefinidamente. Microsoft. Data.SqlClient 2.1 e versões posteriores

Os timeouts de ligação e comandos medem trabalhos diferentes. Connect Timeout Não limita a execução da consulta. Command Timeout não limita a autenticação nem a espera por uma ligação agrupada.

A CancellationToken é independente de ambas as definições. Passe-o para OpenAsync, para a execução de comandos e para os métodos de leitura, para que o autor da chamada deixe de esperar antes de o tempo limite expirar.

Identidade da carga de trabalho e opções de roteamento

Keyword Default Comportamento Versão
Application Name Nome definido pelo fornecedor Identifica a carga de trabalho em sessões do SQL Server, auditorias e diagnósticos. Use um nome estável e de baixa cardinalidade para cada carga de trabalho implementada. Todas as versões de Microsoft.Data.SqlClient
Application Intent ReadWrite ReadOnly solicita o encaminhamento para leitura quando o destino e o grupo de disponibilidade estão configurados para tal. Não torna as instruções SQL apenas de leitura. Todas as versões de Microsoft.Data.SqlClient

Application Intent=ReadOnly é normalmente associado a um listener de grupo de disponibilidade ou a um ponto final de serviço que suporta o encaminhamento de leitura. Ver Alta disponibilidade e recuperação em caso de desastre.

Opções de rede e pacotes

Keyword Default Comportamento Versão
Packet Size 8.000 bytes Define o tamanho do pacote de rede Tabular Data Stream (TDS). Os valores suportados são de 512 a 32.768 bytes. Mantém o padrão, a menos que as medições de carga de trabalho e a configuração do servidor justifiquem uma alteração. Todas as versões de Microsoft.Data.SqlClient
MultiSubnetFailover false Utiliza tentativas paralelas de ligação TCP para endereços IP associados a um ponto terminal com vários endereços. Defina-o como true para os pontos finais do SQL do Azure, os ouvintes de grupos de disponibilidade e as instâncias de cluster de ativação pós-falha acedidas através de TCP. Todas as versões de Microsoft.Data.SqlClient

MultiSubnetFailover=true não é suportado com instâncias nomeadas, protocolos não-TCP, espelhamento de bases de dados ou endpoints configurados com mais de 64 endereços IP. É seguro para um endpoint TCP de IP único.

Microsoft.Data.SqlClient 7.0 também dispõe de um comutador AppContext aplicável a todo o processo que pode fazer com que todas as ligações se comportem como se MultiSubnetFailover=true estivesse definido. A cadeia de ligação por defeito mantém-se false quando esse switch não está ativado. Veja os switches do AppContext no SqlClient.

Opções de agrupamento

Keyword Default Comportamento Versão
Pooling true Reutiliza ligações físicas para configurações de ligação que correspondam entre si. Desative-o apenas para diagnóstico ou para uma carga de trabalho específica que não possa ser agrupada em segurança. Todas as versões do Microsoft.Data.SqlClient
Min Pool Size 0 Mantém pelo menos este número de ligações físicas numa piscina depois de a criar. Um valor positivo pode manter as sessões da base de dados abertas até ao fim do pool ou processo. Todas as versões do Microsoft.Data.SqlClient
Max Pool Size 100 Limita as ligações físicas numa só piscina. Os pedidos esperam até Connect Timeout quando o conjunto está cheio. Todas as versões do Microsoft.Data.SqlClient
Load Balance Timeout 0 segundos Descarta uma ligação quando regressa ao pool se a sua idade exceder este valor. Connection Lifetime é um pseudónimo. 0 Desativa a remoção baseada na idade. Todas as versões de Microsoft.Data.SqlClient
Pool Blocking Period Auto Controla se o pool relança temporariamente uma falha de login em cache. Autodesativa o período de bloqueio para endpoints SQL do Azure reconhecidos e ativa-o para outros endpoints. Todas as versões do Microsoft.Data.SqlClient
Enlist true Regista automaticamente uma ligação aberta na transação ambiente System.Transactions . Todas as versões do Microsoft.Data.SqlClient

As definições do pool aplicam-se a cada pool distinto, não a todo o processo ou servidor de base de dados. Antes de levantar Max Pool Size, confirme que as ligações e leitores estão prontamente eliminados e que a base de dados pode aceitar o total resultante em cada instância de aplicação.

Para chaves de pool, comportamento dos tokens, períodos de bloqueio, eliminação e diagnósticos, consulte agrupamento de ligações do SQL Server.

Opções de recuperação de ligação

Keyword Default Comportamento Versão
Connect Retry Count 1 Define a contagem de tentativas para falhas transitórias qualificadas durante a ligação inicial e para restaurar uma ligação ociosa quebrada. O padrão efetivo é 2 para endpoints SQL do Azure reconhecidos e 5 para endpoints reconhecidos no Azure Synapse e on-demand. 0 desativa essas novas tentativas. Todas as versões de Microsoft.Data.SqlClient
Connect Retry Interval 10 segundos Define o atraso antes das tentativas posteriores de ligação inicial ou de recuperação após inatividade. Os valores válidos são de 1 a 60 segundos. Todas as versões de Microsoft.Data.SqlClient

A primeira tentativa durante a recuperação da ligação é imediata. Connect Retry Interval Aplica-se antes de tentativas posteriores. Para contornar a retentativa inicial-aberta incorporada para uma operação, use uma sobrecarga aberta com OpenWithoutRetry.

Estas palavras-chave não tentam novamente um comando que falha enquanto está a correr. Utilize lógica de repetição configurável para uma política personalizada para abertura ou comandos. Tente novamente os comandos apenas quando for seguro repetir os seus efeitos.

Identidade do servidor e opções de certificado

Estas opções respondem a requisitos específicos de certificado ou de nomenclatura do Kerberos. Não substituem a autenticação normal nem a validação de certificados.

Keyword Default Comportamento Versão
Host Name In Certificate Nome do anfitrião do servidor Fornece o esperado Nome Comum (CN) ou Nome Alternativo de Sujeito (SAN) quando a ligação utiliza um alias DNS que difere do certificado. Microsoft. Data.SqlClient 5.0 e versões posteriores
Server Certificate Empty Fornece um ficheiro PEM, DER ou CER que deve corresponder exatamente ao certificado do servidor quando Encrypt=Mandatory ou Encrypt=Strict. Microsoft. Data.SqlClient 5.1 e versões posteriores
Server SPN Derivado do nome do servidor Substitui o Nome Principal do Serviço (SPN) usado na autenticação integrada para o servidor principal. Configure-o apenas quando a nomenclatura Kerberos utilizada exigir um SPN explícito. Microsoft. Data.SqlClient 5.0 e versões posteriores
Failover Partner SPN Derivado do parceiro de failover Sobrepõe o SPN para um parceiro de failover de espelhamento de base de dados. O espelhamento de bases de dados está obsoleto. Use grupos de disponibilidade para novas implementações. Microsoft. Data.SqlClient 5.0 e versões posteriores

Host Name In Certificate altera o nome usado para comparação de certificados. Não confia num emissor não confiável. Server Certificate associa de forma fixa um ficheiro de certificado específico e exige uma atualização da aplicação quando esse certificado é substituído.

Sobreposições SPN incorretas podem impedir a autenticação por Kerberos ou enfraquecer a verificação de identidade pretendida. Corrija o DNS e o registo do SPN em vez de definir substituições, sempre que possível.

Mantenha as cordas de ligação pequenas. Adiciona uma opção apenas quando conseguires indicar que comportamento muda e como a carga de trabalho verifica esse comportamento.

Alterações na opção de revisão

Antes de mudar uma opção em produção:

  1. Regista a cadeia de ligação atual, a versão do driver, o tipo de endpoint e o problema observado.
  2. Muda um comportamento de cada vez.
  3. Teste o estabelecimento da ligação, a autenticação, a validação de certificados, o pooling, o failover, o cancelamento e a execução de consultas.
  4. Meça ligações hard, esperas em pool, latência de ligação e números de erro.
  5. Confirma a definição em cada instância implementada.

As cadeias de conexão fazem parte da chave do pool. Um lançamento em fases pode criar temporariamente pools antigos e novos, o que aumenta o número total de ligações físicas à base de dados.

Conteúdo relacionado

  • Last updated on