Azure DevOps迁移工具完整指南：从实战到精通-酒店常州论坛

Azure DevOps迁移工具完整指南：从实战到精通

【免费下载链接】azure-devops-migration-toolsAzure DevOps Migration Tools allow you to migrate Teams, Backlogs, Work Items, Tasks, Test Cases, and Plans & Suits from one Project to another in Azure DevOps / TFS both within the same Organisation, and between Organisations.项目地址: https://gitcode.com/gh_mirrors/az/azure-devops-migration-tools

Azure DevOps Migration Tools是一款强大的开源工具，能够帮助团队轻松迁移Azure DevOps/TFS中的团队、待办事项、工作项、任务、测试用例以及计划和套件，无论是在同一组织内还是跨组织间的项目迁移都能高效完成。本文将为您提供从安装到高级配置的全方位指导，让您快速掌握这一工具的使用技巧。

一、快速安装：3种简单方法任选

1.1 Winget一键安装（推荐）

对于Windows 10/11用户，使用微软官方包管理器Winget安装最为便捷：

winget install nkdAgility.AzureDevOpsMigrationTools

工具会自动安装到%Localappdata%\Microsoft\WinGet\Packages目录，并创建系统路径链接，直接在命令行输入devopsmigration即可使用。

⚠️ 注意：不要使用管理员权限运行安装命令！

1.2 Chocolatey包管理安装

Windows Server用户可通过Chocolatey安装：

choco install vsts-sync-migrator

工具将安装到C:\Tools\MigrationTools\目录，自动添加到系统路径。

1.3 手动下载安装

访问GitHub发布页面下载最新版本压缩包，解压到任意目录即可。需要注意的是，在Windows系统中可能需要右键文件属性，点击"解除锁定"后才能正常运行。

二、必备权限配置

迁移工具需要特定权限才能正常工作，这是因为工具需要绕过某些工作项规则引擎，以便在目标系统中创建与源系统一致的数据。

2.1 源项目权限

必须是"项目集合管理员"组的成员
需要拥有"完全访问"权限的PAT令牌

即使工具不会写入源系统，仍需要完全访问权限的PAT令牌

2.2 目标项目权限

必须是"项目集合管理员"组的成员
必须是"项目集合自动化"组的成员（获取"代表他人发出请求"权限）
需要拥有"完全访问"权限的PAT令牌

对于较旧版本的TFS，可能需要使用以下命令添加"代表他人发出请求"权限：

tfssecurity /g+ "Project Collection Service Accounts" n:domain\username ALLOW /server:http://myserver:8080/tfs

三、快速上手：3步完成基础迁移

3.1 创建配置文件

打开Windows终端，导航到工作目录，运行以下命令生成基础配置：

devopsmigration init --options Basic

这将创建一个configuration.json文件，包含迁移所需的基本设置。

3.2 配置关键参数

编辑生成的配置文件，至少需要修改以下参数：

Source和Target部分：设置Collection（组织URL）和Project（项目名称）
Authentication部分：设置AuthenticationMode为"Prompt"（交互式）或"AccessToken"（PAT令牌）
ReflectedWorkItemIdField：设置跟踪字段名称，如"Custom.ReflectedWorkItemId"
将WorkItemMigrationConfig处理器的Enabled设置为true

3.3 执行迁移

保存配置文件后，运行以下命令开始迁移：

devopsmigration execute --config .\configuration.json

⚠️ 重要提示：在开始迁移前，必须在目标项目中添加ReflectedWorkItemId自定义字段，用于跟踪迁移关系。

四、高级迁移：测试计划和套件迁移指南

迁移测试计划和套件是一个多步骤过程，需要按特定顺序执行以确保依赖关系正确映射。

4.1 迁移基础工作项

首先迁移非测试类工作项，排除测试用例、测试套件等：

{ "ProcessorType": "TfsWorkItemMigrationProcessor", "Enabled": true, "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Case', 'Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request') ORDER BY [System.ChangedDate] desc" }

4.2 迁移测试用例及共享组件

接下来迁移测试用例、共享步骤和共享参数：

{ "ProcessorType": "TfsWorkItemMigrationProcessor", "Enabled": true, "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] IN ('Test Case','Shared Steps','Shared Parameter') ORDER BY [System.ChangedDate] desc" }

4.3 迁移测试变量和配置

迁移测试变量和配置作为测试计划的前置条件：

{ "Processors": [ { "ProcessorType": "TfsTestVariablesMigrationProcessor", "Enabled": true }, { "ProcessorType": "TfsTestConfigurationsMigrationProcessor", "Enabled": true } ] }

4.4 重建测试计划和套件

最后重建测试计划和套件结构，完成整个测试资产的迁移：

{ "Processors": [ { "ProcessorType": "TfsTestPlansAndSuitesMigrationProcessor", "Enabled": true, "FilterCompleted": false } ] }

五、常见问题与解决方案

5.1 工作项类型验证失败

迁移前工具会自动验证源和目标系统的工作项类型是否匹配。如果出现类似Work item type 'Risk' does not exist in target system的错误，可以通过以下方法解决：

在目标系统中创建缺失的工作项类型
配置工作项类型映射，将源类型映射到目标系统中存在的类型
从迁移查询中排除该工作项类型

5.2 缺少ReflectedWorkItemId字段

错误信息如'User Story' does not contain reflected work item ID field 'Custom.ReflectedWorkItemId'表示目标项目中未添加必要的跟踪字段。解决方案是：在目标项目的所有工作项类型中添加ReflectedWorkItemId自定义字段。

5.3 权限不足问题

如果迁移过程中出现权限错误，请确保：

使用的PAT令牌具有"完全访问"范围
运行工具的用户是项目集合管理员
已正确添加到"项目集合自动化"组（对于自托管TFS）

六、进一步学习资源

官方文档：docs/content/docs
配置示例：src/MigrationTools.Samples
交互式配置向导：docs/content/docs/config/config-wizard/index.md

通过本指南，您已经掌握了Azure DevOps Migration Tools的基本使用方法和高级迁移技巧。无论是简单的工作项迁移还是复杂的测试计划迁移，这款工具都能帮助您高效完成任务，减少手动操作，确保迁移过程的准确性和完整性。开始使用这款强大的工具，让您的Azure DevOps迁移工作变得轻松简单！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析