Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018
规则用于设置或限制对工作项字段的值分配。 有两种主要的规则类型:自动生成的规则和为流程或项目定义的自定义规则。 自动生成的规则可最大程度地减少为应按标准方式工作的领域添加自定义规则的需要。
定义自定义规则以支持业务用例。 根据字段的数据类型,你可以针对能够输入该字段的数据设置各种限制。 你可以为选取列表(下拉菜单)指定值、设置默认值、清除条目或限制更改。 通过条件规则,你可以基于不同字段值之间的依赖关系对字段应用规则。 你还可以限制能修改字段的人员或将规则的作用域限制为仅适用于组。
阅读本文以了解以下内容:
系统如何应用自动生成的规则
对系统字段的自定义规则定义施加的限制
可以应用的不同类型的自定义规则
如何计算规则
为继承进程与本地 XML 进程定义的规则之间的差异
为什么应最大程度地减少定义的自定义规则数
在定义自定义规则之前,请阅读
配置和自定义Azure Boards
,大致了解如何自定义Azure Boards以满足业务需求。
最大程度地减少为 WIT 定义的规则数。 虽然可以为 WIT 创建多个规则,但当用户添加和修改工作项时,添加规则可能会对性能产生负面影响。 当用户保存工作项时,系统将验证与其工作项类型字段关联的所有规则。 在某些情况下,规则验证表达式过于复杂,SQL 无法计算。
自动生成的规则
自动生成的规则可最大程度地减少为应按标准方式工作的领域添加自定义规则的需要。
状态转换规则
继承的进程为添加到工作流的每个自定义工作项类型和自定义状态动态生成整个任意到任意状态转换规则集。 从任何状态到任何状态的转换是有效的。
对于本地 XML 进程,必须在工作项类型定义的 节中
WORKFLOW
指定有效的转换。
状态转换和按/日期字段规则
By/Date 字段对应于
Created By/Date
、
Activated By/Date
、
Resolved By/Date
和
Closed By/Date
。
对于继承的进程,当您将工作项从一种状态转换为另一种状态时,会自动设置或清除这些字段。 “更改者/日期”字段不包含在内,因为它们会随每个工作项保存进行更新,并且与状态转换无关。
控制这些字段的默认规则和行为包括:
“已关闭
”状态始终包含在“
已完成
”状态类别中。
“已完成
”状态类别不可配置,并且仅与一个状态相关联。
对于敏捷和 CMMI 进程,此
“已关闭”
状态始终为
“已关闭
”,对于 Scrum 和基本进程,此状态始终为
“完成
”。
这些规则的自动生成受区域设置的影响,因为规则条件包含已本地化的州名称。 系统为不同的区域设置生成不同的规则。
仅为包含这些字段的工作项类型指定为这些字段自动生成的规则。 工作项类型可能不包含其中一个或多个字段。
当工作项类型具有自定义状态或工作项类型为自定义工作项类型时,需要这些规则。
这些规则仅适用于继承的进程;它们永远不会为托管 XML 或本地 XML 进程生成。
工作流状态与状态类别相关联,以支持看板中的工作流。 若要了解详细信息,请参阅
如何在积压工作和版块中使用工作流状态和状态类别
。
状态更改日期字段规则
这些规则在技术上比关闭日期/关闭日期规则简单得多,因为它们不依赖于任何特定状态。 对于任何工作项类型,相同的规则始终可用。 它们需要自动生成,因为某些 OOB 工作项类型不包含“状态更改日期”字段,因此当用户将此字段添加到自定义工作项类型时,也需要自动生成这些规则。 此处也适用于关闭日期/关闭日期规则的相同原则。
自定义规则
所有自定义规则都是可选的。 对于继承的进程,指定由条件加操作组成的规则。 对于本地 XML 进程,可以指定字段或工作流中的规则。
两个进程之间没有一对一映射。 在某些情况下,XML 元素规则是在继承进程的
“编辑字段
”对话框中定义的,而不是作为规则定义。 继承的进程不支持其他 XML 元素,如
FROZEN
、
MATCH
NOTSAMEAS
、、 。
注意以下事项:
始终强制实施规则,不仅在与表单交互时,还与其他工具交互时也是如此。 例如,将字段设置为只读不仅在工作项窗体上应用规则,而且还会通过 API 和 Excel Azure DevOps Server外接程序应用规则。
继承的进程条目指定创建完整规则的条件和操作。 XML 元素不会做出这些区别。
字段规则不支持赋值是其他两个字段的总和,也不支持执行其他数学计算。 但是,可以通过
TFS 聚合器 (Web 服务)
市场扩展找到符合需求的解决方案。 另请参阅
工时和其他字段的汇总
。
你可能会发现使用市场扩展(例如
工作项窗体控件库扩展
)将自定义规则应用于字段的其他解决方案。
对于继承的进程,每个规则由两个部分组成:条件和操作。 条件定义为应用规则而必须满足的条件。 操作定义要执行的操作。 对于大多数规则,最多可以指定两个条件,每个规则最多可以指定 10 个操作。 所有自定义规则都需要满足所有条件才能运行。
例如,可以根据分配给状态的值和另一个字段使字段成为必填字段。 例如:
(Condition) When a work item State is
Active
(Condition) And when the value of
值区域
=
业务
(Action) Then make required
故事点
目前,状态转换规则仅支持一个条件。 如果要基于状态应用规则,请参阅
将规则应用于工作流状态
。
下表总结了所选条件可用的操作。
支持的操作
本地 XML 过程使用 XML 元素定义规则。 所有这些规则元素都可以在
FIELD
工作项类型定义的定义中定义。 并且,除了
HELPTEXT
元素之外,可以指定这些规则在工作流转换期间生效,或者指定为 (全局工作流) 元素中的
FIELD
子元素。
VALIDUSER
TFS 2018 及更高版本不支持 元素。
应用字段规则的位置
如果希望规则在工作项的整个生命周期内应用于字段,请在 节中
FIELD
指定它。 例如,对于新的活跃 bug,字段保持必填,直至 bug 关闭。 否则,如果希望根据“状态”、“原因”或“转换”中的更改应用它,请在 节中
WORKFLOW
指定它。
State
(System.State) 和
Reason
(System.Reason) 字段在 节中
WORKFLOW
定义。 你可以指定在更改状态、选择原因或进行特定转换期间应用于字段的大多数字段规则。 若要了解详细信息,请参阅
更改工作项类型的工作流
。
否则,请指定将仅在状态更改时计算的规则。 这些规则在 、
REASON
或
TRANSITION
元素下的 节中
WORKFLOW
STATE
定义。 除 之外
HELPTEXT
的所有规则都可以在 (Workflow) 元素中
FIELD
应用。
字段规则是附加的。 也就是说,可以为同一字段指定四组规则,这些规则将由规则引擎评估。
无论工作项在其状态模型中的位置如何,工作项
类型特定的
规则都适用。 例如,规则
<REQUIRED \>
执行以下检查:
"MyField Value" != NULL
当
工作项实例处于特定状态时,特定于状态的规则将范围限定为工作项实例。 当以下条件为真时,强制实施特定于状态的规则:
State field value == "MyState" && "MyField Value" != NULL
为特定
转换指定的转换特定
转换规则的范围限定为正在进行特定转换的工作项。 当以下条件为真时,强制执行这些规则:
State field value == "ToState" &&
"Previous State Before Edit/New" == "FromState"
&& "MyField Value" != NULL
你为特定
原因指定的特定于
原因的规则的范围限定为特定转换的特定原因。 当以下条件为真时,处理这些规则:
Reason field == "MyReason" &&
State field value == "ToState" &&
"Previous State Before Edit/New" == "FromState" && "MyField Value" != NULL
下面的示例限制当工作项处于“活动”状态时客户严重级别字段的修改。
<STATE name="Active">
<FIELDS>
<FIELD refname="MyCorp.Severity" >
<READONLY />
</FIELD>
</FIELDS>
</STATE>
定义过多规则时会发生什么情况
每个项目定义一个 SQL 表达式,用于在创建或更新工作项时对其进行验证。 此表达式随着为项目定义的所有工作项类型指定的规则数而增长。 为字段指定的每个行为限定符都会增加子表达式的数量。 嵌套规则(仅适用于转换或以其他字段的值为条件的规则)会导致将更多条件添加到 IF
语句中。 表达式达到特定大小或复杂性后,SQL 无法再对其进行计算,并生成错误。 删除某些 WIT 或消除某些规则可以解决错误。
你可以为选取列表(下拉菜单)指定值、设置默认值、清除条目或限制更改。 通过条件规则,你可以基于不同字段值之间的依赖关系对字段应用规则。 你还可以限制能修改字段的人员或将规则的作用域限制为仅适用于组。
工作项规则不作为单个集合存在。 这些规则实际上是从不同的数据源动态生成和合并的。 合并逻辑很简单,可以合并相同的规则,但不要剪裁冲突的规则。
通常,当用户修改工作项时,规则引擎会验证所有工作项。 但是,为了支持某些方案,分配了 绕过工作项更新规则 项目级权限的用户可以保存工作项,而无需评估规则。
可以通过以下两种方式之一绕过规则。 第一个是通过 工作项 - 更新 REST API 并将 参数设置为 bypassRules
true
。 第二种是通过客户端对象模型,在旁路规则模式下初始化 (使用 WorkItemStoreFlags.BypassRules
) 进行初始化WorkItemStore
。
系统字段和自定义规则
系统字段具有“系统”。名称 引用名称,例如 System.Title 和 System.State。
以下系统字段需要有一个值: 区域 ID、 更改日期、 创建日期、 创建者、 状态和 原因。
规则引擎将设置条件或操作限制为系统字段,但如下所示:
可以将 “状态” 和 “原因 ”字段设为只读。
可以将大多数规则应用于 “标题”、“ 分配到”、“ 说明”和 “更改者” 字段。
如果在继承过程的规则用户界面的下拉菜单中未看到列出字段,则这就是原因。 例如,如果 尝试根据条件 使 System.AreaPath (区域路径) 只读,则“区域路径”字段无法进行选择。 即使你可以指定系统字段,规则引擎也可能限制你保存规则。
默认和复制规则
默认和复制规则修改工作项字段的值。 它们定义运行时行为和约束,例如指定默认值、清除字段、要求定义字段等。
可以基于当前用户的组成员身份限制这些规则的应用,如 用户或组成员身份规则限制中所述。
当用户在创建或修改工作项时,为空的字段指定值。 如果字段已具有值,则忽略该 DEFAULT
规则。 仅当字段的值当前为空时 Is
,默认规则才会执行。 支持的值包括当前时间 () from = "clock"
、当前用户 () from = "currentuser"
、 () from = "value" value = "literal"
的文本值或另一个字段 (from = field field = "referenceNameField"
) 的值。
<FIELD refname="MyCorp.Priority" name="Priority" type="String"
<HELPTEXT>Specify the severity of the problem</HELPTEXT
<ALLOWEDVALUES
<LISTITEM value="P1"/
<LISTITEM value="P2"/
<LISTITEM value="P3"/
</ALLOWEDVALUES
<DEFAULT from="value" value="P3"/
</FIELD
<TRANSITION from="New" to="Active">
<ACTIONS>
<ACTION value="Microsoft.VSTS.Actions.StartWork" />
</ACTIONS>
<REASONS>
<DEFAULTREASON value="Work started" />
</REASONS>
<FIELDS>
<FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
<COPY from="currentuser" />
<VALIDUSER />
<REQUIRED />
</FIELD>
<FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
<SERVERDEFAULT from="clock" />
</FIELD>
<FIELD refname="System.AssignedTo">
<DEFAULT from="currentuser" />
</FIELD>
</FIELDS>
</TRANSITION>
防止用户在指定值后清除字段的值。 此元素保留当前字段值,无法将其清除或留空。
<FIELD refname="MyCorp.Priority" name="Management Priority" type="String">
<CANNOTLOSEVALUE />
</FIELD>
防止用户在包含值后更改字段的值。 一旦用户将工作项和值保存在该字段,该值将无法再被修改。 提交更改后,冻结字段无法更改为任何非空值。 但是,您可手动清除此字段,保存工作项,然后指定其他值。
<FIELD refname="MyCorp.Priority" name="Management Priority" type="String">
<FROZEN not="[Project]\Management Team" />
</FIELD>
清除包含任何值的字段,然后在用户保存工作项时将字段设置为只读。 不应将 与 一起使用EMPTY
READONLY
。
EMPTY
主要在 状态转换期间 使用,以清除应用于项目转换到的状态的字段。
<FIELD refname="MyCorp.SubStatus" />
<WHEN field="MyCorp.Status" value="Approve" >
<EMPTY />
</WHEN>
</FIELD>
强制对字符串字段进行的条目符合 指定的字符或数字模式。 如果定义多个 MATCH
元素,则如果值与指定的任何模式匹配,则该值被视为有效。 如果至少有一个元素成功,则字段具有有效值。
<FIELD refname="MyCorp.GitHubURL" name="GitHub URL" type="String">
<MATCH pattern="https:\/\/github\.com\/\S+[\.md|\.yml]$"/>
</FIELD>
<FIELD refname="MyCorp.Status" name="Status" type="String">
<NOTSAMEAS field="MyCorp.SubStatus" />
</FIELD>
防止修改字段。 你可能希望在特定情况下应用此规则。 例如,在工作项关闭后,你希望使字段成为只读字段以保留数据进行报告。
不要与 元素一起使用 READONLY
, EMPTY
因为 EMPTY
也会使字段为只读。 组合这些元素可能会产生不一致的结果。
此外,还可以使用 Control
元素 ReadOnly
属性使工作项窗体中的字段显示为只读。 可通过其他客户端写入该字段,但无法通过工作项窗体进行。
<FIELD refname="MyCorp.Status" name="Status" type="String">
<READONLY />
</FIELD>
要求用户为字段指定值。 用户无法保存工作项,除非已对所有必填字段分配了值。
<FIELD refname="MyCorp.Status" name="Status" type="String">
<REQUIRED />
</FIELD>
使用下表中列出的 XML 元素定义选取列表。 有关语法结构和示例,请参阅 定义选取列表。
你可以组合列表,展开或收起列表。 此外,还可以根据当前用户的组成员身份限制这些规则的应用,如 用户或组成员身份规则限制中所述。
XML 元素
为了避免在成员离开团队且不再注册为项目参与者时发生的验证错误,请为“分配到”字段添加 ALLOWEXISTINGVALUE 元素。
<FIELD name="Assigned To" refname="System.AssignedTo" type="String" syncnamechanges="true" reportable="dimension">
<HELPTEXT>The user who is working on this work item</HELPTEXT>
<ALLOWEXISTINGVALUE />
<VALIDUSER />
<ALLOWEDVALUES expanditems="true" filteritems="excludegroups">
<LISTITEM value="Active" />
<LISTITEM value="[project]\Contributors" />
</ALLOWEDVALUES>
<DEFAULT from="field" field="System.CreatedBy" />
</FIELD>
Set the value of ...
Use the current time to set the value of ...
Use the current user to set the value of ...
指定要对特定字段执行的操作。
以下 XML 元素用于设置评估其他规则时的条件。 每个字段可以指定多个条件规则。 但是,每个条件规则只能指定一个驱动字段。 不能嵌套条件规则。 每个进程模型支持的操作包括下表中列出的操作。
有关语法结构和示例,请参阅 分配基于条件的值和规则。 可以基于当前用户的组成员身份限制这些规则的应用,如 用户或组成员身份规则限制中所述。
XML 元素
用户或组成员身份规则限制
可以根据当前用户的成员身份限制规则的应用。 建议将规则的范围限定为 Azure DevOps 安全组,而不是单个用户,尽管可以指定后者。 若要将规则的范围限定为多个组,必须创建一个父 Azure DevOps 组,其中包含要使用的组集。
若要避免可能出现的规则评估问题,请指定 Azure DevOps 安全组,而不是 Azure Active Directory 或 Active Directory 安全组。 若要了解详细信息,请参阅 默认规则和规则引擎。
若要根据当前用户的成员身份限制规则,请在 rule 元素中指定 for
或 not
属性。 指定规则的范围。 若要将规则的范围限定为多个组,必须创建一个父 Azure DevOps 组,其中包含要使用的组集。
使用 和 not
的组合for
可同时将规则应用于某些规则,而不是将规则应用于其他人。 本示例将“严重级别”定义为“项目成员”组中用户的必填字段,但不是“项目管理员”组中用户的必填字段。 如果用户在这两个组中, for
将强制实施 语句,并且 需要 字段。
<FIELD name="Severity">
<REQUIRED for="[Project]\Project Members" not="[Global]\Project Admins"/>
</FIELD>
[ProjectName],例如 [Fabrikam]、[FabrikamFiber]、[MyProject]
[OrganizationName],例如 [fabrikam]、[myorganization]
[CollectionName],例如 [fabrikam]、[myorganization]
若要了解可用于项目或组织的范围,请转到“项目设置权限>组”>或“组织设置权限>组”>页,可以根据需要筛选列表。 例如,下图显示了基于 Azure DevOps 的筛选列表的前四个条目。 若要了解详细信息,请参阅更改项目级权限或更改项目集合级别权限。
令牌的示例包括以下内容:
[Project],如 [Project]\Contributors, [Project]\Fabrikam Team, [Project]\Project 审批者 [Project] 标记指定为项目定义的组。 这可以对应于团队、默认或自定义安全组或已添加到项目的 Active Directory 组。
[GLOBAL],用于引用集合范围的组,例如 [GLOBAL]\Project Collection Administrators 使用 [GLOBAL] 引用集合范围的安全组,例如 Project 集合管理员组或添加到集合的 Windows 组。 例如:<FIELD name="Title">
<READONLY for="[GLOBAL]\Project Collection Valid Users"/>
</FIELD>
[Team Foundation] 引用服务器范围的组,例如 [Team Foundation]\Team Foundation 管理员使用 [Team Foundation] 引用服务器范围的组,例如添加到服务器级别组的内置组或 Windows 组。 例如:<FIELD name="Title">
<READONLY for="[Team Foundation]\Team Foundation Valid Users"/>
</FIELD>
[DomainName] 用于引用服务器范围的组,例如 [Team Foundation]\Team Foundation Administrators 域限定帐户名(如以下示例中显示的帐户名称)可用于引用域用户或组。 某些规则仅支持组,不支持引用域用户。
<LISTITEM value="FABRIKAM\Christie Church's Direct Reports"/>
[Project]、[GLOBAL]和 [Team Foundation] 按原样使用。 不要将它们替换为项目、集合或服务器名称的名称。
若要了解可用于项目或集合的范围,请转到 项目设置>权限>组 或 集合设置>权限>组 页。 根据需要筛选列表。 例如,下图显示了基于 Azure DevOps 的筛选列表的前四个条目。 若要了解详细信息,请参阅更改项目级权限或更改项目集合级别权限。
所有用户和组必须由其中一个令牌限定。 例如,以下 XML 无效,因为它没有使用有效令牌限定指定的组。
<FIELD name="Title">
<READONLY for="Dev Team"/>
</FIELD>
若要详细了解默认安全组,请参阅 权限和组
根据修改工作项的用户或组成员身份指定条件的规则采用以下两种方式之一进行评估。 评估规则时,应用程序需要通过检查该用户是否是指定组的成员来确定该规则是否适用于当前用户。
从 Web 门户、REST API 或 azure boards 命令修改工作项时,会向 Azure Active Directory 或 Active Directory 发出请求。 此操作不会出现问题。
使用 WIT 客户端对象模型从 Visual Studio、Excel 或其他自定义工具修改工作项时,评估成员身份的请求基于客户端缓存。 客户端缓存无法识别 Active Directory 组。
针对使用 GIT 的项目的 Visual Studio 2019 团队资源管理器已重新编写为使用 REST API。
若要避免用户从各种客户端更新工作项时出现问题,请指定 Azure DevOps 安全组而不是 Active Directory 组。 可以轻松创建 Azure DevOps 安全组来对应于 Active Directory 组。 若要了解如何操作,请参阅 添加或删除用户或组,管理安全组。
WIT 客户端 OM 已弃用。 从 2020 年 1 月 1 日起,在针对Azure DevOps Services和 2020 Azure DevOps Server工作时不再支持它。
计算规则的顺序
规则通常按列出顺序进行处理。 但是,评估所有规则的完整顺序并不完全确定。
本部分介绍应用条件、副本和默认规则时的预期行为和交互。
本地 XML 流程
以下步骤按正确的顺序显示 Azure DevOps 执行的交互,以及由工作项表单的用户执行的交互。 仅步骤 1、8 和 13 是由用户执行的。
在 Azure DevOps 客户端(如 Web 门户或 Visual Studio 团队资源管理器)中,用户创建新的工作项或编辑现有工作项。
填写字段默认值。 对于所有字段,请应用分配给不属于条件子句的字段的任何默认值。
复制或设置字段值。 对于所有字段,应用任何规则来复制值或设置不属于条件子句的字段的值。
对于具有匹配的 When 条件规则的所有字段,应用规则来设置或复制字段值。
对于具有匹配的 When Not 条件规则的所有字段,应用规则来设置或复制字段值。
系统始终处理 When规则,而不是 规则。
对于自步骤 1 以来已更改其值且包含 更改 规则的所有字段,应用规则来设置或复制字段值。
允许用户开始编辑。
用户更改字段值,然后从字段移动焦点。
处理与新值匹配的该字段的任何 When 规则。
处理与新值匹配的字段的任何 When Not 规则。
处理与新值匹配的字段的任何 “更改时 ”规则。
返回用户的编辑能力。
用户将更改保存到数据存储区。
对于所有字段,应用在条件规则下直接或间接为字段定义的任何 Use the current time to set the value of ...
操作。
规则通常按列出顺序进行处理。 但是,使用 WHEN、 DEFAULT 和 COPY 元素时,可能会应用其他行为。 以下步骤按正确的顺序显示 Azure DevOps 执行的交互,以及由工作项表单的用户执行的交互。 仅步骤 1、8 和 13 是由用户执行的。
在 Azure DevOps 客户端(如 Web 门户或 Visual Studio 团队资源管理器)中,用户创建新的工作项或编辑现有工作项。
填写字段默认值。 对于所有字段,应用在规则或 WHEN 规则外部指定的任何 DEFAULT 规则。
复制字段值。 对于所有字段,请使用 WHEN 子句外部的任何 COPY 规则。
对于具有匹配的 WHEN 规则的所有字段,首先执行 DEFAULT ,然后在其中 复制 规则。
对于具有匹配的 WHENNOT 规则的所有字段,请先执行 DEFAULT ,然后在其中 复制 规则。
系统始终在 WHENNOT 规则之前处理 WHEN 规则。
对于自步骤 1 以来已更改其值且包含 WHENCHANGED 规则的所有字段,请先执行 DEFAULT ,然后在其中 复制 规则。
允许用户开始编辑。
用户更改字段值,然后从字段移动焦点。
为该字段引发与新值匹配的任何 WHEN 规则。
为该字段引发与新值匹配的任何 WHENNOT 规则。
为该字段引发与新值匹配的任何 WHENCHANGED 规则。
返回用户的编辑能力。
用户将更改保存到数据库。
对于所有字段,执行在 WHEN 或 WHENNOT 规则下直接或间接为字段定义的 SERVERDEFAULT 操作。
击键项和规则评估
每当用户通过工作项窗体在字段中输入击键时,系统都会为字段设置一个新值。 这意味着,只要满足规则的先决条件条件,条件规则可能会意外发生。
在以下 XML 示例中,系统会在“状态”字段中键入“再次批准”时清空 MyCorp.SubStatus,因为只要用户在“已批准”中键入字母“e”,就会立即出现 WHEN 规则,即使预期的最终值不是“Approv”。 因此,当你使用条件规则时,请细致思考。
<FIELD refname="MyCorp.SubStatus" />
<WHEN field="MyCorp.Status" value="Approve" >
<EMPTY />
</WHEN>
</FIELD>