在 Azure Boards 中定义工作项查询
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Visual Studio 2019 | Visual Studio 2022
工作项查询会根据你提供的筛选条件生成工作项列表。 你可以保存这些托管查询并与他人共享。
请查看本文后面的建议最佳做法。
先决条件
- 必须具有“利益干系人”访问权限才能查看和运行共享查询。 默认情况下，所有项目成员都具有利益干系人访问权限。 有关详细信息，请参阅更改共享查询或文件夹的权限。
- 必须具有“基本”访问权限或更高权限才能添加和保存共享查询。
- 对于要在其中添加查询的文件夹，必须将“参与”权限设置为“允许”。 默认情况下，“参与者”组没有此权限。
注意
对公共项目具有“利益干系人”访问权限的用户可以完全访问查询功能，就像具有“基本”访问权限的用户一样。 有关详细信息，请参阅利益干系人访问快速参考。
- 默认情况下，具有“利益干系人”访问权限的所有项目成员和用户都可以查看和运行所有共享查询。 可以更改为共享查询文件夹或共享查询设置的权限。 有关详细信息，请参阅设置查询权限。
- 若要在“共享查询”下添加和保存查询，必须获得“基本”访问权限或更高权限。 此外，对于要在其中添加查询的文件夹，必须将“参与”权限设置为“允许”。 默认情况下，“参与者”组没有此权限。
选择查询筛选器
在查询编辑器中，可以选择筛选器以跳转到包含示例查询的文章。 除了查询筛选器，还可以以交互方式将筛选器应用于查询结果。
注意
托管查询不支持邻近搜索，但语义搜索支持这样做。 此外，语义搜索还支持将 * 和 ? 作为通配符，你可以使用多个通配符来匹配多个字符。 有关详细信息，请参阅功能工作项搜索。
筛选功能
宏
Filter 函数以交互方式筛选查询。打开查询
在 Web 浏览器中，(1) 检查你是否选择了正确的项目，(2) 选择“面板”>“查询”，然后 (3) 选择“全部”。
如果这是你首次打开“查询”，页面将打开“收藏夹”。 此页列出了你指示加入收藏夹的查询。 否则，可以选择“全部”来查看已定义的所有查询以及为项目定义的共享查询。
提示
你或你的团队选择加入收藏夹的查询显示在“收藏夹”页面上。 加入收藏夹的查询以及其他对象也显示在“项目”页上。 有关详细信息，请参阅设置个人或团队收藏夹。
定义简单列表查询
通过 Web 门户中的“查询”选项卡或团队资源管理器中的“工作项”选项卡启动新的查询。
跨项目或在项目内查询
默认情况下，新查询的范围限定为当前项目。 但是，可以创建查询来查找组织或项目集合中定义的工作项。 但是，你保存的所有查询都会存在特定项目下。
若要列出在两个或更多个项目中定义的工作项，请选中“跨项目查询”。 例如，以下查询查找过去 30 天内在所有项目中创建的所有功能。
选中“跨项目查询”后，可以添加“团队项目”字段以筛选所选数量的项目。
注意
用与为你的客户端计算机定义的区域设置对应的列表分隔符（例如，逗号 (,)）分隔多个项目名称。
- 只有在选中“跨项目查询”后，“团队项目”字段才可用。
- 选中“跨项目查询”时，集合中所有项目中定义的所有工作项类型的所有字段都将显示在“字段”下拉菜单中。
- 取消选中“跨项目查询”时，只有在当前项目中定义的工作项类型的字段才会显示在“字段”下拉菜单中。
定义子句
要创建查询，请定义一个或多个子句。 每个子句定义单个字段的筛选条件。
示例查询子句
| 和/或 | 字段 | 运算符 | Value |
|---|---|---|---|
| And | 分配到 | = | @Me |
有关基于字段数据类型的可用运算符的列表，请参阅查询索引快速参考。
所有子句都作为 And 语句添加。 选择“Or”可以更改分组。 对子句进行分组，确保子句语句按所需的顺序运行。
选择“添加新子句”，在查询末尾添加另一个子句，然后为该子句选择“字段”、“运算符”和“值”。
例如，通过指定“分配到”字段、等于 (=) 运算符和表示用户标识的 @Me 宏来搜索已分配给你的所有工作项。
“删除子句”。
运行”或“
保存查询”。提示
若要查看查询的 WIQL 语法，以及如何使用括号对子句进行分组，请安装市场 Wiql 编辑器。 此扩展支持查看 WIQL 语法并将其导出到 WIQL 文件进行 REST API 调用。 有关详细信息，请参阅工作项查询语言 (WIQL) 的语法。
定义查询子句的清单
在第一个空行中，在“字段”列标题下方，选择下箭头以显示可用字段的列表，然后选择列表中的项。 有关详细信息，请参阅查询字段和值。
在同一行中，在“运算符”列标题下方，选择下箭头以显示可用运算符的列表，然后选择列表中的项。 有关详细信息，请参阅运算符。
在同一行中，在“值”列标题下，输入值或选择下箭头，然后选择列表中的项。 有关如何使用宏或变量指定当前项目、用户、日期或其他选择的详细信息，请参阅变量。
若要添加子句，请选择“添加新子句”。
可以将子句添加到查询末尾，也可以使用相应的图标执行以下任务：
插入新的筛选器行
删除此筛选器行
对所选子句进行分组
对子句取消分组
使用工作项树查看层次结构
使用“
工作项树”查询可以查看多层、嵌套的工作项列表。 例如，你可以查看所有积压工作 (backlog) 项及其链接的任务。 若要重点查看树的不同部分，请选择“
全部展开”或“
全部折叠”。
注意
不能构造显示测试计划、测试套件和测试用例的分层视图的查询。 这些项不会使用“父-子”链接类型链接在一起。 但是，可以创建列出与测试相关的工作项的直接链接查询。 此外，还可以通过“测试计划”页查看层次结构。
定义父工作项和子工作项的筛选条件。 若要查找链接的子级，请选择“首先匹配顶级工作项”。 若要查找链接的父级，请选择“首先匹配已链接的工作项”。
使用直接链接查看依赖项
使用“
工作项和直接链接”查询可以跟踪依赖于其他跟踪的工作的工作项，如任务、bug、问题或功能。 例如，可以查看取决于其他正在实现的项或正在修复的 Bug 的积压工作项。
使用直接链接查询跨团队跟踪依赖项。 该查询还有助于管理团队做出的承诺。 为顶部和链接的工作项选择筛选条件。 此外，选择链接类型以筛选依赖项。
通过选择下列选项之一来筛选第一层工作项列表：
- 仅返回具有匹配链接的项：返回第一层工作项，前提是返回的工作项具有链接工作项筛选条件所指定的工作项链接。
- 返回所有顶级项：返回所有第一层工作项，而不考虑链接工作项筛选条件。 如果链接到第一层的第二层工作项匹配链接的工作项筛选条件，则会返回第二层工作项。
- 仅返回不具有匹配链接的项：返回第一层工作项，前提是返回的工作项不具有链接工作项筛选条件所指定的工作项链接。
有关每个链接类型的详细信息，请参阅链接类型参考。
使用 and/or 逻辑表达式
指定 And 或 Or 创建查询子句的逻辑表达式。 使用 And 查找同时满足当前子句和前一个子句中的条件的工作项。 使用 Or 查找满足当前子句或前一个子句中的条件的工作项。
为每个工作项字段添加一个新子句，可以优化搜索条件。 添加子句以仅返回所需的工作项集。 如果未通过查询收到预期的结果，请对查询进行优化。 可以对查询子句执行添加、删除、分组或取消分组操作，从而改进查询结果。
对查询子句进行分组，使其作为独立于查询的其余部分的一个单元来运行。 对子句进行分组类似于在数学等式或逻辑语句中的某个表达式两侧加上括号。 在对子句进行分组时，组中第一个子句的 And 或 Or 会应用于整个组。
对子句进行分组
分组的子句作为独立于查询的其余部分的一个单元来运行。 对子句进行分组类似于在数学等式或逻辑表达式两侧加上括号。 组中第一个子句的 And 或 Or 运算符会应用于整个组。
如以下示例所示，分组的子句被转换成对应的逻辑表达式。
| 查询 | 分组子句 | 逻辑表达式。 |
|---|---|---|
| 1 |  |
 |
| 2 |  |
 |
| 3 |  |
 |
以下查询返回类型为 bug 并满足以下逻辑表达式的工作项：
- 查询 1：
AND State=Active OR Assigned to @Me - 查询 2：
AND (State=Active OR Assigned to @Me) - 查询 3：
OR (State=Active AND Assigned to @Me)
要对一个或多个子句分组，请选择这些子句，然后选择 
子句分组图标。
还可以对多个分组的子句进行分组。 选中每个子句的框。 然后，选择“ 对子句进行分组”图标。
如果查询结果未返回预期结果，请执行以下步骤：
- 确保每个子句按预期方式定义。
- 验证每个子句的
And/Or分配。 如果结果包含的工作项数量超出预期，通常原因是使用了Or子句而非And子句。 - 确定你是否需要分组或更改查询子句的分组以及每个分组子句的
And/Or分配。 - 添加更多查询子句以细化查询筛选条件。
- 检查可用于指定字段、运算符和值的选项。
- 请参阅本文后面的最佳做法。
对子句取消分组
要对子句取消分组，请为分组的子句选择 
取消子句分组图标。
在仪表板中查看查询结果
下面的两个小组件显示查询结果。 可以直接从这些小组件打开工作项。
- 分配给我的工作：列出分配给已登录用户的所有建议的或活动的工作项。 列出 ID、状态和标题字段。
- 查询结果小组件：显示简单列表、树或直接链接查询的结果。 可以配置通过小组件显示的字段、调整列字段的大小，以及展开和折叠树和直接链接查询。
有关详细信息，请参阅向仪表板添加小组件。
查看显示“父级”标题的查询结果小组件
可以查看显示“父级”标题的查询结果。 为此，请执行以下步骤：
- 创建用于筛选感兴趣的工作项的查询。 查询可以是简单列表、树或直接链接查询。
- 添加“父级”字段作为一个列。
- 将查询另存为“共享查询”或“团队收藏夹”。
- 将查询结果小组件添加到仪表板并配置查询。 确保将“父级”字段设置为显示。
下图演示了显示“父级”字段的查询结果小组件。
将查询定义为超链接
查询超链接使用工作项查询语言 (WIQL)，该语言类似于 Transact-SQL。 有关详细信息，请参阅工作项查询语言 (WIQL) 的语法。
注意
大多数浏览器对 URL 字符串强制实施 2000 到 2083 个字符的限制。
查询超链接语法
对 URL 语法的 WIQL 部分进行编码。 可以使用任何 URL 编码器工具对 URL 进行编码。
https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}
例如，以下超链接列出了 Fabrikam 组织的 FabrikamFiber/Web 区域路径下定义的所有活动 bug 的 ID 和标题。
https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'
解码的 WIQL 符合：
SELECT [System.ID], [System.Title]
FROM WorkItems
WHERE [System.TeamProject]='FabrikamFiber'
AND [System.WorkItemType]='Bug'
AND [System.State]='Active'
AND [System.AreaPath]='FabrikamFiber\Web'
注意
Azure Boards 查询的 WIQL 长度不得超过 32K 个字符。
查询超链接语法
https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}
例如，以下超链接列出了 FabrikamFiber/Web 区域路径下的所有 bug 的 ID、标题和状态。
http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%2C%20%5BSystem.State%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'%20%20
例如，请参阅以下非编码条目。
http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=
SELECT [System.ID], [System.Title], [System.State]
FROM WorkItems
WHERE [System.TeamProject]='FabrikamFiber'
AND [System.WorkItemType]='Bug'
AND [System.AreaPath]='FabrikamFiber\Web'
最佳实践
以下最佳做法适用于你可以创建的以下查询：
创建目标明确、选择性的查询
通过应用你的查询所需的所有筛选器来定义高度选择性的查询。 查询的选择性越高，结果集就越小。 结果集越小，查询的针对性和选择性就越高。
使用标记对工作项进行分类
使用工作项标记对工作项（而不是自定义字段）进行分类。 基于标记进行筛选的查询通常比基于字符串匹配项进行筛选的查询执行速度更快。
与自定义字段匹配或部分匹配不同，具有 Tags Contains 操作的查询不需要对所有工作项表进行完整扫描。
将 Contains words 用于字符串匹配
若要基于字符串匹配项进行筛选，请使用 Contains Words 而不是 Contains 运算符。 Contains Words 运算符对指定的字段运行全文搜索，此操作往往完成速度更快。
Contains 运算符会运行表扫描，该操作比 Contains Words 运算符慢。 而且，它还会消耗更多的 CPU 周期。 这些 CPU 周期可能会导致达到速率限制。 有关详细信息，请参阅速率和使用限制。
使用 In Group 运算符指定小型组
In Group 运算符根据一组值中的匹配项筛选工作项。 这组值对应于团队、安全组或工作跟踪类别中包含的值。 例如，你可以创建一个查询，用来查找分配给某个团队的任何成员的所有工作项。 或者，查找属于需求类别 (Microsoft.RequirementCategory) 的所有工作项。
基于包含大量成员的组进行筛选时，结果集往往更大且不具选择性。 此外，如果某个组对应于一个大型的 Microsoft Entra 组，则查询会产生相当大的成本，以便从 Microsoft Entra ID 解析该组。
避免使用求反运算符
求反运算符（例如 <>, Not In, Not Under, Not In Group）往往会生成非选择性查询和大型结果集。
仅在必要时使用求反运算符。 始终首先尝试查找替代方法。 例如，如果 Field1 具有值 A、B、C、D；指定 Field1 In A, B, C 子句，而不是求反的 Field1 <> D 子句。
避免字符串比较
包含字符串比较的查询会生成本身效率低下的表扫描。 相反，我们建议使用标记或特定的自定义字段作为替代方法，尤其是在查询性能不佳时。
限制使用 Or 运算符
限制查询中定义的 Or 运算符的数量。 使用更少的 Or 运算符时，查询的运行效果更好。 过多的 Or 运算符会使查询不具选择性。 如果查询运行缓慢，请将 Or 运算符子句重新排序到查询子句的顶部。
保存查询
由于进行了内部优化，已保存查询的性能往往优于未保存的查询。 当你计划重复使用查询时，请始终保存查询。 即使通过 REST API 运行 WIQL 查询，也要通过 Web 门户保存 WIQL 来执行 REST API 调用，使得它们不容易在将来出现性能回归。
运行查询
有时需要多次运行查询才能实现正确的优化计划。 务必要保存查询并在 30 分钟内运行多至 10 次。 这样，系统就可以检查并找到最适合你的查询的优化计划。
相关文章
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈