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

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

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

ACTION 是 ACTIONS 的可选子元素。

备注

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

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

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

主题内容

  • ACTION 元素的语法

  • 支持自动化的所需步骤

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

  • 转换操作详细信息

  • 自动转换错误检查

ACTION 元素的语法

可对 ACTION 元素使用下列语法。 值属性(必需)指定操作名称。 对于操作,你应遵循与字段引用名称相同的命名约定。 例如,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

  • 对于在状态转换后变为必需字段的字段,请使用 DEFAULTCOPY 规则元素为该字段指定值。

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

请参见

其他资源

将规则应用于工作项字段

Associating a State Transition with an Action