验证并准备要迁移的服务器环境

验证涉及准备已升级的 Azure DevOps Server 环境进行迁移。 本文将帮助你排查常见问题。 如果没有错误并且通过了所有验证检查,则团队项目集合已准备就绪,你可以继续下一阶段。 查看日志文件以查找任何错误(如果不是所有传递检查)。

突出显示了迁移七个阶段的“验证”阶段的关系图。

先决条件

下载最新的 数据迁移工具

了解进程验证类型

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

  • 继承的进程模型: 如果项目是使用敏捷、Scrum 或功能成熟度模型集成(CMMI)过程模板创建的,并且从未自定义过。
  • 托管的 XML 进程模型: 如果项目进程似乎已自定义。 自定义过程包含自定义字段、工作项类型或其他类型的自定义。

当托管 XML 进程是目标进程模型时,数据迁移工具将验证是否可以迁移自定义项。 数据迁移工具在验证过程中生成两个文件:

  • DataMigrationTool.log: 包含集合中找到的进程验证错误集。 修复发现的所有进程错误,以便继续迁移。
  • TryMatchOobProcesses.log: 目标进程模型的每个项目的列表 - 继承或托管 XML。 对于设置为面向托管 XML 进程模型的项目,它解释了它们被视为自定义的原因。 无需修复这些错误,但它们可指导在迁移到继承过程模型时要执行的操作。 集合迁移后,可以将项目迁移到继承进程模型。

验证团队项目集合

由于每个团队项目集合都对应于自己的 SQL 数据库,验证过程会检查集合的各个方面,包括:

  • 集合数据库的大小
  • SQL 数据库的排序规则
  • 集合中用户的标识
  • 模板自定义(流程)

若要开始验证,请使用迁移程序工具。 建议从 Azure DevOps Server 环境中的某个应用程序层(AT)服务器运行迁移器工具。

对于特定的命令行选项,请使用以下命令请求帮助文本:

	Migrator validate /help

启动验证的最常见方法是使用以下结构指定团队项目集合的 URL:

	Migrator validate /collection:http://localhost:8080/tfs/DefaultCollection

查看验证警告和错误

迁移程序工具完成后,它会生成命令提示符屏幕上显示的日志文件和结果。 如果未发生任何错误,并且所有验证检查都通过,则团队项目集合已准备就绪,可供下一阶段使用。 如果验证检查失败,请查看日志文件以识别错误,然后解决这些问题。

专注于Migrator.log该文件,其中包含有关验证检查的基本详细信息,并帮助保留自定义。 其他文件对应于基于其名称的特定验证错误。 搜索字符串“验证 - 开始验证项目 1”。验证每个项目。 扫描所有项目并搜索包含前缀的任何行 [Error...

此外,列出了 TryMatchOobProcesses.log 与使用现成(OOB)进程(如敏捷、Scrum 或 CMMI)的项目相关的错误。 如果项目在没有自定义项的情况下使用 OOB 进程,则项目包含在继承的模型中。 重要的是,此文件中的错误不会妨碍迁移过程。

数据迁移工具生成的DataMigrationTool.log文件的屏幕截图。

有关验证错误的列表,请参阅 “解决验证错误”。 对于每个验证错误,我们提供了要解决的错误号、说明和方法。 验证检查日志中可能会出现各种错误类型。 请从经过培训的 DevOps 合作伙伴、Microsoft 咨询服务或 Microsoft 顶级支持部门寻求帮助,以解决遇到的错误。

解决进程模板错误

我们发现的主要错误是进程模板问题。 这些问题源于过时的团队项目未合并 Azure DevOps Server 的最新功能或 Azure DevOps Services 不支持的自定义。 但是,Azure DevOps Services 确实支持一系列自定义项,并且验证仅标记需要解析预迁移的自定义项。 数据迁移工具对 Azure DevOps Services 兼容性的模板执行全面的检查,但可能需要进行一些修改。

  • 自定义进程模板或过时的模板可能会导致迁移过程中出现进程验证错误。
  • 如果使用 OOB Agile、Scrum 或 CMMI 进程,检查错误TryMatchOobProcesses.log。 无错误项目映射到 OOB 进程。
  • 某些自定义项在 Azure DevOps Services 中不起作用。 查看支持的自定义列表。
  • 对于使用较旧模板的项目,请运行“配置功能向导,以更新具有最新功能的模板并减少错误计数。
  • 确保在 witadmin 修复进程错误的计算机上可用。 对处理模板进行更改至关重要。

请考虑以下工具来解决进程错误:

  • 利用 Visual Studio 安装随附的witadmin.exe命令行工具。 此链接提供了有关解决这些错误的详细技术文档。
  • 使用未记录的迁移程序工具命令自动导出每个团队项目的流程模板:迁移程序验证 /collection:http://localhost:8080/tfs/DefaultCollection /SaveProcesses。
  • 浏览 GitHub 上的 TFS 团队项目经理(链接)。 它允许你将团队项目与已知的流程模板进行比较,包括现成的模板。

若要修复错误,请更改 XML 语法并将更改应用回项目。

提示

建议手动修改 XML,而不是使用 TFS Power Tools。

若要从项目获取进程模板,请在运行数据迁移工具命令时添加 /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 操作,直到数据迁移工具生成不再出现验证错误。

PowerShell 中符合性项目进程的屏幕截图。

提示

如果你不熟悉 XML 和 witadmin,建议一次进行一个修复,然后符合。 继续此循环,直到解决所有错误。

更新到系统进程

如果从旧版 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.

如果未自定义项目(例如,添加字段、工作项类型等),则修复这些错误非常简单。 但是,如果你自定义了你的流程,此方法就不够了。 需要手动调整进程模板,以保留自定义项不被覆盖。

为每个项目执行以下步骤,使流程保持一致:

  1. 确定项目启动的初始过程(Scrum、Agile 或 CMMI)。
  2. 访问 GitHub 上的进程自定义脚本并下载存储库。
  3. 专注于迁移文件夹中的内容。
  4. ConformProject.ps1使用以下脚本将所选项目与敏捷系统流程保持一致。 此操作将整个项目更新为敏捷项目。
.\ConformProject.ps1 "<collection url>" "<project name>" "c:\process-customization-scripts\import\agile"  

常见验证错误

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 changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /name:newname

TF402571:进程配置中缺少必需的元素 BugWorkItems。

当进程在一段时间内未更新时,通常会看到此错误。 若要解决此问题,请为每个项目运行 “配置功能向导 ”。

TF402564:已定义 XX 全局列表。 仅允许 64 个

Azure DevOps Services 原生支持 64 个全局列表。 当存在大量生成管道时,通常会发生此错误,因为每个新管道都会创建一 Builds - TeamProjectName个名为全局列表。 若要解决此错误,请删除任何过时的全局列表。

重复验证检查

在每个迭代中,解决错误并执行验证检查来解决它们,如验证日志文件所示。 保留此周期,直到纠正所有错误,并且你收到收集验证检查成功确认。

后续步骤