驗證並解決與進程範本相關的錯誤

  • 發行項

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

在移轉匯入程式中，數據遷移工具會檢查集合中專案所使用的程式。 修正任何標示為旗標的錯誤。

解決錯誤之後，請重新執行資料遷移工具的 validate 命令，以確認所有錯誤都已修正。

注意

建議您使用 移轉指南 進行匯入。 本指南會視需要連結到技術檔。

隨著 Azure DevOps Server 2019 的發行，TFS 資料庫匯入服務已重新命名為移轉至 Azure DevOps。 這包括 TfsMigrator 短期成為數據遷移工具或移轉工具。 此服務仍然與舊的匯入服務完全相同。 如果您是使用 TFS 作為商標的舊版內部部署，只要升級至其中一個支援的版本，您仍然可以使用此功能來移轉至 Azure DevOps。

處理驗證類型

在驗證期間，數據遷移工具會決定每個專案的目標進程模型。 它會自動將下列兩個程式模型之一指派給集合中的每個專案：

  • 繼承的進程模型：如果專案是以 Agile、Scrum 或 CMMI 程式範本建立，且從未自定義過。
  • 裝載的 XML 進程模型：如果項目進程似乎已經自定義。 自訂程式包含自定義欄位、工作項目類型或其他自訂類型。

當裝載的 XML 進程是目標進程模型時，資料遷移工具會驗證是否可以移轉自定義專案。 資料移移工具會在驗證期間產生兩個檔案：

  • DataMigrationTool.log：包含集合中找到的進程驗證錯誤集。 修正找到的所有程序錯誤，以繼續進行您的移轉。

  • TryMatchOobProcesses.log：目標進程模型 - 繼承或託管 XML 的每個項目清單。 針對設定為以託管 XML 進程模型為目標的專案，它會說明為何要將其視為自定義。 您不需要修正這些錯誤，但會提供指引，以防您想要移轉至繼承程式模型時該怎麼辦。 請注意，一旦匯入集合，您就可以將專案移轉至繼承程式模型。

大部分的客戶在集合內都有項目組合。 某些專案會使用預設進程範本，而其他專案則使用自定義進程範本。 數據遷移工具會據以檢查並驗證每個專案。 您很有可能會混合專案、一些項目對應至繼承的進程，而另一些則對應至託管的 XML 進程。

建議您針對尚未自定義的任何專案，檢閱 TryMatchOobProcesses.log ，以判斷是否有任何錯誤。 如果是，請據以調整專案，以便在數據匯入時對應至繼承的進程。

更新至系統進程

如果您從舊版的 Azure DevOps Server 開始，您的專案仍使用較舊的程式範本。 如果這些專案尚未使用 [ 設定功能精靈 ] 更新，則數據遷移工具會尋找程序錯誤。 在某些情況下，如果您的程式非常舊，即使是設定功能精靈也無法解決錯誤。

以下是您可能會收到之錯誤訊息的一些範例：

Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element PortfolioBacklog is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element BugWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackRequestWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackResponseWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Team.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField RemainingWork.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Order.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Effort.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Activity.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationStartInformation.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationLaunchInstructions.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationType.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF400572: The Project Process Settings must be configured for this feature to be used.

如果您從未自定義專案（新增欄位、工作項目類型等），則修正這些錯誤實際上相當簡單。 如果您已自定義程式，則此方法將無法運作。 您必須手動變更程式範本，讓您的自定義專案不會遭到覆寫。

首先，請確定您知道專案啟動的程序為何。 這是 Scrum、Agile 或 CMMI 嗎？ 在此範例中，讓我們假設 Agile。 接下來，移至 GitHub 上提供的處理自定義腳本 ，並下載存放庫。 在此實例中，我們會將焦點放在 [匯入] 資料夾中的內容。

使用 ConformProject.ps1 腳本來符合您選擇的專案到 Agile 系統程式。 這會將整個專案更新為 Agile。

.\ConformProject.ps1 "<collection url>" "<project name>" "c:\process-customization-scripts\import\agile"

請確定您針對每個項目執行此動作。

解決進程錯誤

您的程式範本是自定義的嗎？ 您是否使用較舊的過時程式範本？ 如果是，您很可能會有進程驗證錯誤。 數據遷移工具會針對您的程式範本進行詳盡的檢查。 它會檢查以確定其適用於 Azure DevOps Services。 賠率在於您必須進行一些調整，並將其套用至您的集合。

注意

如果您使用 OOB Agile、Scrum 或 CMMI 程式，則可能不會在DataMigrationTool.log中看到任何錯誤。 請改為檢查 TryMatchOobProcesses.log 是否有錯誤。 如果您無錯誤，則您的專案將會對應至 OOB 程式。

Azure DevOps Services 中有數個自定義專案無法運作。 請確定您檢閱 支援的自訂 清單。

如果您有使用較舊進程範本的專案，資料遷移工具會發現數個錯誤。 這是因為您的進程範本尚未更新，以符合最新的進程範本。 若要開始，請嘗試針對每個項目執行 [ 設定功能精靈 ]。 這會嘗試使用最新的功能來更新您的程序範本。 這樣做應該會大幅減少錯誤計數。

最後，請確定您已 witadmin 在想要用來修正程式錯誤的電腦上。 這可以是您的本機桌面。 witadmin命令行工具會在自動化腳本中使用，而且每當變更程式範本時，都需要此工具。

步驟 1 - 檢閱錯誤

會產生DataMigrationTool.log 檔案，並包含驗證程式找到的錯誤清單。 若要檢視記錄檔，請開啟 DataMigrationTool.log 檔案。 搜尋字串 「驗證 - 開始驗證專案 1」。 每個專案都會經過驗證。 掃描所有專案，並搜尋包含 [Error ...] 前置詞的任何行。

處理資料遷移工具所產生的記錄檔

如需驗證錯誤的清單，請參閱 解決程式匯入的驗證錯誤。 針對每個驗證錯誤，我們提供了要解決的錯誤號碼、描述和方法。

步驟 2 - 修正錯誤

一旦您判斷哪些專案有錯誤和錯誤詳細數據，請修正錯誤。 修正錯誤需要您變更 XML 語法，並將變更套用回專案。

注意

建議您不要使用 TFS Power Tools 來執行這項工作。 相反地，強烈建議您手動修改 XML。

若要從專案取得進程範本，請在執行資料遷移工具命令時新增 /SaveProcesses 參數。

Migrator validate /collection:{collection URL} /tenantDomainName:{name} /region:{region} /SaveProcesses

此命令會從專案擷取 XML，並將它放入與記錄相同的資料夾中。 將 zip 檔案解壓縮到本機計算機，以便編輯檔案。

現在，請修正 XML。 使用檔案中的 DataMigrationTool.log 記錄來判斷每個項目的錯誤。

處理資料遷移工具所產生的記錄檔

某些錯誤會要求您使用 witadmin changefield 命令。 變更功能變數名稱是最常見的範例。 若要省下一些時間，建議您執行 witadmin changefield 命令，然後重新執行數據遷移工具。 這樣做會以更正的名稱重新匯出 XML。 否則，您也必須手動修正 XML 語法中的欄位。

進行修正之後，請將變更套用回 Azure DevOps Server。 若要這樣做，視您所做的變更而定，您必須執行一或多個 witadmin 命令。 為了讓您更輕鬆地進行此作業，我們建立了PowerShell腳本來自動化程式。 文稿包含 witadmin 符合整個程式所需的所有命令。

您可以在程式自定義文稿取得文稿。 使用 import/ConformProject.ps1 腳本。

.\conformproject.ps1 "<collection url>" "<project name>" "<process template folder>"

符合執行的項目進程腳本

當文稿完成時，請重新執行資料遷移工具來驗證集合。 請遵循步驟 1 到 3，直到數據遷移工具不會產生任何驗證錯誤為止。

提示

如果您不熟悉 XML 和 witadmin，建議您一次進行一個修正，然後符合。 繼續此迴圈，直到解決所有錯誤為止。

常見的驗證錯誤

VS402841：工作項目類型的字段 X Bug 具有 syncnamechanges=false，但有規則使其成為識別字段。 識別欄位必須具有 syncnamechanges=true。 請更新您的程式範本以包含此變更。

在 Azure DevOps Services 中，我們新增了規則，讓每個身分識別欄位都必須有 syncnamechanges=true 屬性。 在 Azure DevOps Server 中，規則不適用。 因此，數據遷移工具會將此問題識別為問題。 別擔心，在 Azure DevOps Server 內部部署上進行這項變更不會造成任何傷害。

執行 witadmin changefield 命令。 命令的語法如下所示：

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /syncnamechanges:true

如需命令的詳細資訊， witadmin changefield 請參閱 管理工作專案欄位。

TF402556：若要妥善定義 System.IterationId 欄位，您必須將它命名為反覆運算標識碼，並將其類型設定為 Integer。

此錯誤通常適用於舊的進程範本。 請嘗試在每個項目上執行 [ 設定功能精靈 ]。 或者，您可以執行下列 witadmin 命令：

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /name:newname

TF402571：進程組態中遺漏必要的 BugWorkItems 元素。

此錯誤通常會在一段時間內未更新進程時發生。 請嘗試在每個項目上執行設定 功能精靈 來解析。

TF402564：您已定義XX全域清單。 只允許 64 個。

根據預設，Azure DevOps Services 將支援 64 個全域清單。 如果您有大量的組建管線，您通常會在此錯誤中執行。 系統會為每個新的組建管線建立名為 Builds - TeamProjectName 的全域清單。 您必須移除過期的全域清單。