Opções de AppContext no SqlClient

Aplica-se a: .NET Framework .NET .NET Standard

Baixar ADO.NET

A classe AppContext permite que o SqlClient forneça novas funcionalidades enquanto continua dando suporte a chamadores que dependem do comportamento anterior. Os usuários podem recusar alterações no comportamento definindo opções de AppContext específicas.

O SqlClient lê e armazena em cache cada switch na primeira vez que usa esse switch. Configure os switches na inicialização da aplicação, antes de usar qualquer tipo de SqlClient. Mudar um switch depois que o SqlClient armazenou seu valor em cache não tem efeito.

Habilitar MultiSubnetFailover por padrão

Aplica-se a: .NET Framework; .NET; .NET Standard

(Disponível a partir da versão 7.0)

Para definir MultiSubnetFailover=true globalmente sem modificar as strings de conexão individuais, configure o comutador Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault AppContext para true na inicialização da aplicação:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault", true);

Você também pode habilitar essa opção em seu App.Config:

<runtime>
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault=true" />
</runtime>

Quando habilitadas, todas as conexões se comportam como se MultiSubnetFailover=true estivesse definidas na cadeia de conexão. Essa opção está desabilitada por padrão.

Habilitar o multiplexatório de pacotes para leituras assíncronas

Aplica-se a: .NET Framework; .NET; .NET Standard

(Disponível a partir da versão 7.0)

A multiplexação de pacotes melhora o desempenho para grandes operações de leitura assíncrona, como ExecuteReaderAsync com grandes conjuntos de resultados, cenários de streaming ou recuperação de dados em massa. Esse recurso é controlado por dois comutadores AppContext opt-in. Definir ambos os interruptores para false habilitar o novo caminho assíncrono de processamento.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);

Por padrão, ambas as opções são true, o que preserva o comportamento existente (compatível).

Habilitar a extensão de funcionalidade do User Agent

Aplica-se a: .NET Framework; .NET; .NET Standard

(Disponível a partir da versão 7.0)

Quando o interruptor Switch.Microsoft.Data.SqlClient.EnableUserAgent AppContext está ativado, o driver envia os detalhes do agente de usuário para o servidor como parte da conexão. Essas informações auxiliam na solução de problemas e na quantificação do uso do driver por versão e sistema operacional. Essa opção está desabilitada por padrão. Para habilitá-lo, defina o switch AppContext para true na inicialização do aplicativo.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableUserAgent", true);

Habilitar a função de truncamento decimal

Aplica-se a: .NET Framework; .NET; .NET Standard

Começando com o Microsoft.Data.SqlClient 2.0, os dados decimais são arredondados por padrão, como é feito pelo SQL Server. Para ativar o comportamento anterior de truncamento, você pode configurar o interruptor Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal AppContext para true na inicialização da aplicação:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Habilitar a rede gerenciada no Windows

Aplica-se a: .NET; .NET Standard

(Disponível começando com a versão 2.0)

No Windows, o SqlClient usa uma implementação nativa da interface de rede SNI por padrão. Para permitir o uso de uma implementação de SNI gerenciada, defina o comutador Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows AppContext para true na inicialização da aplicação:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

Essa opção altera o comportamento do driver para usar a implementação de rede gerenciada em projetos do .NET Core 2.1+ e do .NET Standard 2.0+ no Windows, eliminando todas as dependências de bibliotecas nativas para a biblioteca Microsoft.Data.SqlClient. Sua utilização é exclusivamente para fins de teste e depuração.

Observação

Há algumas diferenças conhecidas em comparação com a implementação nativa. Por exemplo, a implementação gerenciada não suporta autenticação Windows sem domínio.

Desativar resolução de IP de rede transparente

Aplica-se a: .NET Framework

A TNIR (Resolução IP de Rede Transparente) é uma revisão do recurso MultiSubnetFailover existente. A TNIR afeta a sequência de conexão do driver quando o primeiro IP resolvido do nome do host não responde e quando existem vários IPs associados ao nome do host. A combinação de TransparentNetworkIPResolution e MultiSubnetFailover seleciona a sequência de conexão:

TransparentNetworkIPResolution	MultiSubnetFailover	Sequência de ligação
Verdadeiro	Verdadeiro	TransparentNetworkIPResolution é ignorado. O driver tenta, em paralelo, os endereços IP resolvidos pelo DNS e conclui a autenticação com o primeiro a responder.
Verdadeiro	Falso	O driver executa várias tentativas de conexão nos endereços IP resolvidos por DNS, com um mínimo de 500 milissegundos na primeira tentativa e tempos limite progressivamente maiores por tentativa, até que uma conexão seja bem-sucedida ou o Connect Timeout geral seja atingido.
Falso	Verdadeiro	O driver tenta, em paralelo, os endereços IP resolvidos pelo DNS e conclui a autenticação com o primeiro a responder.
Falso	Falso	O driver tenta cada endereço IP resolvido por DNS sequencialmente até que um seja bem-sucedido ou o Connect Timeout seja atingido.

TransparentNetworkIPResolutionestá ativado por padrão no .NET Framework, e MultiSubnetFailover está desativado por padrão. No .NET 5 e em versões posteriores, TransparentNetworkIPResolution não é uma palavra-chave reconhecida da cadeia de conexão, e defini-la (com qualquer valor) gera ArgumentException (KeywordNotSupported). Essas versões respeitam apenas MultiSubnetFailover. O restante desta seção (a substituição automática, os modos de falha no aviso seguinte e o interruptor AppContext) se aplica ao .NET Framework.

Dica

Defina MultiSubnetFailover=True em todas as cadeias de conexão, independentemente da versão do .NET ou de o destino ser o SQL do Azure ou o SQL Server local. MultiSubnetFailover=True seleciona um caminho de código de conexão paralela que encontra rapidamente a primeira réplica que responde. No .NET Framework, ele também ignora o loop de repetição sequencial por IP do TNIR, que é uma causa comum de longos atrasos de conexão e tempos limite de handshake de pré-autenticação.

No .NET Framework, quando TransparentNetworkIPResolution não está especificado na cadeia de conexão, o driver desativa automaticamente o TNIR quando a fonte de dados é um endpoint SQL do Azure reconhecido, quando a Authentication chave está definida para qualquer método Microsoft Entra ID (Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service PrincipalActive Directory Device Code Flow, Active Directory Managed Identity, , Active Directory MSI, Active Directory Defaultou Active Directory Workload Identity), ou quando a SqlConnection.AccessToken propriedade está definida. Para os sufixos de endpoint reconhecidos pelo driver, consulte a entrada TransparentNetworkIPResolution em SqlConnection.ConnectionString.

Um valor explícito TransparentNetworkIPResolution contorna esse comportamento automático: True ativa o TNIR e False desativa o TNIR incondicionalmente. Para restaurar o comportamento automático, remova a palavra-chave da cadeia de conexão. A substituição automática também não se aplica quando a string de conexão aponta para o SQL do Azure por meio de um CNAME personalizado ou um nome DNS personalizado cujo sufixo não é reconhecido como um ponto de extremidade do SQL do Azure. A substituição automática tem como alvo especificamente o SQL do Azure; ela não é aplicada ao SQL Server no local, portanto o TNIR fica ativado por padrão nesse caso.

Longos atrasos de conexão no .NET Framework

No .NET Framework, TransparentNetworkIPResolution=True (o padrão) pode causar longos atrasos na conexão e tempos limite de handshake de pré-autenticação sempre que o nome DNS de destino for resolvido para vários IPs e um dos IPs anteriores estiver inativo, desatualizado ou inacessível. O TNIR testa os IPs resolvidos sequencialmente e aumenta o tempo limite de cada tentativa a cada rodada até que o tempo limite geral Connect Timeout seja atingido. Normalmente, você observa um atraso de conexão inesperadamente longo que termina neste erro:

Connection Timeout Expired.  The timeout period elapsed while attempting to consume the pre-authentication handshake acknowledgement.  This could be because the pre-authentication handshake failed or the server was unable to respond back in time.

O padrão aparece em várias topologias:

• Banco de Dados SQL do Azure, Instância Gerenciada do SQL do Azure ou banco de dados SQL no Microsoft Fabric. O gateway do SQL do Azure encaminha cada autenticação para uma réplica de back-end. Quando uma conexão roteada falha, o TNIR tenta novamente o back-end roteado sem retornar ao gateway para ser redirecionado, o que aumenta o atraso durante um failover de back-end.
• SQL Server local atrás de um ouvinte de grupo de disponibilidade Always On cujo nome DNS é resolvido para vários IPs de réplica. Uma entrada DNS obsoleta ou uma réplica IP não saudável é testada sequencialmente antes que o TNIR chegue a uma réplica funcional.
• Instâncias de cluster de failover com um listener de cluster multi-sub-rede ou qualquer outra configuração em que o nome DNS de destino tenha vários registros A/AAAA (como DNS round-robin).

Para evitar esse comportamento, defina MultiSubnetFailover=True na cadeia de conexão:

MultiSubnetFailover=True

Essa recomendação funciona em todas as versões do .NET e abrange tanto SQL do Azure quanto SQL Server local. Quando MultiSubnetFailover=True, o driver ignora TransparentNetworkIPResolution, tenta os endereços IP resolvidos por DNS em paralelo e completa a autenticação com a primeira réplica responsiva. Apesar do nome, MultiSubnetFailover aplica-se a qualquer listener cujo nome DNS resolva para vários IPs de destino, independentemente de esses IPs estarem em sub-redes diferentes, e é seguro em servidores independentes cujo DNS resolva para um único IP.

Para controle em todo o processo sem editar cada string de conexão, use a opção Habilitar MultiSubnetFailover por padrão do AppContext.

Desabilitar TNIR com uma opção do AppContext

Para inverter o valor padrão de TransparentNetworkIPResolution de true para false no .NET Framework, configure o interruptor Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString AppContext para true na inicialização da aplicação. Esse switch só altera o valor padrão quando TransparentNetworkIPResolution não está na cadeia de conexão; ele não substitui um valor explícito.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);

Para obter mais informações sobre como definir essas propriedades, confira a documentação da Propriedade SqlConnection.ConnectionString.

Habilitar um tempo limite mínimo durante o logon

Aplica-se a: .NET Framework; .NET; .NET Standard

Para evitar que uma tentativa de login espere indefinidamente, você pode configurar o comutador Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin AppContext para true na inicialização do aplicativo:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);

Desabilitar o comportamento de bloqueio do ReadAsync

Aplica-se a: .NET Framework; .NET; .NET Standard

A partir da versão 3.0, ReadAsync roda de forma assíncrona. Versões anteriores rodam ReadAsync de forma síncrona e bloqueiam a thread de chamada no .NET Framework. Para controlar esse comportamento de bloqueio, configure o interruptor Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking AppContext para true ou false na inicialização da aplicação:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);

Ativar o comportamento nulo de rowversion

Aplica-se a: .NET Framework; .NET; .NET Standard

A partir da versão 3.0, quando uma rowversion tem um valor nulo, SqlDataReader retorna um valor DBNull em vez de um byte[] vazio. Para ativar o comportamento legado de retornar um byte[] vazio, ative a chave do AppContext Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior na inicialização do aplicativo.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);

Suprimir aviso TLS inseguro

Aplica-se a: .NET Framework; .NET; .NET Standard

(Disponível a partir da versão 4.0.1)

Ao usar Encrypt=false na string de conexão, o console exibe um aviso de segurança se a versão do TLS for 1.2 ou inferior. Suprima esse aviso ativando o seguinte interruptor AppContext na inicialização do aplicativo:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);

Ignorar Parceiro de Failover Fornecido pelo Servidor

Aplica-se a: .NET Framework; .NET; .NET Standard

(Disponível a partir das versões 5.1.8, 6.0.4 e 6.1.3)

Em caso de failover, as informações do parceiro de failover fornecidas pelo servidor têm preferência sobre as informações do parceiro de failover fornecidas na string de conexão. Para ignorar as informações do parceiro de failover fornecidas pelo servidor e considerar apenas as informações do parceiro de failover fornecidas na string de conexão, habilite esta opção do AppContext na inicialização do aplicativo:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner", true);

Impor o timeout de inatividade da conexão

Aplica-se a: .NET Framework; .NET; .NET Standard

A partir da versão 7.1.0-preview2, a palavra-chave Connection Idle Timeout da cadeia de conexão configura o tempo de inatividade, em segundos, após o qual uma conexão em pool pode ser removida (o padrão é 300; um valor de 0 desativa a expiração por inatividade). Uma conexão elegível é descartada em uma busca ou rotina de manutenção subsequente, portanto o momento exato pode variar conforme a implementação do pool e a cadência de manutenção. A palavra-chave só é imposta quando o comportamento legado de tempo limite de inatividade está desativado. Com o switch em seu valor padrão de true, o pool preserva o comportamento histórico e a palavra-chave não tem efeito.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior", false);

Ative o pool de conexões V2

Aplica-se a: .NET Framework; .NET; .NET Standard

A partir da versão 6.1, o SqlClient inclui uma implementação alternativa e experimental de pool de conexões (V2). O pool V1 permanece o padrão (o switch é padrão para false). Para aderir ao pool V2, habilite a chave Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2 do AppContext na inicialização do aplicativo.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2", true);

O pool de contagem aguarda em relação ao tempo limite de conexão

Aplica-se a: .NET Framework; .NET; .NET Standard

A partir da versão 7.1.0-preview2, o tempo gasto aguardando uma conexão do pool pode ser contabilizado no orçamento de Connect Timeout do chamador, de modo que a espera pelo pool e a tentativa de conexão de rede compartilhem um único tempo limite geral. Quando a opção é definida para seu valor padrão de false, as operações do pool recebem um orçamento completo Connect Timeout e a tentativa de conexão de rede recebe um orçamento completo adicional.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutForPoolWait", true);

Voltar para a alternância legada de failover em caso de erros de login

Aplica-se a: .NET Framework; .NET; .NET Standard

A partir da versão 7.1.0-preview2, ao se conectar com failover configurado, o SqlClient não alterna mais para o parceiro de failover em caso de erros SQL retornados durante a fase de login. Para voltar ao comportamento legado de alternância, habilite a opção AppContext Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors na inicialização do aplicativo. O interruptor por padrão é false.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors", true);

Respeite uma escala de zero explícita nos parâmetros vartime

Aplica-se a: .NET Framework; .NET; .NET Standard

Por padrão, o SqlClient envia uma escala de 7 quando você define explicitamente a escala como 0 para parâmetros datetime2, datetimeoffset ou time. Na versão 6.0 ou posterior, defina Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour para false na inicialização da aplicação para preservar a escala explícita de 0. O interruptor por padrão é true.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false);

Conteúdo relacionado

• Classe AppContext