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

  • 项目

您可能需要基于 Visual Studio Application Lifecycle Management (ALM) 中其他位置发生的事件，或者基于 Visual Studio ALM 外部发生的事件，自动将工作项从一种状态转换为另一种状态。例如，您可能需要基于调用跟踪工具中发生的事件，自动将 Bug 从一种状态转换为另一种状态。工作项类型模型和工作项跟踪 API 已进行了扩展，以支持由其他系统自动转换工作项。

如果您有更改工作项状态的代码，则可以通过使用 ACTION 元素将您的操作与适当的状态转换相关联来对该代码进行一般化。可以将您的操作的值传递给 [WorkItem.GetNextState] 方法以获取该工作项的操作后状态。版本控制签入对话框使用此方法来解决 Bug 并关闭与签入相关联的任务。

ACTION 是 ACTIONS 的可选子元素。

说明说明

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

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

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

主题内容

  • ACTION 元素的语法

  • 支持自动化所需的步骤

  • 将状态转换和操作相关联

  • 转换操作详细信息

  • 自动转换错误检查

ACTION 元素的语法

ACTION 元素使用以下语法。value 特性指定操作的名称，并且它是必需的。对于操作，您应遵循与字段引用名称相同的命名约定。例如，Team Foundation 版本控制使用 Microsoft.VSTS.Actions.CheckIn 确定适合于与签入相关联的工作项的转换。有关更多信息，请参见工作项跟踪对象的命名约定。

<ACTION value="NameOfAction" />

minOccurs="0"

maxOccurs="unbounded"

支持自动化所需的步骤

若要将工具与工作项跟踪集成，该工具必须执行以下步骤：

  1. 确定在执行该操作时应将工作项转换为什么状态。

  2. 将工作项设置为“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">
   <ACTIONS>
      <ACTION value="microsoft.vsts.actions.checkin"/>
   </ACTIONS>
</TRANSITION>

返回页首

转换操作详细信息

使用状态转换操作在工作项的工作流中的不同时刻自动执行工作项转换。可以考虑以下有关转换操作的使用详细信息：

  • 转换操作是可选的。如果工作项实例的当前状态具有指定操作的操作条目，则转换将返回“to”状态。如果没有指定操作的操作条目，则返回值为 Null。集成会正常处理 Null 返回值。即：

    • 不失败。

    • 退出跟踪，或记录日志以指出：由于一个必需操作未找到，集成未执行自动转换。

  • 对于每种工作项类型，操作对于 From 状态/Action 对必须是唯一的。这意味着，工作项类型作者不能为同一操作指定多个“to”状态。

  • 但是，支持同一转换中的多个操作，以允许多个自动转换集成，如下面的示例所示：

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

  • 操作名称是只能使用英语字符的编程名称。

  • 操作名称应遵循与字段引用名称相同的引用命名空间约定，以避免操作名称在供应商和客户之间出现冲突。但是，此约定不会由工具强制执行。Visual Studio ALM 使用 Microsoft.VSTS.Actions.<your action>。

返回页首

自动转换错误检查

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

  • 用户操作自动转换   对于这种类型的自动转换，需要用户参与，以便对所发生的任何与规则有关的问题做出响应。您必须确保为发生的以下情况提供支持：工作项类型的作者添加了一个必需字段，而集成无法识别此字段。若要为此情况提供支持，请执行自动转换，然后检查工作项类型是否存在与规则的冲突。如果发现冲突，则显示表单以便用户解决。

  • 无人参与的自动化自动转换   前提必须是没有用户来解决这些问题。在这种情况下，集成将正常退出。错误日志中应说明已尝试自动转换，同时给出失败的原因。

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

为避免字段变为无效，请执行以下操作：

  • 为状态转换定义 DEFAULTREASON。

  • 对于在状态转换之后变为必填字段的字段，使用 DEFAULT 或 COPY 规则元素为该字段指定值。

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

返回页首

请参见

概念

应用字段规则的时间和位置

其他资源

Associating a State Transition with an Action