使用 Azure Boards 中的 CSV 文件导入、更新和导出批量工作项

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

使用 Azure Boards 中的 CSV 格式化文件批量导入和导出工作项。 虽然可以继续使用 Excel 进行批量导入和更新，但可以使用不需要 Excel 的本机导入/导出功能。 有关详细信息，请参阅使用 Excel 批量添加或修改工作项。

导入新工作项

若要批量导入工作项，CSV 文件必须包含工作项类型和标题字段。 可以根据需要包括其他字段。 导入 CSV 文件：

• 不包括 ID 字段。
• 如果 CSV 文件已从其他项目导出，请删除包含特定于源项目的值的字段。 例如，对于删除 区域路径、 标记 作为默认字段的列表，请参阅 “工作项”字段索引。
• 导入测试用例时，必须包含“测试步骤”字段。 有关详细信息，请参阅批量导入或导出测试用例。 不包括 “已分配日期”、“ 已更改日期”、“ 创建者”或 “状态” 字段。
• 确保 CSV 文件中包括工作项类型和标题字段。
• 确保 工作项类型 是目标项目中的有效类型。
• 确保 CSV 文件中的字段与目标项目中的字段 fi=或工作项类型匹配。
• 如果导入包含无效值的工项的 CSV 文件，一旦导入该文件，则必须编辑工作项以修复无效值，然后才能保存工作项。

执行以下步骤以导入新的工作项。

注意

一次最多可以导入 1,000 个工作项。 如果要导入的工作项超过 1,000 个，请将它们分解为多个文件并单独导入它们。

1. 创建本地 import.csv 文件，并在 Visual Studio Code 或 Excel 中打开该文件。

2. 该文件必须包含“工作项类型”和“标题”字段。 可以根据需要包括其他字段。 有关默认字段的列表，请参阅工作项字段索引。

   以下示例包括“优先级”字段。

   Work Item Type,Title,Priority
   Issue,Fix issues with code,1
   Issue,Merge testing modules,3
   Issue,Open private preview for select customers,2
   Issue,Enable feature for customer champs,2
   Issue,Remove old test code,2
   

3. 在项目的 Web 门户中，打开 Boards>查询，然后选择导入工作项。

   

4. 选择选择文件，选择文件，然后选择导入。

   

   导入过程以未保存的状态将导入的工作项加载到查询视图中。 未分配 ID。

5. 验证结果，然后选择“保存项”以保存工作项。

   

   提示

   不要将 ID 分配给你添加的新工作项。 分配 ID 会导致错误消息。

6. 系统突出显示了那些有数据问题的工作项。 先解决数据问题，然后保存工作项。 在此示例中，“优先级”字段中的值无效。 通过直接打开工作项修复数据。 请改用批量编辑来修复多个出现相同问题的工作项。

   

以下提示非常有用。

• 父子链接：可通过缩进标题列在导入的工作项之间添加父子链接，如能否导入具有父子链接的 CSV 文件？中所示。 但是，导入或更新工作项时，不能指定任何其他链接类型。

• 默认状态字段： 导入新工作项时， “状态” 字段默认设置为 “新建 ”。 在导入过程中不能指定其他状态。 如果需要更改导入的工作项的状态，请使用以下解决方法：

  1. 导入具有默认 “新建 ”状态的工作项。
  2. 将导入的工作项导出到 CSV 文件。
  3. 更新导出的 CSV 文件中的“状态”字段值。
  4. 重新导入更新的 CSV 文件以设置所需状态。

• 默认区域和迭代字段：区域和迭代字段默认为顶级节点。 发生此行为的原因是导入过程没有这些字段的上下文，除非在 CSV 文件中明确指定。 若要在导入过程中设置特定的 区域 和 迭代 路径，请确保这些字段包含在 CSV 文件中，其值正确。 例如：

  Title,Description,Area Path,Iteration Path
  "Sample Work Item","This is a sample description.","Project\Team","Project\Sprint 1"
  

更新现有工作项

1. 若要更新工作项，请创建查询，其中包含要导出和可能编辑的所有列。 保存查询，然后选择“导出到 CSV”，将data.csv文件保存到本地计算机。

   

   导出的文件应类似于以下示例：

   ID,Work Item Type,Title,Assigned To,State,Tags
   "272","Issue","Fix issues with code","Active","",
   "273","Issue","Merge testing modules","Active","",
   "274","Issue","Open private preview for select customers","Active","",
   "275","Issue","Enable feature for customer champs","Active","",
   "276","Issue","Remove old test code","Active","",
   

2. 对工作项进行编辑。 CSV 文件必须包含 ID、工作项类型和标题字段。 要包含的任何其他字段都是可选的。

   注意

   导入标识字段时，请使用 "Display Name <email>" 格式输入名称和电子邮件。 例如，若要将工作分配给 Jamal Hartnett，请指定 "Jamal Hartnett <fabrikamfiber4@hotmail.com>"。 如果指定的值未被识别为系统的有效用户，则导入可能会遇到问题。

   在以下示例中，我们将更改现有工作项的值。

   ID,Work Item Type,Title,Assigned To,State,Tags
   "272","Issue","Fix issues with code","Jamal Hartnett <fabrikamfiber4@hotmail.com>","Active",
   "273","Issue","Merge testing modules","Jamal Hartnett <fabrikamfiber4@hotmail.com>","Active",
   "274","Issue","Open private preview for select customers","Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>","Active",
   "275","Issue","Enable feature for customer champs","Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>","Active",
   "276","Issue","Remove old test code","Christie Church <fabrikamfiber1@hotmail.com>","Active",
   

3. 保存文件并导入，如上一部分所述。

4. 包含值更改的工作项的结果列表以粗体突出显示。 选择“保存项”以应用更改。

   

5. 有数据问题的工作项以红色突出显示，必须先解决问题才能保存它们。 在此示例中，“分配到”字段中显示无效值。 通过直接打开工作项修复数据。 如果有多个工作项存在相同的问题，你可以使用批量编辑。

   

将列表导出为 CSV 文件

在任何查询中，都可以将工作项列表导出为以逗号分隔的列表。 打开查询，选择 操作图标，然后选择“导出到 CSV”。

将工作项导出和导入到其他项目

可以使用此功能从一个项目导出工作项，然后将其导入到另一个项目。 但是，在将其导入到另一个项目之前，必须删除工作项 ID。 如果尝试将新工作项导入指定了 ID 的项目，你将收到错误。

导入 HTML 字段

HTML 字段（如说明和验收条件）包括富文本格式。 若要确保保留此格式，请执行以下任务：

1. 确保 CSV 文件在相关字段中包含 HTML 标记。
2. 将 CSV 文件导入 Excel。

Excel 可能以不同的方式处理多行文本字段，因此在导入后检查格式非常重要。 通过用 <p>... </p> 将句子括起来来替换以 CRLF 结尾的行。

例如，可以导入以下工作项，其中包括“说明”字段中的三行文本。

Work Item Type,Title,Description
"Product Backlog Item","Hello World Web Site - 8","<p><strong>&nbsp;You can include bold text</strong></p><p><em>&nbsp;And italic text</em></p><p><u>&nbsp;Underline text</u></p>"

将多行字段转换为纯文本

若要在多行字段中禁用 HTML 以确保它们是纯文本，可以使用 witadmin changefield 该命令。 有关详细信息，请参阅 “管理工作项字段”。

示例 命令：

witadmin changefield /collection:CollectionURL /n:FieldName /type:PlainText

处理格式不一致

当在不同的 Microsoft 产品中使用 HTML 字段时，可能会遇到格式不一致的问题。 以下是一些处理这些问题的技巧：

• 导入后查看格式，以确保它满足你的要求。
• 使用适当的 HTML 标记和结构来最大程度地减少差异。 可以添加多个以分号分隔的标记。 有关详细信息，请参阅 Excel 可以执行和无法执行的任务。

有关管理 HTML 内容并确保兼容性的详细信息，请参阅 在工作项窗体上提供帮助文本、超链接或 Web 内容。

常见问题

问：是否可以在同一个 CSV 文件中导入新项和更新现有项？

答：当然可以！ 将任何新工作项的 ID 字段留空。 在以下示例中，长篇故事的最后一个条目未指定 ID。

ID,Work Item Type,Title,Assigned To,State,Priority,Tags
"16504","Issue","Fix issues with code",,"To Do","1",
"16505","Issue","Merge testing modules",,"To Do","3",
"16506","Issue","Open private preview for select customers",,"To Do","2",
"16507","Issue","Enable feature for customer champs",,"To Do","2",
"16508","Issue","Remove old test code",,"To Do","2",
,"Epic","Track Telemetry for data imports",,"To Do","2",

问：是否可以导入具有父子链接的 CSV 文件？

答：可以，可以通过缩进标题列来添加子工作项。 以下示例在已定义的长篇故事下添加三个子问题。

ID,Work Item Type,Title 1,Title 2,Assigned To,State,Priority,Tags
"165","Epic","Track Telemetry for data imports",,,"To Do","2",
,"Issue",,"Fix issues with code",,"To Do","1",
,"Issue",,"Open private preview for select customers",,"To Do","2",
,"Issue",,"Enable feature for customer champs",,"To Do","2",

问：如何得知我的已导入文件中是否有错误？

答：例如，可以通过添加带空格和连字符的标记来进行测试，并将其包含在导出中。 导入应匹配相同的格式。 CSV 文件格式设置中的任何问题都将显示在导入视图的“结果”页中。 在格式设置和语法准确无误之前，无法导入工作项。

工作项的结果始终列出为单个工作项找到的数据错误。 从 Web 门户或 CSV 文件中修复每个错误，然后再次导入。

问：为什么我收到某些标识值的错误？

答：使用 Web UI 时，标识选取器会执行额外的步骤来验证用户。 首先，它会检查此人是否是组织中的有效用户。如果不是，它将在 Microsoft Entra ID 中搜索标识。 如果该用户在 Microsoft Entra ID 中，但不在组织中，则该用户将添加到有效标识。

从 CSV 导入时，出于性能原因，标识选取器不会执行这些额外步骤。 它仅检查组织中是否已存在匹配的用户主体名称 (UPN)。如果找不到匹配的 UPN，则它会报告该标识未知。

问：CSV 导入是否支持所有工作项类型？

答：否，CSV 导入不支持以下工作项类型：

• 代码评审请求
• 代码评审响应
• 反馈请求
• 反馈响应
• 测试用例
• 测试计划
• 测试套件
• 共享参数

有关详细信息，请参阅批量导入或导出测试用例。

相关文章

• 工作项字段索引
• 使用 Excel 批量添加或修改工作项
• 常见问题解答：使用连接到 Azure Boards 的 Excel