Microsoft OLE DB Driver for SQL Server 的疑难解答

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Azure Synapse AnalyticsMicrosoft Fabric 中的 SQL 数据库

使用本文识别 OLE 数据库操作的失败阶段，选择下一个检查，并查找详细的故障排除说明。 该指南使用当前提供程序 MSOLEDBSQL19。 有关特定版本缺陷和升级变更，请参见 已知问题 和 主要版本差异。

识别症状

在更改设置前，请记录完整的错误描述和所有可用的错误记录。 顶层 HRESULT（如 DB_E_ERRORSOCCURRED）本身并不能指明原因。 记录故障是否发生在加载提供程序、打开连接、执行命令、获取数据或提交事务时。

症状 从这里开始
找不到提供者，或者课程没有注册。 提供者注册与架构
登录失败、访问被拒，或集成认证失败。 登录和认证失败
证书链不被信任，或者证书名称不匹配。 TLS证书故障
找不到服务器或实例，或者连接被拒绝。 网络和实例发现失败
参数失效、数值被截断，或者数据无法转换。 参数和数据转换错误
连接断开、恢复失败或超时到期。 连接丢失与超时
缺少错误详细信息，或者你需要向支持团队提供跟踪信息。 诊断与追踪

对于连接失败，可以将应用与 通用数据链（UDL）连接测试进行比较。 使用相同的计算机、提供商、进程架构、认证身份、服务器、数据库和加密设置。 用不同提供者或身份测试成功，并不能证明应用配置是否正常。

提供者注册与架构

如找不到提供者或REGDB_E_CLASSNOTREG（0x80040154类未注册）等错误表示在SQL Server认证前已加载提供者。

  1. 查看申请中要求的服务提供者。 MSOLEDBSQL19 和 MSOLEDBSQL 标识不同的主要版本。 安装当前驱动不会改变应用程序的服务提供者选择。 如果应用仍然要求更换供应商，请按照 迁移步骤 操作。
  2. 检查托管应用的进程架构。 32位应用程序即使在64位Windows上也需要32位提供者。 对于服务或调度作业，检查该主机使用的可执行文件和账户，而不仅仅是你的开发环境。
  3. 在运行该应用的电脑上安装或修复支持的安装程序驱动。 x64安装程序包含64位和32位驱动二进制。 请在 “安装 OLE DB 驱动 和 系统需求”中检查所需的依赖关系。 不要用别的电脑复制驱动库来替代安装。
  4. 重复UDL测试，使用匹配的架构和提供者。 如果能用，但应用仍然无法加载提供者，就将应用的有效提供者选择和主机架构与测试进行比较。

如果错误中明确提到 adal.dll，请查看已知的身份验证库问题，而不要将其当作缺少 SQL Server 提供程序的问题。

登录和认证失败

区分服务器登录拒绝与未能获取凭证或建立加密连接。 请阅读完整的错误文本，包括任何嵌套的提供程序错误。

  1. 对于SQL Server错误18456，请数据库管理员检查对应的服务器错误日志条目和状态。 通过 MSSQLSERVER_18456检查认证模式、登录状态、请求的数据库和数据库访问。 不要以为每次登录被拒都是密码错误。
  2. 对于集成身份验证，确认应用程序是在何种身份下运行的。 服务账户或调度任务账户可能与成功测试连接的用户不同。 如果消息中包含 “无法生成 SSPI 上下文”，请遵循 安全支持提供商接口（SSPI）故障排除 和 服务主体名称（SPN）支持。
  3. 对于 Microsoft Entra ID，检查所选认证方法是否符合应用程序的执行环境，并且其身份是否能够访问目标数据库。 请查看 Use Microsoft Entra ID 中的方法专属设置和访问令牌限制。 不要将访问令牌与相互冲突的身份验证属性或凭据属性结合使用。
  4. 将有效设置与正确的 连接字符串 关键字表进行比较。 IDBInitialize::Initialize， IDataInitialize::GetDataSource， 和 ActiveX 数据对象（ADO）使用不同的关键词表。 查看您的应用程序所使用接口对应的表格。

文本“ 目标主体名称错误 ”可能出现在不同语境中。 如果同时出现无法生成 SSPI 上下文，请检查 Windows 身份验证和 SPN。 如果错误识别了证书或加密握手，请使用下一部分。

TLS证书故障

传输层安全（TLS）错误可能在登录到达 SQL Server 之前发生。 当前驱动默认启用强制加密，因此升级时可能会暴露出证书信任或名称问题，而旧连接配置未检测到。

  1. 对于证书链由不受信任的颁发机构颁发的情况，请检查 SQL Server 提供的证书以及客户端计算机信任的颁发证书链。 配置有效的服务器证书，并通过组织的证书管理流程安装所需的可信根证书和中间证书。
  2. 对于证书名称不匹配，可以将应用程序使用的服务器或监听器名称与证书中的名称进行比较。 使用涵盖预期连接名称的证书。 如果应用程序有意使用不同的连接名称，在配置预期证书名称前，请先查看文档中的 HostNameInCertificate属性 。
  3. 检查有效的加密和验证设置，包括 注册表设置。 查看 加密和证书验证表 ，了解优先级和 Strict 行为。 在 Strict 模式下，驱动程序无论信任-服务器-证书设置如何，都会验证证书。
  4. 如果故障是在迁移过程中开始的， 请检查主要版本的故障排除，包括加密属性的值类型以及禁止使用 ServerCertificate 外部 Strict 模式的规定。

使用SQL Server的证书要求和证书链非可信的故障排除来进行详细检查。 在生产环境中保持加密和证书验证开启。 禁用这两个功能并不能解决证书部署问题。

网络和实例发现失败

对于未找到服务器、找不到指定的服务器/实例或连接被拒绝错误，请确定应用程序正尝试连接的端点。

  1. 请与数据库管理员核实服务器名称、实例名称和已配置的监听端口。 确认数据库服务正在运行，并且预期的协议和监听器已被启用。 不要假设每个实例都监听1433端口。
  2. 对于远程传输控制协议（TCP）连接，使用驱动程序的 tcp:<server>,<port> 服务器名称格式测试已知端点。 保持相同的身份验证、数据库和加密设置。 请参见连接 字符串关键词 ，了解适用于你界面的服务器关键词。
  3. 如果显式主机和端口都能用，但命名实例不行，可以研究一下 SQL Server 浏览器和实例发现。 检查 Browser 服务以及在使用 Browser 发现时到用户数据报协议 (UDP) 端口 1434 的路径。
  4. 如果显式端点也失败，检查域名系统（DNS）解析、路由以及应用主机对实际监听端口的防火墙访问情况。 请按照 与网络相关或特定于实例的连接错误 中的说明进行排查，而不要一次更改多个连接设置。

对于可用性组监听器，也可以查看 高可用性和灾难恢复支持。 对于LocalDB，使用 LocalDB支持 来检查本地实例和用户上下文，而不是应用远程TCP发现步骤。

参数和数据转换错误

如果连接打开但命令执行或数据检索失败，则将重现简化为失败的命令和值。 替换敏感数据时，保持原始数据类型、长度、空状态和字符编码。

  1. 将每个 ? 参数标记与其绑定的序数、方向和元数据进行比较。 当你使用 ICommandWithParameters::SetParameterInfo时，SQL 源类型与命令或存储过程匹配。 不要假设参数元数据总是自动生成的。 请审查命令 参数 以了解推导限制和输出参数行为。
  2. 检查访问器绑定状态以及每个返回值的状态和长度，而不仅仅是整体 HRESULT。 对于属性设置失败的情况，检查每个属性的 dwStatus。 例如 DB_S_ERRORSOCCURRED 这样的部分成功返回，即使没有可用的错误对象，也可能仍需要检查状态数组。 参见 退货代码。
  3. 对于转换或截断，将消费者缓冲区类型和大小与实际列或参数元数据进行比较。 检查精度和缩放以获取数值，检查有效范围和分数秒以获取日期/时间值，以及字符缓冲区的字节长度。 检查 DBSTATUS_E_CANTCONVERTVALUE，不要将 DBSTATUS_S_TRUNCATED 视为完整的值。 使用 数据类型映射、 获取行以及 日期和时间转换 来满足适用规则。
  4. 如果显示缺少受限的输出参数，在读取前先用尽返回的行集。 请参阅使用 IMultipleResults 处理多个结果集。 对于流式输出参数，在请求下一个结果前，先消耗或释放待处理的流，详见 “流式支持”中的输出参数。

对于 ADO 特定映射，请查看 将 ADO 与 OLE DB 驱动程序配合使用 以及 DataTypeCompatibility 中关于 的身份验证限制。 不要在未检查两者之前添加兼容性设置。

对于驱动程序升级后 sql_variant 列中损坏的窄字符串，在修改存储数据之前，请先查看现有的 SSVARIANT 已知问题和恢复过程。

连接丢失与超时

记录连接最后一次正常工作的时间、失败的操作以及该操作持续了多久。 在更改重试或超时设置前，先区分这些情况。

失败阶段 检查与详细指导
打开连接。 先检查提供商、网络、认证和 TLS 错误。 请检查有效的 DBPROP_INIT_TIMEOUT 或相应的连接关键字。 请参见 连接超时故障排除。
执行命令。 检查 DBPROP_COMMANDTIMEOUT 或应用程序的命令超时设置。 使用 查询超时故障排除排查阻塞问题并检查查询性能。 增加连接超时不会改变命令超时。
复用空闲连接。 检查 空闲连接弹性中的恢复条件、重试设置和预期错误。 当命令超时结束且重新连接未完成时，恢复可能失败。
在执行或提交过程中丢失连接。 关联客户端和服务器事件，以检查网络中断、服务器重启或故障切换。 在决定是否安全重试之前，先确定手术结果。

空闲连接弹性不提供初始连接重试或任意命令和事务的自动重放。 对于确认的瞬态失败，使用带有延迟的有界应用重试，并记录每次尝试。 不要在未纠正原因的情况下反复尝试提供者加载错误、凭证被拒绝或证书验证失败。

Caution

如果在写入或提交过程中连接中断，客户端可能不知道 SQL Server 是否提交了该事务。 不要盲目重播手术过程。 在重试前检查结果，或者使用防止重复效果的应用设计。

诊断与追踪

在故障点收集诊断数据，避免无关的提供者呼叫替换错误信息。

  1. 捕获失败操作、时间戳和时区、经过时间和 HRESULT。 对于原生 OLE DB 使用者，应通过 IErrorRecords 和 IErrorInfo 检索所有可用记录，而不只是第一个说明。 包括 SQLSTATE，以及在可通过 ISQLErrorInfo 获取时的 SQL Server 本机错误编号。 参见检索错误信息和 SQL Server 错误详情。 对于 ADO，捕获连接的 Errors 集合。
  2. 收集每个属性、每个绑定和每个值的状态，以识别通过这种方式报告错误的方法。 缺失错误对象并不能让部分成功结果可以被忽视。
  3. 将客户端故障与服务器错误日志或扩展事件联系起来。 如有，记录 ClientConnectionID 和 ActivityID。 在预登录前失败可能发生在没有客户端连接标识的情况下。
  4. 如果错误记录不足，可以在 扩展事件日志中使用访问诊断信息 进行驾驶员追踪和关联设置。 在复制品周围收集有界的描图，之后停止描摹。

升级时，请包含驱动版本、请求的提供者、应用和进程架构、服务器版本、认证方法、有效连接设置、故障阶段、错误记录以及最小的重复。 说明匹配的UDL测试是否成功，以及问题是否影响一台主机还是多台主机。

从连接设置和日志中移除密码、访问令牌和其他秘密。 审查查询文本和敏感数据的追踪记录，以受限访问方式存储，并且仅通过经批准的支持渠道共享。

相关内容

  • Last updated on