从TFS迁移至Azure DevOps Server时变更集缺失工作项关联

已完成TFS到Azure DevOps Server的TFVC仓库迁移，调用API创建变更集时，变更集其他详情正常，但工作项关联链接缺失，可从以下几个方向排查解决：

1. 检查请求体中工作项关联的参数格式 #

Azure DevOps Server TFVC变更集创建API（POST https://{instance}/{collection}/{project}/_apis/tfvc/changesets?api-version=7.1-preview.1）要求工作项关联通过workItemRefs字段传入，注意以下要点：

• workItemRefs是对象数组，每个对象的id必须为整数类型，不能是字符串（如用户提供的JSON中"id": "5678"会导致关联失败）
• 若传入url字段，必须是工作项的完整有效URL（例如https://{instance}/{collection}/_apis/wit/workItems/5678）
• 正确的参数示例：

  {
    "comment": "关联WI#5678",
    "changes": [
      {
        "item": { "path": "$/MyProject/File.cs" },
        "changeType": "edit"
      }
    ],
    "workItemRefs": [
      { "id": 5678 }
    ]
  }
  

• 排查是否存在字段拼写错误（如误写为workItems而非workItemRefs）

2. 验证API调用的权限 #

确保调用API的身份（PAT令牌或服务账号）同时拥有：

• TFVC的签入权限
• 工作项跟踪的编辑工作项权限
  权限不足会导致变更集创建成功，但无法完成工作项关联的写入操作，可在项目设置的权限面板中确认账号权限。

3. 匹配API版本与Azure DevOps Server版本 #

不同版本的Azure DevOps Server对API参数的支持有差异：

• Azure DevOps Server 2020+ 支持7.1-preview.x系列API，使用workItemRefs字段
• 旧版本Server（如2019及更早）需使用5.1或更低版本API，此时工作项关联需传入workItemIds整数数组（而非对象数组），示例：

  {
    "comment": "关联WI#5678",
    "changes": [...],
    "workItemIds": [5678]
  }
  

4. 尝试分步骤关联工作项 #

如果单步创建变更集关联失败，可拆分操作：

1. 先调用API创建变更集，获取返回的变更集ID
2. 调用工作项更新API添加变更集链接，请求体示例：

   [
     {
       "op": "add",
       "path": "/relations/-",
       "value": {
         "rel": "ArtifactLink",
         "url": "vstfs:///VersionControl/Changeset/{changesetId}",
         "attributes": {
           "name": "Fixed in Changeset"
         }
       }
     }
   ]
   

   端点：PATCH https://{instance}/{collection}/{project}/_apis/wit/workItems/{workItemId}?api-version=7.1-preview.3

5. 查看Server日志排查深层问题 #

登录Azure DevOps Server管理控制台，查看应用层日志，检查是否有变更集关联相关的权限错误、数据格式错误日志；也可在API调用时开启详细日志，查看响应中的隐藏错误提示。

相关用户提供信息 #

API代码示例

var changesetRequest = new
{
    Comment = "Migrated changeset",
    Changes = new[]
    {
        new
        {
            Item = new { Path = "$/MyProject/File.cs" },
            ChangeType = "edit"
        }
    },
    WorkItemRefs = new[]
    {
        new { Id = "5678" } // 此处id为字符串是潜在问题点
    }
};

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", patToken);
var response = await client.PostAsync(apiUrl, new StringContent(JsonConvert.SerializeObject(changesetRequest), Encoding.UTF8, "application/json"));
response.EnsureSuccessStatusCode();

数据源JSON

{
  "comment": "关联WI#5678",
  "changes": [
    {
      "item": { "path": "$/MyProject/File.cs" },
      "changeType": "edit"
    }
  ],
  "workItemRefs": [
    { "id": "5678" }
  ]
}

新旧变更集对比截图

• 旧TFS变更集：
• 新Azure DevOps Server变更集：

内容的提问来源于stack exchange，提问作者Lior Swisa