疑難排解適用於 SQL Server 的 Microsoft OLE DB Driver

適用於：SQL ServerAzure SQL 資料庫Azure SQL 受控執行個體Azure Synapse AnalyticsMicrosoft Fabric 中的 SQL 資料庫

請使用本文來辨識 OLE DB 操作的失敗階段，選擇下一個檢查點，並找到詳細的故障排除說明。 指引使用目前的提供者：MSOLEDBSQL19。 關於特定版本的缺陷與升級變更，請參見 已知問題 與 主要版本差異。

辨識症狀

在更改設定前，請擷取完整的錯誤描述及所有可用的錯誤紀錄。 頂層 HRESULT，例如 DB_E_ERRORSOCCURRED，本身無法直接找出原因。 記錄失敗是否發生於載入提供者程式、開啟連線、執行指令、擷取資料或認可交易時。

癥狀 從這裡開始
找不到提供者，或是課程未註冊。 提供者註冊與架構
登入失敗、存取被拒，或整合驗證失敗。 登入與認證失敗
憑證鏈不被信任，或者憑證名稱不符。 TLS 憑證失效
找不到伺服器或實例，或是連線被拒絕。 網路與實例發現失敗
參數失效、數值被截斷，或資料無法轉換。 參數與資料轉換錯誤
連線中斷、復原失敗或逾時。 連線中斷與逾時
缺少錯誤詳細資料，或者你需要提供給支援人員的追蹤記錄。 診斷與追蹤

連線失敗時，將應用與 通用資料鏈（UDL）連線測試做比較。 使用相同的電腦、服務提供者、流程架構、認證身份、伺服器、資料庫及加密設定。 用不同提供者或身份測試成功，並不代表應用程式的設定是否正常。

提供者註冊與架構

像是 Provider cannot be found 或 REGDB_E_CLASSNOTREG（0x80040154、Class not registered）之類的錯誤，表示在 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 專用的對應，請參閱 搭配 OLE DB Driver 使用 ADO，以及 DataTypeCompatibility 中關於 的驗證限制。 不要在未檢查兩者前就新增相容性設定。

對於驅動程式升級後 sql_variant 欄中損壞的窄字串，修改儲存資料前，請先檢視現有的 SSVARIANT 已知問題與復原程序 。

連線中斷與逾時

記錄連線最後一次運作的時間、哪個操作失敗了，以及該操作持續了多久。 在更改重試或逾時設定前，先區分這些情況。

失敗階段 檢查與詳細指導
開啟連接。 先檢查供應商、網路、認證和 TLS 錯誤。 請檢查有效的 DBPROP_INIT_TIMEOUT 或對應的連線關鍵字。 請參見 連線逾時故障排除。
執行命令。 檢查 DBPROP_COMMANDTIMEOUT 或應用程式的指令逾時設定。 使用 查詢逾時疑難排解來調查阻塞和查詢效能。 延長連線逾時時間不會改變指令逾時時間。
重新使用閒置連線。 檢查 閒置連線復原能力中的恢復條件、重試設定，以及預期錯誤。 如果在重新連線完成之前命令逾時，復原可能會失敗。
在執行或提交過程中連線中斷。 將客戶端與伺服器事件關聯起來，以檢查網路中斷、伺服器重啟或故障轉移。 先確定手術結果，再決定是否安全重試。

閒置連線復原能力不提供初始連線的重試，也不會自動重新執行任意指令與交易作業。 對於確認的暫時性失敗，使用有延遲的有界應用程式重試，並記錄每次嘗試。 不要在未修正原因前反覆嘗試提供者載入錯誤、憑證被拒或憑證驗證失敗。

注意事項

若在寫入或提交過程中連線中斷，客戶端可能無法確定該交易是否已提交 SQL Server。 不要盲目重播手術過程。 在重試前，請檢查結果或使用避免重複效果的應用程式設計。

診斷與追蹤

在故障點收集診斷資料，避免無關的提供者呼叫取代錯誤資訊。

  1. 擷取失敗操作、時間戳與時區、經過時間，以及 HRESULT。 對於原生 OLE DB 使用者，請透過 IErrorInfo 和 IErrorRecords 擷取所有可用記錄，而不僅是第一個描述。 請納入 ISQLErrorInfo 以及原生 SQL Server 錯誤編號（若可透過 SQLSTATE 取得）。 請參閱「取得錯誤資訊」及「SQL Server 錯誤詳情」。 對於 ADO 來說，擷取該連線的 Errors 集合。
  2. 針對那些以這種方式回報錯誤的方法，收集各屬性、各繫結及各值的狀態資訊。 缺失錯誤物件並不代表部分成功結果可以被忽略。
  3. 將用戶端故障與伺服器錯誤日誌或延伸事件相關聯。 若有，請記錄 ClientConnectionID 和 ActivityID。 在沒有用戶端連線識別碼的情況下，預先登入前的失敗可能會發生。
  4. 如果錯誤記錄不足，請使用 在延伸事件日誌中存取診斷資訊 來進行驅動程式追蹤和關聯設定。 在複製品周圍收集有界的描圖，之後停止描摹。

升級時，請包含驅動程式版本、請求的提供者、應用程式與程序架構、伺服器版本、認證方法、有效連線設定、故障階段、錯誤紀錄，以及最小重現。 說明匹配的 UDL 測試是否成功，以及問題是否影響單一主機或多台主機。

從連線設定和日誌中移除密碼、存取權杖及其他秘密。 審查查詢文字與敏感資料的追蹤，並以限制存取方式儲存，並僅透過核准的支援管道分享。

相關內容

  • Last updated on