基于状态、转换或原因自动进行字段赋值

项目
08/06/2022

Azure DevOps Server 2020 |Azure DevOps Server 2019 |TFS 2018

你可能希望根据 Azure DevOps 项目内部或外部发生的事件自动将工作项从一个状态转换为另一个状态。例如，你可能需要基于调用跟踪工具中发生的事件自动将 Bug 从一种状态转换为另一种状态。已对工作项类型模型和工作项跟踪 API 进行了扩展，以支持由其他系统自动转换工作项。

如果代码更改工作项的状态，则可以通过使用 ACTION 元素将操作与适当的状态转换相关联来通用化该代码。可以将操作的值传递给 [WorkItem.GetNextState](assetId:///WorkItem.GetNextState?qualifyHint=False&autoUpgrade=True) 方法，以获取该工作项的后操作状态。版本控制签入对话框使用此方法来解决 Bug 并关闭与签入相关联的任务。

ACTION 是 ACTIONS 的可选子元素。

注意

工作项跟踪 API 是 Visual Studio ALM SDK 的一部分，如 Microsoft 网站上的以下页面所述：扩展 Team Foundation。

例如，将某个工具预设为在用户签入更改后自动将工作项转换为“已解决”状态。但是，作为集成提供商，你不知道工作项类型作者将什么状态声明为“已解决”。该作者可能表示“已解决”、“已关闭”、“已完成”、“已做好测试准备”、“包含版本”等。有一种方法是要求所有工作项类型作者包括显式命名为“已解决”的状态。

该解决方案的限制性太强。而且从国际化的角度来看也不甚理想，因为它不支持状态本地化。相反，系统集成人员可以声明包含工作项自动转换的操作，例如“签入”或“完成”。然后，工作项类型作者可在相应中的转换过程中声明此操作。

ACTION 元素的语法

以下语法用于 ACTION 元素。值属性（必需）指定操作名称。对于操作，你应遵循与字段引用名称相同的命名约定。例如，Team Foundation 版本控制使用 Microsoft.VSTS.Actions.CheckIn 来确定适合与签入关联的工作项的转换。有关详细信息，请参阅工作项跟踪对象的命名约定。

<ACTION value="NameOfAction" />

系统定义的操作

下表描述了在选择 XML 定义文件中出现的系统定义操作。

系统操作

说明

工作项类型

Microsoft.VSTS.Actions.CheckIn

此操作在签入时转换与更改集关联的工作项的状态。仅在将代码签入 TFVC 存储库并且工作项已链接到更改集时有效， (请参阅注释 1) 。

Bug (敏捷、CMMI) 、更改请求、代码评审请求、问题、要求、任务、用户情景

Microsoft.VSTS.Actions.StartWork

此操作支持 Visual Studio 团队资源管理器 “我的工作 ” (请参阅说明 2) 功能，在开发人员将工作项移动到“正在进行”时转换工作项的状态。状态会自动从 “新建 ”移动到 “活动 ” (敏捷) ，从“ 做 ”和“ 正在进行 ” (Scrum) ，从 “建议 ”移动到 “活动 (CMMI) ，从 ”做到做 “ (基本) 。仅在开发在 TFVC 存储库中维护的代码时才有效。

Bug、任务

Microsoft.VSTS.Actions.StopWork

此操作支持 Visual Studio 团队资源管理器 “我的工作 ”功能，用于在开发人员将工作项移动到“挂起的工作”时转换工作项的状态。状态会自动从 “活动 ”移动到“ 新建 ” (敏捷) ，从 “正在进行 到执行 ” (Scrum) ，从 “主动 ”移动到 “建议 (CMMI) ”，从 “执行 ” (基本) 到 “完成”。仅在开发在 TFVC 存储库中维护的代码时才有效。

Bug、任务

获取详细信息

有关将工作项链接到更改集的详细信息，请参阅使用 Visual Studio 在 TFVC 中开发和共享代码，快照 (签入) 代码。
有关 “我的工作”的详细信息，请参阅 Devops 开发人员生活中的一天：暂停工作、修复 bug 并执行代码评审。

支持自动化的所需步骤

如需将工具与工作项跟踪集成，则该工具必需执行下列步骤：

确认在执行操作时将工作项转换成何种状态。
将工作项设置为 "to" 状态。

工作项跟踪 API 提供了执行这些步骤的方法。工作项跟踪 API 是 Visual Studio ALM SDK 的一部分。有关详细信息，请参阅 Microsoft 网站上的以下页面： Team Foundation Server SDK。

备注

不会记录导致特定状态转化的事务操作。如果必须跟踪导致转化的操作，你可以指定其他工作项字段进行跟踪，也可定义“原因”值。

将状态转换与操作相关联

通过状态转换操作，可以在工作项的不同工作流位置完成自动转换。例如，Team Foundation Server 版本控制系统必须支持在签入时自动转换工作项。为了支持此操作，已定义操作 microsoft.vsts.actions.checkin 。

工作项类型作者可定义状态为“正在进行”的“缺陷”工作项类型，并在开发人员进行更改时使用此工作项。工作项类型作者还可定义名为“生成工作准备就绪”的状态，这表示开发人员已经声明，受缺陷影响的代码已经准备夜间生成。

作者通过声明以下内容，可以在签入操作期间将工作项状态从“正在进行”自动转化为“生成工作准备就绪”。

<TRANSITION from="Working" to="Ready To Build">  
   <REASONS>
      ...
   </REASONS>
      <ACTIONS>  
      <ACTION value="microsoft.vsts.actions.checkin"/>  
      </ACTIONS>  
</TRANSITION>

转换操作详细信息

通过状态转换操作，可以在工作项的不同工作流位置完成自动转换。可以考虑以下有关转换操作的使用详细信息：

转换操作是可选的。如果工作项实例的当前状态具有指定操作的操作条目，则将返回 "to" 状态。如果没有，则将返回 Null。集成会正常处理 Null 返回值。即：
- 不失败。
- 退出跟踪，或记录日志指出：由于未找到必需的操作，集成未执行自动转换。
对于每种工作项类型，必须向 From 状态/Action 对执行唯一操作。即表示工作项类型作者不得为同一操作指定多个 "to" 状态。

然而，支持同一转换中的多种操作，以允许多个自动转换集成，如下所示：

<TRANSITION from="Working" to="Ready To Build">  
   <REASONS>
      <DEFAULTREASON value="Fixed" />
   </REASONS>
      <ACTIONS>  
      <ACTION value="Microsoft.VSTS.Actions.Checkin"/>  
      <ACTION value="ADatum.Actions.Complete"/>  
      </ACTIONS>  
</TRANSITION>

操作名称是只能采用英文字符的编程名称。
操作名称应当遵循与字段引用名称相同的引用命名空间约定，从而避免在供应商和客户之间出现操作名称冲突。但是，此约定不会由工具强制执行。 Visual Studio ALM 使用 Microsoft.VSTS.Actions。<你的操作>。

自动转换错误检查

集成人员可以尝试两种自动转换。第一种是由于用户操作而导致的自动转换。第二种是由无人参与的自动化操作（例如夜间生成）而导致的自动转换。

用户操作自动转换 对于此类自动转换，用户会显示对出现的任何规则相关问题做出反应。如果工作项作者添加了一个集成无法识别的字段，你必须确保对此产生的情况提供支持。要提供支持，请执行自动转换操作，然后检查工作项类型是否存在与规则的冲突。如果发现冲突，则显示表单以便用户解决。
无人参与的自动化自动转换 必须假定没有用户能够解决这些问题。在这种情况下，集成将正常退出。错误日志中应说明已尝试自动转换，并说明失败原因。

定义任何一种类型的自动转换时，转换的定义方式应使每个工作项在转换结束时达到有效状态，而无需用户干预。也就是说，通过为所有字段提供默认值或复制的值来满足为转换的目标状态而定义的所有规则。如果任何字段在转换后变为无效，则状态转换失败。

为防止字段变为无效，请执行下列操作：
定义状态转换的 DEFAULTREASON 。
对于状态转换后所需的字段，请使用 DEFAULT 或 COPY 规则元素为字段指定值。

例如，你已经创建转换操作“签入”，此操作将工作项状态从“正在进行”转换为“生成工作准备就绪”。工作项的“生成工作准备就绪”规则要求设置“解决者”字段。然后，在 TRANSITION 部分为“ResolvedBy”定义 DEFAULT 或 COPY 规则元素。此外，你将定义 DEFAULTREASON ，以确保无需用户干预即可设置所需的字段。