共用方式為

ClearQuest 轉換器疑難排解

  • 發行項

更新：2007 年 11 月

如果當您將工作項目從 ClearQuest 移轉到 Team Foundation Server 時發生問題，ClearQuest 轉換器會將錯誤和警告記錄在報告檔案中。針對問題進行疑難排解的最佳方法就是檢閱此報告檔案，以判斷發生了哪些事情。下列資訊有助於針對 ClearQuest 轉換器發生的問題進行疑難排解。

本章節內容

分析問題的疑難排解

找不到 license.dll 檔案

分析失敗且未建立分析報告

疑難排解移轉的問題

移轉命令失敗

轉換器連接時發生的嚴重錯誤

提供工作項目類型時發生的嚴重錯誤

分析報告或移轉報告中的區段未展開

工作項目結構描述變更未移轉到 Team Foundation Server

由於附件上載失敗而造成工作項目移轉失敗

分析問題的疑難排解

當執行分析命令發生問題時，會將錯誤向主控台 (Console) 報告，而且會產生報告檔案，其中包含所發生之問題的詳細資料。您可以在大多數的時間更正錯誤的原因，並重新啟動轉換器。如果您不確定錯誤的原因，請在 Team Foundation 說明中搜尋錯誤代碼或完全相同的文字。某些錯誤也會列出從轉換器使用的 ClearQuest API 所報告的內部錯誤；如果是這類錯誤，您可以在 ClearQuest 文件中找到其他資訊。

找不到 license.dll 檔案

當您執行分析命令時，可能會收到以下錯誤：「這個應用程式無法啟動，因為找不到 license.dll。重新安裝應用程式可能可以解決這個問題。」當您按一下 [確定] 之後，您會收到另一個錯誤：「TF61118: ClearQuest API 呼叫失敗，發生下列錯誤: 由於發生下列錯誤，為具有 CLSID {94773112-72E8-11D0-A42E-00A024DED613} 的元件擷取 COM Class Factory 失敗: 8007007e。如需詳細說明，請參閱 ClearQuest 文件。」

當轉換器無法載入 ClearQuest 程式庫時，會發生這些錯誤，因為程式庫路徑未正確設定。

解決方案

  • 確認 ClearQuest 用戶端已安裝在電腦上，這樣會安裝必要的程式庫。

  • 確認您未從安裝 ClearQuest 之前啟動的主控台視窗執行轉換器；如果有的話，請開啟新的主控台視窗，然後再次執行轉換器。

  • 確認在安裝 ClearQuest 之後並未修改過 PATH 環境變數。PATH 環境變數應該包含 ClearQuest 所安裝之 DLL 檔案的路徑。如果遺失這些路徑，您可能必須重新安裝 ClearQuest。

分析失敗且未建立分析報告

如果轉換器無法載入組態檔，分析命令將會失敗，而且不會建立任何報告。

解決方案

  • 使用 XML 編輯器或工具，並確認組態檔的 XML 格式正確。

  • 確認組態檔中的 XML 項目和屬性已正確指定。如果您收到驗證錯誤，錯誤訊息將會指示不支援的值，而且會指示找到該值的行號。如需詳細資訊，請參閱工作項目轉換器組態檔。

疑難排解移轉的問題

當您使用移轉命令來執行轉換器時，有幾個時間點可能會發生錯誤。首先，轉換器會讀取組態檔，並使用指定的連接資訊來連接到 ClearQuest 資料庫。接下來，轉換器會在 Team Foundation Server 上提供指定的工作項目類型。最後，轉換器會將工作項目從 ClearQuest 移轉到 Team Foundation Server。

當轉換器執行時，它會將狀態訊息列印到主控台，您可以使用狀態訊息來判斷發生移轉失敗的時間點。例如，如果最後的成功狀態訊息為「正在驗證 Team Foundation 中的使用者」，則錯誤很可能與使用者對應檔有關。

針對移轉問題進行疑難排解的關鍵在於檢查所報告的任何錯誤；報告錯誤的方式如下。

  1. 將訊息顯示到主控台，以指示所發生的錯誤。例如，如果有 2 個警告和 1 個錯誤，您會收到下列訊息：[移轉完成，共有 2 個警告，1 個錯誤]。

  2. 建立移轉報告檔，其中包含與警告和錯誤有關之更確切的資訊，此報告檔的名稱為 CQMigrationReport.xml。

注意事項：

在某些情況下，轉換器可能無法產生報告檔，而您只會看到錯誤訊息輸出到主控台。

移轉命令失敗

在移轉期間，轉換器可能會在任何時間點遇到嚴重錯誤，嚴重錯誤會讓轉換器停止，而且不再移轉其他工作項目。嚴重錯誤可能發生在實際移轉工作項目之前，或是已經移轉某些工作項目之後。當移轉失敗時，您會遇到下列兩個徵兆的其中一個：

  • 您會在移轉報告檔 CQMigrationReport.xml 中看到嚴重錯誤及「移轉失敗」訊息。您會在此報告檔中看到類似以下的字串：移轉失敗 { 1 嚴重錯誤 | 2 錯誤 | 4 警告 }。

  • 移轉失敗並將錯誤輸出到主控台，但是未產生任何報告。

解決方案

  • 修正此錯誤的來源，並重新啟動轉換器。當您重新啟動轉換器時，它不會重新移轉已經移轉過的工作項目。轉換器不會建立重複的工作項目。

  • 嚴重失敗的原因不一，錯誤訊息也有很多種。大多數的錯誤訊息都會提供可識別錯誤原因的資訊。您也可以在 Team Foundation 說明中搜尋錯誤文字，以找出某些錯誤的詳細資訊。最後，檢查本主題之前列出之分析命令的疑難排解問題，許多問題也同樣適用於移轉命令。

轉換器連接時發生的嚴重錯誤

當轉換器嘗試連接到 ClearQuest 或 Team Foundation Server 時，可能發生嚴重錯誤。您會在報告中看到一或多個指示連接問題的錯誤訊息。

解決方案

確認您可以透過 ClearQuest 用戶端連接到 ClearQuest，並透過 Team 總管連接到 Team Foundation Server。通常透過這些用戶端的訊息就可以比較容易診斷出連接問題。此外，當您使用將執行轉換器的使用者帳戶來登入時，也記得要啟動這些用戶端，如此將會快取轉換器的必要資料，以便能夠正確執行。

提供工作項目類型時發生的嚴重錯誤

提供工作項目類型時發生的嚴重錯誤可能是因為欄位命名問題。您可能會遇到類似以下的錯誤訊息：

移轉失敗是因為「TF61013: 轉換器無法提供檔案 \\<computername>\e$\temp\CQOGF\Defect.xml 中指定的工作項目類型，因為發生下列錯誤: TF26177: 無法將欄位 Microsoft.TeamFoundation.Converters.Priority_String 由 'Priority String' 重新命名為 'Priority String1'。Team Foundation 不支援重新命名欄位的功能。」

Team Foundation Server 中的欄位有伺服器層級的命名範圍，欄位的名稱、參考名稱和型別的組合在伺服器中應該是唯一的。轉換器分析階段具有可避免衝突的邏輯；當轉換器偵測到衝突時，它會適當地修改產生的欄位名稱。但是，當您從分析命令產生欄位名稱與執行移轉命令之間可能會有時間差距。可能在衝突之前的該段時間修改了伺服器上的工作項目類型，或是，您可能已經編輯產生的工作項目類型，並在無意間選擇了與現有欄位衝突的名稱。

解決方案

  • 藉由修改名稱及 (或) 參考名稱來修改您的工作項目類型，以解決此衝突。您通常能夠只使用已經存在的欄位名稱。若要檢視現有的工作項目類型，您必須從 Team Foundation Server 匯出工作項目類型定義檔案。如需詳細資訊，請參閱 witexport。

  • 使用 witfields 命令列公用程式可重新命名或刪除 Team Foundation Server 上的衝突欄位。但是，您要知道不是每次都可以重新命名及刪除現有的工作項目欄位。如需詳細資訊，請參閱 witfields。

分析報告或移轉報告中的區段未展開

分析報告或移轉報告中的區段未在 Internet Explorer 的預設安全性設定底下正確展開；展開和摺疊按鈕是由指令碼所控制，而預設 Internet Explorer 安全性會防止這些指令碼執行。

解決方案

您可以變更 Internet Explorer 安全性來允許呈現報告的主動式內容 (Active Content)，藉此更正此問題。

若要變更安全性來允許呈現報告的主動式內容

  1. 在瀏覽器上方的附近找出有 [為了協助保護您的安全性，Internet Explorer 已限制這個檔案顯示會存取您電腦的主動式內容] 文字的黃色安全性標題列。

  2. 按一下此黃色安全性標題列，然後按一下 [允許被封鎖的內容]。

  3. 在 [安全性警告] 對話方塊中，按一下 [是]。

工作項目結構描述變更未移轉到 Team Foundation Server

如果已提供工作項目類型，則不會套用工作項目結構描述變更。這通常發生於當您一次執行移轉命令、修改結構描述對應檔中的工作項目類型定義，然後再次執行移轉命令時。修改的內容不會出現在 Team Foundation Server 中。此外，下列警告會出現在移轉報告中：「無法建立工作項目類型 <type name>，因為它已經存在於 Team Foundation Server 中。」

轉換器會進行明確檢查，以確定它不會覆寫現有的工作項目類型。因此，一旦此工作項目類型是由轉換器所提供時，即使當您修改此工作項目類型時，還是不會納入這些變更，因為已經提供此工作項目類型。

解決方案

若要更新 Team Foundation 伺服器上的工作項目類型，請使用 witimport 命令列公用程式將工作項目類型匯入到 Team Foundation Server。然後，當您移轉工作項目時，轉換器會使用更新的類型。當您使用 witimport 命令列公用程式時，請務必小心，不要修改或刪除工作項目資料。如需詳細資訊，請參閱 witimport。

由於附件上載失敗而造成工作項目移轉失敗

如果附件超過允許的附件大小，將不會移轉這些附件。此外，移轉報告檔中會列出下列錯誤：「TF61015: 工作項目 <id> 的附件 <filename> 儲存失敗，發生下列錯誤: 正在上載的檔案超過容許的檔案上載大小上限 (4MB)。」

解決方案

  • 您可以增加 Team Foundation 伺服器上附件大小的上限，以修正這個問題。預設大小為 4 MB，但是您最多可以增加到 2 GB (2147483648 個位元組)。

若要設定工作項目的附件大小上限

  1. 在 Internet Explorer 中，尋找下列 URL：

    http://<tfsserver>:8080/WorkItemTracking/v1.0/ConfigurationSettingsService.asmx?op=SetMaxAttachmentSize

    其中 <tfsserver> 表示 Team Foundation 伺服器的名稱。

  2. 在 [maxSize] 方塊中，輸入附件大小上限 (以位元組為單位)，然後按一下 [叫用] (Invoke)。附件大小上限為 2 GB。

注意事項：

您必須是 Team Foundation 應用程式層伺服器上 [Administrators] 群組的成員以及 [Team Foundation Administrators] 群組的成員，才能執行此程序。如需詳細資訊，請參閱 Team Foundation Server 使用權限。

請參閱

概念

Team Foundation Server 使用權限

其他資源

工作項目移轉疑難排解