Référence syntaxique du langage WIQL

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

Vous pouvez utiliser la syntaxe WIQL pour définir une requête en tant que lien hypertexte ou lors de l’utilisation de l’API REST Work Item Query Language.

La syntaxe WIQL prend en charge toutes les fonctions disponibles via l’Éditeur de requête du portail web, plus quelques autres. Vous pouvez spécifier les champs à retourner et spécifier le regroupement logique des clauses de requête. En outre, vous pouvez utiliser une clause ASOF pour filtrer en fonction des affectations sur la base d’une date précédente.

Prérequis

Une requête retourne uniquement les éléments de travail pour lesquels vous avez l’autorisation Afficher les éléments de travail ou l’autorisation Afficher les éléments de travail dans ce nœud. En général, ces autorisations sont accordées aux membres des groupes Readers et aux groupes Contributors de chaque projet d’équipe. Pour plus d’informations, consultez Autorisations et groupes.

Vue d’ensemble du langage de requête

Le langage de requête d’élément de travail comporte cinq parties indiquées dans l’extrait de code de syntaxe suivant et décrites dans le tableau suivant. La syntaxe WIQL ne respecte pas la casse.

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'

Modèle de date et d’heure

Le modèle de date et d’heure que vous entrez pour les champs DateTime doit correspondre à celui que vous sélectionnez dans votre profil. Pour afficher ou modifier votre sélection, consultez Définir les préférences utilisateur.

Placez entre guillemets (guillemets simples ou doubles pris en charge) les littéraux DateTime utilisés dans les comparaisons. Ils doivent être au format .NET DateTime de l’ordinateur client local exécutant la requête. Sauf si un fuseau horaire est spécifié, les littéraux DateTime se trouvent dans le fuseau horaire de l’ordinateur local.

WHERE 
   AND [System.ChangedDate] >= '01-18-2019 GMT'
   AND ([Closed Date] < '01-09-2022 GMT'
   OR [Resolved Date] >= '01-18-2019 14:30:01')  

Lorsque l’heure est omise dans un littéral DateTime et que le paramètre dayPrecision est égal à false, l’heure est supposée être égale à zéro (minuit). Le paramètre par défaut pour le paramètre dayPrecision est false.

Vous pouvez également spécifier le format ISO 8601, qui est valide quels que soient les paramètres régionaux. ISO 8601 représente la date et l’heure en commençant par l’année, suivie du mois, du jour, de l’heure, des minutes, des secondes et des millisecondes. Par exemple, 2021-12-10 15:00:00.000, représente le 10 décembre 2021 à 15h00 en heure locale. Voici un exemple d’utilisation du format 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')  

Champs personnalisés

Spécifier des clauses de filtre (WHERE)

La clause WHERE spécifie les critères de filtre. La requête retourne uniquement les éléments de travail qui répondent aux critères spécifiés. Par exemple, l’exemple de clause WHERE suivant retourne des récits utilisateur actifs et qui vous sont affectés.

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

Vous pouvez contrôler l’ordre dans lequel les opérateurs logiques sont évalués en les plaçant entre parenthèses pour regrouper les critères de filtre. Par exemple, pour retourner des éléments de travail qui vous sont assignés ou que vous avez fermé, modifiez le filtre de requête pour qu’il corresponde à l’exemple suivant.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

Conditions de filtre

Chaque condition de filtre est composée de trois parties, chacune devant être conforme aux règles suivantes :

• Champ : vous pouvez spécifier le nom de référence ou le nom convivial. Les exemples suivants sont une syntaxe WIQL valide :
  • Nom de la référence : SELECT [System.AssignedTo] ...
  • Nom convivial avec des espaces : SELECT [Assigned To] ...
  • Les noms sans espaces ne nécessitent pas de crochets : SELECT ID, Title ...
• Opérateur : des valeurs valides sont spécifiées dans la section Opérateurs, plus loin dans cet article.
• Valeur du champ : vous pouvez spécifier l’une des trois valeurs suivantes en fonction du champ spécifié.
  • Une valeur littérale doit correspondre au type de données de la valeur de champ.
  • Une *variable ou macro qui indique une certaine valeur. Par exemple, @Me indique la personne qui exécute la requête. Pour plus d’informations, consultez Macros et variables plus loin dans cet article.
  • Nom d’un autre champ. Par exemple, vous pouvez utiliser [Assigned to] = [Changed by] pour rechercher des éléments de travail assignés à la personne qui a modifié l’élément de travail en dernier.

Pour obtenir une description et les noms de référence de tous les champs définis par le système, consultez Index des champs d’élément de travail.

Opérateurs

Les requêtes utilisent des expressions logiques pour qualifier les jeux de résultats. Ces expressions logiques sont formées par une ou plusieurs opérations jointes.

Certaines opérations de requête simples sont répertoriées ci-dessous.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

Le tableau ci-dessous récapitule tous les opérateurs pris en charge pour différents types de champs. Pour plus d’informations sur chaque type de champ, consultez Champs et attributs d’élément de travail.

Les opérateurs =, <>, >, <, >=, and <= fonctionnent comme prévu. Par exemple, System.ID > 100 interroge tous les éléments de travail avec un ID supérieur à 100. System.ChangedDate > '01-01-19 12:00:00' interroge tous les éléments de travail qui ont changé après midi le 1er janvier 2019.

Au-delà de ces opérateurs de base, il existe certains comportements et opérateurs spécifiques à certains types de champs.

Regroupements logiques

Vous pouvez utiliser les termes AND et OR dans le sens booléen classique pour évaluer deux clauses. Vous pouvez utiliser les termes AND EVER et OR EVER lors de la spécification d’un opérateur WAS EVER. Vous pouvez regrouper des expressions logiques et les regrouper en fonction des besoins. Des exemples sont présentés ci-dessous.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

Vous pouvez inverser les opérateurs contains, under, et in à l’aide de not. Vous ne pouvez pas inverser l’opérateur ever. L’exemple ci-dessous interroge tous les éléments de travail qui ne sont pas affectés sous la sous-arborescence de Fabrikam Fiber\Account Management.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

Exemple de requête, Was Ever Assigned To

L’exemple d’Éditeur de requête suivant recherche tous les éléments de travail qui ont été attribués à Jamal Hartnett.

Et voici la syntaxe WIQL correspondante.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

Macros ou variables

Le tableau suivant répertorie les macros ou variables que vous pouvez utiliser dans une requête WIQL.

Macro @me

La macro @me remplace le nom du compte intégré Windows de l’utilisateur qui exécute la requête. L’exemple ci-dessous montre comment utiliser la macro et l’instruction statique équivalente. La macro est destinée à être utilisée avec des champs d’identité comme Assigned To.

WHERE  
   [System.AssignedTo] = @Me 

Macro @today

Vous pouvez utiliser la macro @today avec n’importe quel champ DateTime. Cette macro remplace minuit de la date actuelle sur l’ordinateur local qui exécute la requête. Vous pouvez également spécifier @today+x ou @today-y avec des décalages entiers pour x jours après @today et y jours avant @today, respectivement. Une requête qui utilise la macro @today peut retourner différents jeux de résultats en fonction du fuseau horaire dans lequel elle est exécutée.

Les exemples ci-dessous supposent que nous sommes le 3 janvier 2019.

WHERE  
   [System.CreatedDate] = @today

Équivaut à :

WHERE  
   [System.CreatedDate] = '01-03-2019'

And

WHERE  
   [System.CreatedDate] > @today-2

Équivaut à :

WHERE  
   [System.CreatedDate] > '01-01-2019'

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

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'

Macros personnalisées

WIQL prend également en charge les macros personnalisées arbitraires. Toute chaîne préfixée par un @ est traitée comme un macro personnalisé et est substituée. La valeur de remplacement de la macro personnalisée est récupérée à partir du paramètre de contexte de la méthode de requête dans le modèle d’objet. La méthode suivante est l’API utilisée pour les macros :

public WorkItemCollection Query(string wiql, IDictionary context)

Le paramètre de contexte contient des paires clé-valeur pour les macros. Par exemple, si le contexte contient une paire clé-valeur de (project, MyProject), alors @project est remplacé par MyProject dans le WIQL. Ce remplacement est la façon dont le générateur de requête d’élément de travail gère la macro @project dans Visual Studio.

Spécifier des requêtes historiques (ASOF)

Vous pouvez utiliser une clause ASOF dans une requête pour filtrer les éléments de travail qui répondent aux conditions de filtre spécifiées, car ils ont été définis à une date et une heure spécifiques.

Supposons qu’un élément de travail ait été classé sous un chemin d’itération de Fabrikam Fiber\Release 1 et affecté à ’Jamal Hartnett’ avant le 5/05/2022. Toutefois, l’élément de travail a récemment été attribué à « Raisa Pokrovskaya » et déplacé vers un nouveau chemin d’itération de Version 2. L’exemple de requête suivant retourne les éléments de travail assignés à Jamal Hartnett parce que la requête est basée sur l’état des éléments de travail à une date et heure passées.

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 <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2022 00:00:00.0000000'

Définir l’ordre de tri (ORDER BY)

Vous pouvez utiliser la clause ORDER BY pour trier les résultats d’une requête sur un ou plusieurs champs dans l’ordre croissant ou décroissant.

L’exemple suivant trie d’abord les éléments de travail par Priorité dans l’ordre croissant (par défaut), puis par Date de création dans l’ordre décroissant (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 <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

Interroger les liens entre éléments de travail

Pour retourner des liens entre éléments de travail, vous spécifiez FROM WorkItemLinks. Filtrez les conditions dans la clause WHERE peut s’appliquer aux liens ou à tout élément de travail étant la source ou la cible du lien. Par exemple, la requête suivante retourne les liens entre les éléments du backlog de produit et leurs éléments enfants actifs.

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)

Le tableau suivant récapitule les différences entre les requêtes d’élément de travail et les requêtes pour les liens entre les éléments de travail.

• System.LinkTypes.Hierarchy-Forward
• System.LinkTypes.Related
• System.LinkTypes.Dependency-Predecessor
• System.LinkTypes.Dependency-Successor
• Microsoft.VSTS.Common.Affects-Forward (processus CMMI)

Pour plus d’informations, consultez Référence sur le type de lien.

Exemple de requête de type Arborescence

La requête suivante retourne tous les types d’élément de travail définis dans le projet en cours. La requête indiquée dans l’Éditeur de requête s’affiche comme illustré dans l’image suivante.

La syntaxe WIQL équivalente est illustrée ci-dessous.

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)

Exemple de requête de lien direct

La requête suivante retourne tous les types d’élément de travail définis dans le projet en cours. La requête indiquée dans l’Éditeur de requête s’affiche comme illustré dans l’image suivante.

La syntaxe WIQL équivalente est comme indiqué.

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)

Autres exemples de requêtes

L’exemple de requête WIQL classique suivant utilise des noms de référence pour les champs. La requête sélectionne les éléments de travail (aucun type d’élément de travail spécifié) avec Priority=1. La requête retourne l’ID et le Titre du jeu de retour en tant que colonnes. Les résultats sont triés par ID dans l’ordre croissant.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

Modèle date/heure

Vous spécifiez le modèle date-heure selon l’un des deux modèles suivants :

• Le modèle de date et le format de modèle d’heure proviennent de vos Préférences utilisateur, Heure et paramètres régionaux
• Modèle spécifié par UTC, qui suit ce modèle (avec Z ajouté à la date-heure).

AND [System.ChangedDate] >= '1/1/2019 00:00:00Z'

Exemples de clauses

Les exemples d’instructions suivants montrent des clauses de qualification spécifiques.

SELECT [System.Id], [System.Title]
FROM WorkItems
WHERE [System.TeamProject] = @project
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>' )

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AreaPath] UNDER 'Agile1\Area 0'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [System.Id] [asc | desc]

SELECT [System.Title] 
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>' 
ASOF '3/16/19 12:30'

Chaîne et PlainText

Placez entre guillemets (les guillemets simples ou doubles sont pris en charge) les littéraux de chaîne dans une comparaison avec un champ de chaîne ou de texte brut. Les littéraux de chaîne prennent en charge tous les caractères Unicode.

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

Vous pouvez utiliser l’opérateur Contains pour rechercher une sous-chaîne n’importe où dans la valeur du champ.

WHERE [System.Description] contains 'WIQL' 

Zone et itération (TreePath)

Vous pouvez utiliser l’opérateur UNDER pour les champs Zone et Chemin d’itération. L’opérateur UNDER évalue si une valeur se trouve dans la sous-arborescence d’un nœud de classification spécifique. Par exemple, l’expression ci-dessous a la valeur true si le chemin de zone était « MyProject\Server\Administration », « MyProject\Server\Administration\Feature 1 », « MyProject\Server\Administration\Feature 2\SubFeature 5 » ou tout autre nœud dans la sous-arborescence.

WHERE [System.AreaPath] UNDER 'MyProject\Server\Administration'

Modificateurs et opérateurs spéciaux

Vous pouvez utiliser certains modificateurs et opérateurs spéciaux dans une expression de requête.

Utilisez l’opérateur IN pour évaluer si une valeur de champ est égale à l’une des valeurs d’un ensemble. Cet opérateur est pris en charge pour les types de champs Chaîne, Entier, Double et DateTime. Consultez l’exemple suivant avec son équivalent sémantique.

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

L’opérateur EVER permet d’évaluer si une valeur de champ est égale ou n’a jamais égalé une valeur particulière dans toutes les révisions antérieures des éléments de travail. Les types de champs Chaîne, Entier, Double et DateTime prennent en charge cet opérateur. Il existe d’autres syntaxes pour l’opérateur EVER. Par exemple, les extraits de code ci-dessous demandent si tous les éléments de travail ont été attribués à Jamal, Raise ou Christie à un moment donné.

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Articles connexes

• Champs de requête, opérateurs, valeurs et variables
• Champs et attributs d’élément de travail
• À propos des requêtes managées
• Définir une requête