Resolver problemas do Microsoft OLE DB Driver for SQL Server

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada SQL do AzureBanco de Dados SQL do Azure Synapse Analyticsno Microsoft Fabric

Use este artigo para identificar a fase de falha de uma operação OLE DB, escolher a próxima verificação e encontrar instruções detalhadas de resolução de problemas. A orientação utiliza o fornecedor atual, MSOLEDBSQL19. Para defeitos específicos de lançamento e alterações de atualização, veja Problemas conhecidos e Diferenças principais de versão.

Identificar o sintoma

Capture a descrição completa do erro e todos os registos de erro disponíveis antes de alterar as definições. Um top-level HRESULT, como DB_E_ERRORSOCCURRED, não identifica a causa por si só. Registe se a falha ocorre ao carregar o provedor, abrir uma conexão, executar um comando, obter dados ou confirmar uma transação.

Para falhas de ligação, compare a aplicação com um teste de ligação Universal Data Link (UDL). Use o mesmo computador, fornecedor, arquitetura de processos, identidade de autenticação, servidor, base de dados e definições de encriptação. Um teste bem-sucedido com outro fornecedor ou identidade não comprova que a configuração da aplicação funciona.

Registo de fornecedores e arquitetura

Erros como Provider não pode ser encontrado ou REGDB_E_CLASSNOTREG (0x80040154, Classe não registada) indicam o carregamento do fornecedor antes da autenticação do SQL Server.

1. Verifique qual é o provedor que a aplicação solicita. MSOLEDBSQL19 e MSOLEDBSQL identificam diferentes versões principais. Instalar o driver atual não altera a escolha do fornecedor da aplicação. Siga os passos de migração se a aplicação ainda solicitar outro fornecedor.
2. Verifique a arquitetura do processo que aloja a aplicação. Uma aplicação de 32 bits precisa do fornecedor de 32 bits, mesmo no Windows de 64 bits. Para um serviço ou tarefa agendada, verifique o executável e a conta utilizados nesse host, não apenas o seu ambiente de desenvolvimento.
3. Instale ou repare o driver com o instalador suportado no computador que executa a aplicação. O instalador x64 inclui binários de driver de 64 e 32 bits. Verifique as dependências necessárias em Instalar o controlador OLE DB e Requisitos do sistema. Não copies bibliotecas de drivers de outro computador como substituto da instalação.
4. Repita o teste UDL com a arquitetura e o fornecedor correspondentes. Se funcionar mas a aplicação ainda não conseguir carregar o fornecedor, compare a seleção eficaz do fornecedor da aplicação e a arquitetura do host com o teste.

Se o erro mencionar especificamente adal.dll, consulte o problema conhecido da biblioteca de autenticação em vez de o considerar como um fornecedor do SQL Server em falta.

Falhas de login e autenticação

Distinga-se uma rejeição de login de servidor de uma falha em obter credenciais ou estabelecer uma ligação encriptada. Leia o texto completo do erro, incluindo qualquer erro incorporado do prestador.

1. Para o erro 18456 do SQL Server, peça ao administrador da base de dados para inspecionar a entrada e o estado correspondentes do registo de erro do servidor. Verifique o modo de autenticação, o estado de login, a base de dados solicitada e o acesso à base de dados usando MSSQLSERVER_18456. Não assumas que todas as rejeições de login significam uma palavra-passe incorreta.
2. Para autenticação integrada, confirme a identidade sob a qual a aplicação é executada. Uma conta de serviço ou conta de tarefas agendadas pode diferir do utilizador que testou com sucesso a ligação. Se a mensagem incluir Não é possível gerar contexto SSPI, siga a resolução de problemas do Security Support Provider Interface (SSPI) e o suporte ao Service Principal Name (SPN).
3. Para o Microsoft Entra ID, verifique se o método de autenticação selecionado se adequa ao ambiente de execução da aplicação e se a sua identidade tem acesso à base de dados alvo. Revise as definições específicas do método e as restrições de tokens de acesso no Use Microsoft Entra ID. Não combine um token de acesso com propriedades de autenticação ou credenciais conflitantes.
4. Compare as definições efetivas com a tabela correta de palavras-chave da cadeia de ligação. IDBInitialize::Initialize, IDataInitialize::GetDataSource, e os Objetos de Dados ActiveX (ADO) utilizam tabelas de palavras-chave diferentes. Consulte a tabela da interface que a sua aplicação utiliza.

O texto O nome principal alvo está incorreto pode aparecer em diferentes contextos. Se acompanhar Cannot generate SSPI context, investigue a autenticação do Windows e os SPNs. Se o erro identificar o certificado ou o handshake de encriptação, use a secção seguinte.

Falhas no certificado TLS

Erros de Segurança da Camada de Transporte (TLS) podem ocorrer antes de um login chegar ao SQL Server. O driver atual permite a encriptação obrigatória por defeito, por isso uma atualização pode expor um problema de confiança de certificado ou de nome que uma configuração de ligação mais antiga não detetou.

1. Relativamente a A cadeia de certificados foi emitida por uma autoridade que não é de confiança, verifique o certificado apresentado pelo SQL Server e a cadeia de emissão do certificado na qual o computador cliente confia. Configure um certificado de servidor válido e instale os certificados raiz e intermédios de confiança necessários através do processo de gestão de certificados da sua organização.
2. Em caso de incompatibilidade no nome do certificado, compare o nome do servidor ou do listener que a aplicação utiliza com os nomes presentes no certificado. Use um certificado que cubra o nome da ligação pretendido. Se a aplicação usar intencionalmente um nome de ligação diferente, revise a propriedade documentada HostNameInCertificate antes de configurar o nome esperado do certificado.
3. Verifique as definições efetivas de encriptação e validação, incluindo as definições do registo. Revise as tabelas de encriptação e validação de certificados para verificar a precedência e Strict o comportamento. No Strict modo, o driver valida o certificado independentemente da definição de trust-server-certificate.
4. Se a falha começou durante a migração, verifique a resolução de problemas relativa à versão principal, incluindo o tipo de valor da propriedade de encriptação e a restrição à utilização de ServerCertificate fora do modo Strict.

Utilize os requisitos de certificado para o SQL Server e a resolução de problemas de cadeia de certificados não fidedigna para verificações detalhadas. Mantenha a encriptação e a validação de certificados ativadas em produção. Desativar qualquer um deles não resolve um problema de implementação de certificados.

Falhas na descoberta de rede e instâncias

Para servidor não encontrado, erro ao localizar o servidor/a instância especificado(a) ou erros de ligação recusada, identifique o endpoint que a aplicação está a tentar contactar.

1. Verifique o nome do servidor, o nome da instância e a porta de escuta configurada com o administrador da base de dados. Confirme que o serviço de base de dados está a correr e que o protocolo e ouvinte pretendidos estão ativados. Não assumas que todas as instâncias ouvem na porta 1433.
2. Para uma ligação TCP remota, teste o endpoint conhecido utilizando o formato server-name do controlador tcp:<server>,<port>. Mantém as mesmas definições de autenticação, base de dados e encriptação. Consulte Palavras-chave da cadeia de conexão para a palavra-chave do servidor aplicável à sua interface.
3. Se o host e a porta especificados explicitamente funcionarem, mas a instância nomeada não, investigue o SQL Server Browser e a deteção de instâncias. Verifique o serviço de navegador e o caminho da porta 1434 do Protocolo de Datagramas de Utilizador (UDP) onde é usada a descoberta do navegador.
4. Se o endpoint explícito também falhar, verifique a resolução do Sistema de Nomes de Domínio (DNS), o encaminhamento e o acesso do firewall à porta de escuta real a partir do host da aplicação. Siga as orientações sobre erros de ligação relacionados com a rede ou específicos da instância, em vez de alterar várias definições de ligação ao mesmo tempo.

Para uma escuta de um grupo de disponibilidade, consulte também o suporte de alta disponibilidade e recuperação após desastre. No caso do LocalDB, utilize o suporte para LocalDB para verificar a instância local e o contexto do utilizador, em vez de aplicar os passos de deteção remota por TCP.

Erros de parâmetros e de conversão de dados

Se a ligação abrir mas a execução de comandos ou a recuperação de dados falharem, reduza a reprodução ao comando e valor falhados. Preserve o tipo de dado original, o comprimento, o estado nulo e a codificação de caracteres ao substituir dados sensíveis.

1. Compare cada ? marcador de parâmetro com o seu ordinal de ligação, direção e metadados. Quando utilizar ICommandWithParameters::SetParameterInfo, faça corresponder o tipo de origem de SQL ao comando ou procedimento armazenado. Não assuma que os metadados dos parâmetros são sempre derivados automaticamente. Revise os parâmetros do comando para restrições de derivação e comportamento dos parâmetros de saída.
2. Inspecione os estados de ligação dos acessórios e o estado e comprimento de cada valor retornado, não apenas o valor global HRESULT. Para falhas na definição de propriedades, inspecione o dwStatus de cada propriedade. Um retorno com êxito parcial, como DB_S_ERRORSOCCURRED, pode exigir a inspeção do array de estado, mesmo quando não está disponível nenhum objeto de erro. Ver códigos de retorno.
3. Para conversão ou truncamento, compare o tipo e tamanho do buffer do consumidor com os metadados reais da coluna ou parâmetro. Verifique a precisão e a escala para valores numéricos, intervalos válidos e frações de segundo para valores de data/hora, e comprimentos de bytes para buffers de caracteres. Investigue DBSTATUS_E_CANTCONVERTVALUEe não trate DBSTATUS_S_TRUNCATED como um valor completo. Use mapeamento de tipos de dados, obtenção de linhas e conversões de data e hora para as regras aplicáveis.
4. Se aparecerem em falta parâmetros de saída limitados, esgote os conjuntos de linhas retornados antes de os ler. Consulte Utilizar IMultipleResults para processar vários conjuntos de resultados. Para parâmetros de saída transmitidos, consuma ou liberte fluxos pendentes antes de solicitar o próximo resultado, conforme descrito no suporte de streaming para parâmetros de saída.

Para mapeamentos específicos do ADO, consulte Utilizar o ADO com o controlador OLE DB e as restrições de autenticação em DataTypeCompatibility em Utilizar o Microsoft Entra ID. Não adiciones uma configuração de compatibilidade sem verificares ambas.

Para cadeias estreitas corrompidas numa coluna sql_variant após uma atualização do driver, reveja o problema conhecido do SSVARIANT e o procedimento de recuperação existente antes de modificar os dados armazenados.

Perda de conexão e tempos limite excedidos

Regista quando a ligação funcionou pela última vez, qual operação falhou e quanto tempo essa operação durou. Distingua estes casos antes de alterar as definições de nova tentativa ou de timeout.

A resiliência da ligação inativa não disponibiliza novas tentativas na ligação inicial nem a reexecução automática de comandos e transações arbitrárias. Para uma falha transitória confirmada, use novas tentativas da aplicação limitadas, com um atraso entre elas, e registe cada tentativa. Não tente repetidamente erros de carregamento do fornecedor, credenciais rejeitadas ou falhas de validação de certificados sem corrigir a causa.

Diagnóstico e rastreio

Recolha diagnósticos no ponto de falha, antes que chamadas de fornecedores não relacionadas substituam a informação de erro.

1. Capture a operação com falha, a data/hora e o fuso horário, o tempo decorrido e HRESULT. Para consumidores nativos de OLE DB, recupere todos os registos disponíveis através de IErrorInfo e IErrorRecords, e não apenas a primeira descrição. Inclua SQLSTATE e o número de erro nativo do SQL Server quando este estiver disponível através de ISQLErrorInfo. Veja Recuperar informação de erro e detalhes de erro do SQL Server. Para ADO, capture a coleção da ligação Errors.
2. Recolha os estados por propriedade, por vinculação e por valor para métodos que reportam erros dessa forma. Um objeto de erro ausente não torna seguro ignorar um resultado de sucesso parcial.
3. Correlacione a falha do cliente com o registo de erros do servidor ou Eventos Estendidos. Quando disponível, regista ClientConnectionID e ActivityID. Uma falha antes do pré-login pode ocorrer sem um identificador de ligação do cliente.
4. Se os registos de erros não forem suficientes, use Aceder a informações de diagnóstico no registo de Eventos Alargados para o rastreio do controlador e a configuração da correlação. Recolhe um traço limitado em torno da reprodução e pare de traçar depois.

Quando escalar, inclua a versão do driver, o fornecedor solicitado, a arquitetura da aplicação e do processo, a versão do servidor, o método de autenticação, as definições de ligação eficazes, a fase de falha, os registos de erro e uma reprodução mínima. Indique se o teste UDL correspondente tem sucesso e se o problema afeta um host ou múltiplos.

Remova palavras-passe, tokens de acesso e outros segredos das definições de ligação e registos. Revise os vestígios de texto de consulta e dados sensíveis, armazene-os com acesso restrito e partilhe-os apenas através de um canal de suporte aprovado.

Conteúdo relacionado

• Início Rápido: Ligue-se e faça consultas com o Driver Microsoft OLE DB
• Problemas conhecidos
• Notas de lançamento
• Visão geral da resolução de problemas de conectividade ao SQL Server