验证并解决与进程模板相关的错误

  • 项目

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

作为迁移导入过程的一部分，数据迁移工具检查集合中项目使用的过程。 修复标记的任何错误。

解决错误后，请重新运行数据迁移工具的 validate 命令，以验证是否已修复所有错误。

注意

建议使用 迁移指南 完成导入。 本指南根据需要链接到技术文档。

随着 Azure DevOps Server 2019 的发布，TFS 数据库导入服务已重新命名为迁移到 Azure DevOps。 这包括 TfsMigrator 成为数据迁移工具或简称迁移器。 此服务的工作方式仍与旧的导入服务完全相同。 如果使用的是使用 TFS 作为品牌打造的较旧本地版本，则只要升级到受支持的版本之一，仍可使用此功能迁移到 Azure DevOps。

处理验证类型

在验证期间，数据迁移工具确定每个项目的目标进程模型。 它会自动将以下两个进程模型之一分配给集合中的每个项目：

  • 继承的进程模型：如果项目是使用敏捷、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、敏捷还是 CMMI？ 在此示例中，让我们假设敏捷。 接下来，转到 GitHub 上提供的流程自定义脚本 并下载存储库。 在此实例中，我们将重点介绍“导入”文件夹中的内容。

使用 ConformProject.ps1 脚本符合所选敏捷系统流程的项目。 这将将整个项目更新为敏捷项目。

.\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：工作项类型 Bug 中的字段 X 具有 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 字段，必须将它命名为迭代 ID，并将其类型设置为 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 的全局列表。 需要删除过时的全局列表。