Guia de solução de problemas do SqlClient

Baixar ADO.NET

Exceções na conexão com o SQL Server

Existem vários motivos pelos quais a conexão pode não ser estabelecida. Aqui estão algumas dicas de solução de problemas que podem ser usadas como um guia para analisar e solucionar vários deles.

Não é possível carregar a biblioteca SNI (Interface de Rede do Servidor) nativa

Problemas em aplicativos .NET Framework

Rastreamento de pilha observado:

TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.SNILoadHandle' threw an exception.
DllNotFoundException: Unable to load DLL 'Microsoft.Data.SqlClient.SNI.x64.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E)

TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.SNILoadHandle' threw an exception.
DllNotFoundException: Unable to load DLL 'Microsoft.Data.SqlClient.SNI.x86.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E)

SNI é a biblioteca nativa do C++ da qual o SqlClient depende para várias operações de rede quando executado no Windows. Em aplicativos .NET Framework criados com o SDK de Projeto do MSBuild, as DLLs nativas não são gerenciadas com comandos de restauração. Portanto, um arquivo ".targets" está incluído no pacote NuGet "Microsoft.Data.SqlClient.SNI" que define as operações de "Cópia" necessárias.

O arquivo ".targets" incluído é referenciado automaticamente quando uma dependência direta é feita para a biblioteca "Microsoft.Data.SqlClient". Em cenários nos quais uma referência transitiva (indireta) é feita, esse arquivo ".targets" deve ser referenciado manualmente para garantir que as operações de "Cópia" possam ser executadas quando necessário.

Solução recomendada: verifique se o arquivo ".targets" está referenciado no arquivo de projeto do aplicativo para garantir que as operações "Copy" sejam executadas. Um exemplo de edições em um arquivo de projeto pode ser encontrado neste problema relacionado do GitHub.

Esses destinos cobrem apenas aqueles conhecidos e comumente usados pela Microsoft. Se uma ferramenta ou um aplicativo externo definir destinos personalizados para copiar binários, novos destinos deverão ser definidos pelos mantenedores da ferramenta para garantir que DLLs SNI nativas sejam copiadas com os binários Microsoft.Data.SqlClient.dll e estejam disponíveis ao executar aplicativos clientes.

Problemas em aplicativos .NET Core

Rastreamento de pilha observado:

System.TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.TdsParser' threw an exception.
---> System.TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.SNILoadHandle' threw an exception.
---> System.DllNotFoundException: Unable to load shared library 'Microsoft.Data.SqlClient.SNI.dll' or one of its dependencies.

Observação

Esse erro pode ocorrer apenas em aplicativos do Windows. Se ele ocorrer em um ambiente Unix, seu aplicativo precisará ser construído para ser direcionado adequadamente a um runtime do Unix, e não ao Windows.

SNI é a biblioteca nativa do C++ da qual o SqlClient depende para várias operações de rede quando executado no Windows. O Microsoft.Data.SqlClient não gerencia o carregamento/descarregamento dessa biblioteca no .NET Core.

Solução recomendada: verifique se as permissões "Executar" foram concedidas no sistema de arquivos em que as bibliotecas de runtime nativas são carregadas no processo do .NET Core. Se isso não resolver o problema, você poderá registrar um problema no repositório dotnet/runtime para obter mais suporte.

Erros da SNI nativa (pdb não encontrado)

Rastreamento de pilha observado:

An assembly specified in the application dependencies manifest (sql2csv.deps.json) was not found:
  package: 'Microsoft.Data.SqlClient.SNI.runtime', version: '2.0.0'
  path: 'runtimes/win-x64/native/Microsoft.Data.SqlClient.SNI.pdb'

Solução recomendada: verifique se o aplicativo cliente faz referência à versão v2.1.0 mínima do pacote Microsoft.Data.SqlClient. Ao usar o EF Core, adicione uma referência a essa versão do pacote do Microsoft.Data.SqlClient diretamente para substituir a dependência.

Erros de resolução de nome do host

Rastreamento de pilha observado:

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible.
Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
(provider: TCP Provider, error: 0 - No such host is known.)

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible.
Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
(provider: TCP Provider, error: 35 - An internal exception was caught)

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible.
Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
(provider: TCP Provider, error: 35 - An internal exception was caught)
 ---> System.Net.Internals.SocketExceptionFactory+ExtendedSocketException (00000005, 0xFFFDFFFF): Name does not resolve

Possíveis motivos

• O protocolo TCP/Pipes Nomeados não está habilitado no SQL Server

  Solução recomendada: habilite o protocolo TCP/Pipes Nomeados na instância do SQL Server por meio do console do SQL Server Configuration Manager.

• Nome do host não conhecido

  Solução recomendada: verifique se o nome do host é resolvido para o endereço IP do servidor do cliente em que a conexão está sendo iniciada.

Erros de fase de logon

Rastreamentos de pilha observados:

Microsoft.Data.SqlClient.SqlException (0x80131904): A connection was successfully established with the server, but then an error occurred during the pre-login handshake.
(provider: SSL Provider, error: 31 - Encryption(ssl/tls) handshake failed)
System.IO.EndOfStreamException: End of stream reached

A connection was successfully established with the server, but then an error occurred during the login process.
(provider: SSL Provider, error: 0 - The target principal name is incorrect.)

Microsoft.Data.SqlClient.SqlException (0x80131904): Connection Timeout Expired. The timeout period elapsed during the post-login phase. The connection could have timed out while waiting for server to complete the login process and respond; Or it could have timed out while attempting to create multiple active connections.
The duration spent while attempting to connect to this server was - [Pre-Login] initialization=837; handshake=394; [Login] initialization=3; authentication=15; [Post-Login] complete=1027;
---> System.ComponentModel.Win32Exception (258): Unknown error 258
at Microsoft.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection, Action1 wrapCloseInAction)

Possíveis motivos e soluções

• O SQL Server não dá suporte ao TLS 1.2

  Esse erro normalmente ocorre em ambientes de cliente, como contêineres de imagem do Docker, clientes UNIX ou clientes do Windows, em que o TLS 1.2 é o protocolo TLS mínimo com suporte.

  Solução recomendada: instale as atualizações mais recentes das versões com suporte do SQL Server¹ e verifique se o protocolo TLS 1.2 está habilitado no servidor.

  ¹ Confira o Ciclo de vida de suporte do driver SqlClient para ver uma lista de versões do SQL Server com suporte em diferentes versões do Microsoft.Data.SqlClient.

  Solução não segura: defina as configurações de TLS/SSL no ambiente de cliente/imagem do Docker para se conectar ao TLS 1.0.

  MinProtocol = TLSv1
  CipherString = DEFAULT@SECLEVEL=1
  

  Observação

  Ao se conectar ao Microsoft.Data.SqlClient v2.0+ por meio de um ambiente Windows/Linux com TLS 1.0 ou TLS 1.1, uma mensagem de aviso de segurança será gerada se o SQL Server de destino e o cliente não puderem negociar, no mínimo, o TLS versão 1.2 ao estabelecer a conexão: Security Warning: The negotiated <TLS1.0 | TLS1.1> is an insecure protocol and is supported for backward compatibility only. The recommended protocol version is TLS 1.2 and later.

• Criptografia imposta do SQL Server

  Se o servidor de destino é uma instância SQL do Azure ou um SQL Server local com a propriedade "Forçar Criptografia" ativada, uma conexão criptografada é feita, para a qual o cliente deve estabelecer confiança com o servidor.

  Solução recomendada: há duas opções disponíveis para corrigir esse problema:

  1. Instalar o certificado TLS/SSL do SQL Server de destino no ambiente do cliente. Ele é validado se a criptografia é necessária.
  2. (Menos seguro) Defina a propriedade "TrustServerCertificate=true" na cadeia de conexão.

  Solução não segura: desabilite a configuração "Forçar Criptografia" no SQL Server.

• Certificados TLS/SSL não assinados com SHA-256 ou maior.

  Solução recomendada: gere um novo certificado TLS/SSL para o servidor cujo hash seja assinado com pelo menos o algoritmo de hash SHA-256.

• Conjuntos de criptografia rigorosamente restritos no Linux com o .NET 5+

  O .NET 5 introduziu uma alteração interruptiva para clientes Linux, em que uma lista rigorosamente restrita de conjuntos de criptografia permitidos é usada por padrão. Talvez seja necessário expandir a lista de conjuntos de criptografia padrão para aceitar clientes herdados (ou contatar servidores herdados), especificando um valor CipherSuitePolicy ou alterando o arquivo de configuração do OpenSSL.

  Leia mais sobre Conjuntos de criptografia TLS padrão para .NET no Linux para uma ação recomendada.

Microsoft.Data.SqlClient.SqlException (0x80131904): A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
 ---> System.ComponentModel.Win32Exception (0x80090325): The certificate chain was issued by an authority that is not trusted.

• Criptografia imposta do SQL Server

  Se o servidor de destino é uma SQL Server local com a propriedade "Forçar Criptografia" ativada e um certificado autoassinado, uma conexão criptografada é feita, para a qual o cliente deve estabelecer confiança com o servidor.

  Solução recomendada: há duas opções disponíveis para corrigir esse problema:

  1. Instalar o certificado TLS/SSL do SQL Server de destino no ambiente do cliente. Ele é validado se a criptografia é necessária.
  2. (Menos seguro) Defina a propriedade "TrustServerCertificate=true" na cadeia de conexão.

  Solução não segura: desabilite a configuração "Forçar Criptografia" no SQL Server.

Erros de esgotamento do pool de conexões

Rastreamento de pilha observado:

System.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.

Possíveis motivos e soluções

O aplicativo cliente está abrindo mais conexões do que o pool de conexão pode manter em atividade em determinado momento.

Solução recomendada: configure a propriedade de conexão "Tamanho Máximo do Pool" para um valor mais alto e feche as conexões não utilizadas em tempo hábil.

Contatar o suporte

Se este guia não resolver seus problemas de conectividade, você poderá exibir os problemas existentes no repositório dotnet/sqlclient e abrir um novo problema, se necessário.