Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

可以使用 WIQL 语法 将查询定义为超链接 ，或者在使用 工作项查询语言 (REST API) 时使用。

WIQL 语法支持通过 Web 门户提供的所有函数查询编辑器以及更多函数。 可以指定要返回的字段，并指定查询子句的逻辑分组。 此外，可以使用 ASOF 子句根据基于上一个日期的分配进行筛选。

WIQL 语法用于执行 通过 Wiql REST API 查询 。 目前，无法调用 API 以直接从 WIQL 查询返回详细的工作项信息。 无论在 SELECT 语句中包含哪些字段，API 都仅返回工作项 ID。 若要获取完整信息，需要执行两个步骤：(1) 从 WIQL 获取工作项的 ID，(2) 通过 按 ID 和为特定字段获取工作项列表 获取工作项。

查询仅返回你拥有“查看工作项”或“查看此节点中的工作项”权限的那些工作项。 通常，这些权限将授予每个团队项目的“访问者”和“参与者”组的成员。 有关详细信息，请参阅 权限和组 。

查询语言概述

工作项查询语言包括五个部分，如下表所示的语法代码片段所示。 WIQL 语法不区分大小写。

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2020'
通过安装 Wiql 编辑器市场扩展，可以使用查询编辑器构造查询，然后查看 WIQL 语法。 然后，可以使用添加到“Boards”的 Wiql Playground 中心复制和修改 WIQL 语法并运行查询。
比较中使用的引号（支持单引号或双引号）日期/时间文本。 它们必须采用运行查询的本地客户端计算机的 .NET 日期/时间格式。 除非指定了时区，否则日期/时间文本采用本地计算机的时区。
WHERE 
   AND [System.ChangedDate] >= '01-18-2019 GMT'
   AND ([Closed Date] < '01-09-2022 GMT'
   OR [Resolved Date] >= '01-18-2019 14:30:01')  
如果日期/时间文本中省略了时间，并且 dayPrecision 参数等于 false，则假定时间为零点（午夜）。 dayPrecision 参数的默认设置为 false。
或者，可以指定无论区域设置为何都有效的 ISO 8601 格式。 ISO 8601 表示日期和时间，从年份开始，然后是月、日、小时、分钟、秒和毫秒。 例如，2021-12-10 15:00:00.000 表示当地时间 2021 年 12 月 10 日下午 3 点。 使用 ISO 8601 格式的示例如下所示。
WHERE 
   AND [System.ChangedDate] >= '2019-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2022-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2019-01-18T00:00:00.0000000')  
自定义字段
可以将自定义字段添加到查询子句。 使用 WIQL 时，必须指定自定义字段的引用名称。 对于使用继承的流程模型的项目，自定义字段的名称前面通常会加上“Custom.”，并移除空格。 例如：
指定筛选器子句 (WHERE)
WHERE 子句指定筛选器条件。 此查询仅返回符合指定条件的工作项。 例如，下面的示例 WHERE 子句将返回处于活动状态并分配给你的用户情景。
WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me
可以通过将逻辑运算符括在括号中来对筛选器条件进行分组，以便控制计算顺序。 例如，若要返回分配给你的或者你关闭的工作项，可以更改查询筛选器以匹配以下示例。
WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
筛选器条件
每个筛选器条件由三个部分组成，每个部分必须符合以下规则：
字段：可以指定引用名称或友好名称。 以下示例是有效的 WIQL 语法：

引用名称：SELECT [System.AssignedTo]  ...
带空格的友好名称：SELECT [Assigned To]  ...
不带空格的名称不需要方括号：SELECT ID, Title  ...
运算符：本文后面的运算符部分指定了有效值。
字段值：根据指定的字段，可以指定以下三个值之一。
文本值必须与字段值的数据类型匹配。
指示特定值的*变量或宏。 例如，@Me 指示正在运行查询的人员。 有关详细信息，请参阅本文后面的宏和变量。
另一字段的名称。 例如，可以使用 [Assigned to] = [Changed by] 查找分配给最近更改过工作项的人员的工作项。
有关所有系统定义字段的说明和引用名称，请参阅工作项字段索引。
查询使用逻辑表达式来限定结果集。 这些逻辑表达式由一个或多个连接运算构成。
下面列出了一些简单的查询操作。
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'
下表汇总了不同字段类型支持的所有运算符。 有关每种字段类型的详细信息，请参阅工作项字段和属性。
=, <>, >, <, >=, and <= 运算符按预期工作。 例如，System.ID > 100 将查询 ID 大于 100 的所有工作项。 System.ChangedDate > '01-01-19 12:00:00' 将查询在 2019 年 1 月 1 日中午之后更改的所有工作项。
除了这些基本运算符之外，还有一些特定于某些字段类型的行为和运算符。
可用的运算符取决于平台和版本。 有关详细信息，请参阅查询快速参考。
支持的运算符
可以使用术语 AND 和 OR 在典型布尔意义上计算两个子句。 指定 WAS EVER 运算符时，可以使用术语 AND EVER 和 OR EVER。 可以根据需要对逻辑表达式进行分组和进一步连接。 下面显示了示例。
WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
可以使用 not 对 contains, under, 和 in 运算符求反。 不能对 ever 运算符求反。 下面的示例将查询未分配在 Fabrikam Fiber\Account Management 的子树下的所有工作项。
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'
示例查询，曾分配给
以下查询编辑器示例将查找曾经分配给 Jamal Hartnett 的所有工作项。
下面是相应的 WIQL 语法。
SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
下表列出了可在 WIQL 查询中使用的宏或变量。
使用此变量可在包含用户别名的字段中自动搜索当前用户的别名。 例如，如果将“字段”列设置为“激活者”，将“运算符”列设置为 =，将“值”列设置为“@Me”，则可查找你打开的工作项。
@CurrentIteration
使用此变量可根据所选团队上下文自动筛选分配给所选团队的当前冲刺 (sprint) 的工作项。
@Project
使用此变量可搜索当前项目中的工作项。 例如，如果将“字段”列设置为“团队项目”，将“运算符”列设置为 =，将“值”列设置为“@Project”，则可查找当前项目中的所有工作项。
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear
使用这些宏可以基于当前星期几、月、年或这些值之一的偏移量筛选“日期/时间”字段。 例如，如果将“字段”列设置为“创建日期”、将“运算符”列设置为“>=”，将“值”列设置为“@StartOfMonth - 3”，则可查找过去 3 个月中创建的所有项。
@Today
使用此变量可搜索与当前日期或更早日期相关的工作项。 还可以通过减去天数来修改 @Today 变量。 例如，如果将“字段”列设置为“激活日期”、将“运算符”列设置为“>=”，将“值”列设置为“@Today - 7”，则可查找过去一周激活的所有项。
[Any]
使用此变量可搜索为特定字段定义的任何值的相关工作项。
@me 宏
@me 宏可替换运行查询的用户的 Windows 集成帐户名称。 下面的示例演示了如何使用宏和等效的静态语句。 该宏旨在与标识字段（如 Assigned To）一起使用。
WHERE  
   [System.AssignedTo] = @Me 
@today 宏
可以将 @today 宏与任何日期/时间字段一起使用。 此宏可替换运行查询的本地计算机上当前日期的午夜。 还可以使用整数偏移量为 @today 后 x 天和 @today 前 y 天分别指定 @today+x 或 @today-y。 使用 @today 宏的查询可能会返回不同的结果集，具体取决于运行该宏的时区。
以下示例假定今天为 2019/1/3。
WHERE  
   [System.CreatedDate] = @today
WHERE  
   [System.CreatedDate] = '01-03-2019'
WHERE  
   [System.CreatedDate] > @today-2
WHERE  
   [System.CreatedDate] > '01-01-2019'
@StartOfDay、@StartOfWeek、@StartOfMonth、@StartOfYear 宏
可以将 @StartOf... 宏与任何日期/时间字段一起使用。 此宏可替换运行查询的本地计算机上当天的午夜、周开始、月份开始或年初。
需要 Azure DevOps Server 2019 Update 1 或更高版本。
这些宏接受格式为 (+/-)nn(y|M|w|d|h|m) 的修饰符字符串。 与 @Today 宏类似，你可以指定正负整数偏移量。 如果省略时间单位限定符，则默认为函数的自然周期。 例如，@StartOfWeek("+1") 和 @StartOfWeek("+1w") 相同。 如果省略了正/负 (+/-) 号，则假定为正号。
此语法允许嵌套修饰符并偏移查询两次。 例如，子句 Closed Date >= @StartOfYear - 1 可筛选自去年以来关闭的工作项。 通过将其修改为 Closed Date >= @StartOfYear('+3M') - 1，它将排除去年头三个月内关闭的工作项。 WIQL 语法如以下示例所示。
WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1
以下示例假定今天为 2019/4/5。
WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3
WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2019'
WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear
WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2019'
WIQL 还支持任意自定义宏。 任何以 @ 为前缀的字符串都会被视为自定义宏并被替换。 自定义宏的替换值是从对象模型中查询方法的上下文参数检索的。 以下方法是用于宏的 API：
public WorkItemCollection Query(string wiql, IDictionary context)
上下文参数包含宏的键值对。 例如，如果上下文包含一个键值对 (project, MyProject)，则 @project 就会在 WIQL 中被替换为 MyProject。 此替换是工作项查询生成器在 Visual Studio 中处理 @project 宏的方式。
指定历史查询 (ASOF)
可以在查询中使用 ASOF 子句来筛选满足特定日期和时间所定义的指定筛选器条件的工作项。
你无法在 Visual Studio 中的查询生成器中创建 ASOF 查询。 如果创建包含 ASOF 子句的查询文件 (.wiq)，然后在 Visual Studio 中加载此文件，则会忽略 ASOF 子句。
假设工作项在 2022 年 5 月 5 日之前被分类到迭代路径 Fabrikam Fiber\Release 1 下，并分配给“Jamal Hartnett”。 但是，工作项最近已分配给了“Raisa Pokrovskaya”，并移动到发布 2 的一个新迭代路径。 下面的示例查询会返回分配给 Jamal Hartnett 的工作项目，因为该查询是基于过去某个日期和时间的工作项目状态。
SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <[email protected]>') 
    ASOF  '01-05-2022 00:00:00.0000000'
如果未指定时间，WIQL 将使用午夜。 如果未指定时区，WIQL 将使用本地客户端计算机的时区。
设置排序顺序 (ORDER BY)
可以使用 ORDER BY 子句按一个或多个字段对查询结果进行升序或降序排序。
数据层上 SQL Server 的排序首选项确定了默认排序顺序。 但是，可以使用 asc 或 desc 参数选择显式排序顺序。
以下示例先按“优先级”对工作项进行升序（默认）排序，然后按“创建日期”进行降序排序。DESC
SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
查询工作项之间的链接
若要返回工作项之间的链接，应指定 FROM WorkItemLinks。 WHERE 子句中的筛选器条件可应用于链接或应用于作为链接的源或目标的任何工作项。 例如，以下查询可返回产品积压工作项与其活动子项之间的链接。
SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
MODE (Recursive)
下表汇总了工作项查询与对工作项之间链接的查询之间的差异。
工作项之间的链接
Specify one or more of the following:

[Source].[FieldName] = Value

[Target].[FieldName] = Value

[System.Links.LinkType] = 'LinkName'
MODE (MustContain)：（默认）仅返回其中的源、目标和链接条件都满足的 WorkItemLinkInfo 记录。
MODE (MayContain)：即使链接的工作项不满足目标条件，也返回满足源和链接条件的所有工作项的 WorkItemLinkInfo 记录。
MODE (DoesNotContain)：仅当没有链接的工作项满足链接和目标条件时，才返回满足源的所有工作项的 WorkItemLinkInfo 记录。
MODE (Recursive)：用于树查询 ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward')。 链接类型必须为树拓扑和顺向。 以递归方式为目标返回满足源的所有工作项的 WorkItemLinkInfo 记录。  ORDER BY 和 ASOF 与树查询不兼容。
System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Related
System.LinkTypes.Dependency-Predecessor
System.LinkTypes.Dependency-Successor
Microsoft.VSTS.Common.Affects-Forward（CMMI 流程）
有关详细信息，请参阅链接类型参考。
树类型查询示例
以下查询可返回当前项目中定义的所有工作项类型。 查询编辑器中显示的查询如下图所示。
等效的 WIQL 语法如下所示。
SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
MODE (Recursive)
直接链接查询示例
以下查询可返回当前项目中定义的所有工作项类型。 查询编辑器中显示的查询如下图所示。
等效的 WIQL 语法如下所示。
SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
ORDER BY [System.Id]
MODE (MustContain)
更多查询示例
以下典型的 WIQL 查询示例为字段使用引用名称。 查询选择“优先级”为 1 的工作项（未指定工作项类型）。 查询以列的形式返回返回集的“ID”和“标题”。 按 ID 对结果进行升序排序。
SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]
日期/时间模式
根据以下两种模式之一指定日期/时间模式：
日期模式和时间模式格式来自用户首选项、时间和区域设置
UTC 指定的模式，遵循此模式（Z 追加在日期/时间的后面）。
AND [System.ChangedDate] >= '1/1/2019 00:00:00Z'
以下示例语句显示了特定的限定子句。
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <[email protected]>' )
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <[email protected]>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <[email protected]>'
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <[email protected]>'
AND [System.AreaPath] UNDER 'Agile1\Area 0'
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
ORDER BY [System.Id] [asc | desc]
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jamal Hartnett <[email protected]>' 
ASOF '3/16/19 12:30'
字符串和纯文本
引号字符串文本（单引号或双引号）与字符串或纯文本字段进行比较。 字符串文本支持所有 Unicode 字符。
WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'
可以使用 contains 运算符在字段值中的任何位置搜索子字符串。
WHERE [System.Description] contains 'WIQL' 
区域和迭代 (TreePath)
可以将 UNDER 运算符用于“区域”和“迭代路径”字段。 UNDER 运算符评估值是否位于特定分类节点的子树内。 例如，如果区域路径为“MyProject\Server\Administration”、“MyProject\Server\Administration\Feature 1”、“MyProject\Server\Administration\Feature 2\SubFeature 5”或子树中的任何其他节点，则下面的表达式的计算结果将为 true。
WHERE [System.AreaPath] UNDER 'MyProject\Server\Administration'
修饰符和特殊运算符
可以在查询表达式中使用一些修饰符和特殊运算符。
使用 IN 运算符来评估字段值是否等于一组值中的任何一个。 字符串、整数、双精度和日期/时间字段类型支持此运算符。 请参阅以下示例及其语义等效项。
WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <[email protected]>', 'Raisa Pokrovskaya <[email protected]>', 'Christie Church <[email protected]>')
WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <[email protected]>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <[email protected]>'
        OR [System.CreatedBy] = 'Christie Church <[email protected]>'
EVER 运算符用于评估字段值是否等于或曾经等于工作项的所有过去修订中的特定值。 字符串、整数、双精度和日期/时间字段类型支持此运算符。 EVER 运算符有备用语法。 例如，下面的代码片段将查询所有工作项是否曾经分配给 Jamal、Raise 或 Christie。
WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <[email protected]>'
        OR EVER [System.AssignedTo] = 'Christie Church <[email protected]>'
查询字段、运算符、值和变量
工作项字段和属性
关于托管查询