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

As opções de conexão do Microsoft.Data.SqlClient controlam como o driver estabelece, identifica, direciona, tenta novamente e gerencia conexões em pool. Defina-as em uma cadeia de conexão ou por meio de SqlConnectionStringBuilder propriedades correspondentes.

Para autenticação do Microsoft Entra ID, veja autenticação do Microsoft Entra ID. Para as configurações de TLS, veja Criptografia e validação de certificados.

Definir opções com SqlConnectionStringBuilder

Use o construtor em vez de concatenar fragmentos da cadeia de conexã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 usa nomes de propriedades dos construtores. As tabelas usam grafias comuns de cadeia de conexão. O motorista também aceita pseudônimos documentados.

Opções de timeout

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

Os tempos limite de conexão e de comando medem operações diferentes. Connect Timeout Não limita a execução da consulta. Command Timeout Não limita a autenticação nem a espera por uma conexão em pool.

A CancellationToken é independente de ambas as configurações. Passe-o para OpenAsync, para a execução de comandos e para os métodos de leitura, para que o chamador possa deixar de esperar antes de o timeout expirar.

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

Keyword Padrão Behavior Versão
Application Name Nome definido pelo provedor Identifica a carga de trabalho em sessões do SQL Server, auditoria e diagnóstico. Use um nome estável e de baixa cardinalidade para cada carga de trabalho implantada. Todas as versões da Microsoft. Data.SqlClient
Application Intent ReadWrite ReadOnly solicita o roteamento de intenção de leitura quando o destino e o grupo de disponibilidade estão configurados para isso. Isso não torna os comandos SQL somente de leitura. Todas as versões da Microsoft. Data.SqlClient

Application Intent=ReadOnly normalmente é associado a um listener de grupo de disponibilidade ou a um endpoint de serviço que oferece suporte ao roteamento de leitura. Veja Alta disponibilidade e recuperação em caso de desastre.

Opções de rede e pacotes

Keyword Padrão Behavior 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. Mantenha 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 da Microsoft. Data.SqlClient
MultiSubnetFailover false Utiliza tentativas paralelas de conexão TCP com os endereços IP retornados para um endpoint com vários endereços. Defina-o como true para endpoints do SQL do Azure, ouvintes de grupos de disponibilidade e instâncias de cluster de failover atingidas por TCP. Todas as versões da Microsoft. Data.SqlClient

MultiSubnetFailover=true não é suportado com instâncias nomeadas, protocolos não-TCP, espelhamento de banco 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 possui uma opção AppContext válida para todo o processo que pode fazer com que todas as conexões se comportem como se MultiSubnetFailover=true. O padrão da cadeia de conexão permanece false quando esse switch não está ativado. Veja os switches do AppContext no SqlClient.

Opções de agrupamento

Keyword Padrão Behavior Versão
Pooling true Reutiliza conexões físicas para combinar configurações de conexão. Desative apenas para diagnóstico ou uma carga de trabalho medida que não possa acumular com segurança. Todas as versões da Microsoft. Data.SqlClient
Min Pool Size 0 Mantém pelo menos esse número de conexões físicas em uma piscina depois que a piscina é criada. Um valor positivo pode manter as sessões do banco de dados abertas até o fim do pool ou processo. Todas as versões da Microsoft. Data.SqlClient
Max Pool Size 100 Limita o número de conexões físicas em um pool. As solicitações aguardam por até Connect Timeout quando o pool está cheio. Todas as versões da Microsoft. Data.SqlClient
Load Balance Timeout 0 Segundos Descarta uma conexão quando ela retorna ao pool, se sua idade exceder esse valor. Connection Lifetime é um alias. 0 Desativa a remoção baseada na idade. Todas as versões da Microsoft. Data.SqlClient
Pool Blocking Period Auto Ele 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 o habilita para outros endpoints. Todas as versões da Microsoft. Data.SqlClient
Enlist true Registra automaticamente uma conexão aberta na transação ambiente System.Transactions . Todas as versões da Microsoft. Data.SqlClient

As configurações do pool se aplicam a cada pool distinto, não ao processo inteiro ou servidor de banco de dados. Antes de levantar Max Pool Size, confirme que as conexões e leitores são descartados prontamente e que o banco de dados pode aceitar o total resultante em cada instância de aplicação.

Para chaves de pool, comportamento de tokens, períodos de bloqueio, limpeza e diagnósticos, veja SQL Server connection pooling.

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

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

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

Essas palavras-chave não tentam novamente um comando que falha enquanto está rodando. Use lógica de retentativa configurável para uma política de abertura ou comando personalizada. Tente novamente os comandos somente quando for seguro repetir os efeitos deles.

Identidade do servidor e opções de certificado

Essas opções resolvem requisitos específicos de certificado ou de nomenclatura do Kerberos. Eles não substituem a autenticação normal e a validação de certificados.

Keyword Padrão Behavior Versão
Host Name In Certificate Nome do host do servidor Fornece o Nome Comum (CN) ou Nome Alternativo de Sujeito (SAN) esperado quando a conexão usa um alias DNS que difere do certificado. Microsoft. Data.SqlClient 5.0 e versões posteriores
Server Certificate Vazio Fornece um arquivo 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 da Entidade de Serviço (SPN) usado para autenticação integrada com o servidor principal. Configure isso apenas quando a nomeação Kerberos implantada exigir um SPN explícito. Microsoft. Data.SqlClient 5.0 e versões posteriores
Failover Partner SPN Derivado do parceiro de failover Substitui o SPN de um parceiro de failover do espelhamento de banco de dados. O espelhamento de banco de dados está obsoleto. Use grupos de disponibilidade para novas implantações. Microsoft. Data.SqlClient 5.0 e versões posteriores

Host Name In Certificate muda o nome usado para correspondência de certificados. Não confia em um emissor não confiável. Server Certificate vincula um arquivo de certificado específico e exige uma atualização do aplicativo quando esse certificado é substituído.

Substituições incorretas de SPN podem impedir a autenticação Kerberos ou enfraquecer a verificação de identidade prevista. Corrija DNS e registro de SPN em vez de configurar overrides quando possível.

Mantenha as cordas de conexão pequenas. Adicione uma opção apenas quando puder indicar qual comportamento ela muda e como a carga de trabalho verifica esse comportamento.

Mudanças na opção de revisão

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

  1. Registre a cadeia de conexão atual, a versão do driver, o tipo de endpoint e o problema observado.
  2. Mude um comportamento de cada vez.
  3. Teste o estabelecimento de conexão, a autenticação, a validação de certificado, o pool de conexões, o failover, o cancelamento e a execução de consultas.
  4. Meça conexões físicas, esperas no pool, latência de conexão e códigos de erro.
  5. Confirme a configuração em cada instância implantada.

As cadeias de conexão fazem parte da chave do pool. Uma implementação em etapas pode criar temporariamente pools antigos e novos, o que aumenta o número total de conexões físicas de banco de dados.

Conteúdo relacionado

  • Last updated on