Rechercher des bogues, des tâches et d'autres éléments de travail

Vous pouvez rechercher les bogues, les tâches, d'autres types d'éléments de travail, et des liens entre des éléments de travail à l'aide de l'une des méthodes d' WorkItemStore.Query ou un objet d' Query .Ces requêtes utilisent le langage d'interrogation de requête d'élément de travail (WIQL), qui ressemble à Transact-SQL.

TfsTeamProjectCollection tpc = new TfsTeamProjectCollection(
      new Uri("https://server:8080/tfs/DefaultCollection"));
WorkItemStore workItemStore = (WorkItemStore)tpc.GetService(typeof(WorkItemStore)); 
WorkItemCollection queryResults = workItemStore.Query("
   Select [State], [Title] 
   From WorkItems
   Where [Work Item Type] = 'User Story'
   Order By [State] Asc, [Changed Date] Desc");

Dim collectionUri As Uri
collectionUri = New Uri("https://Server:8080/tfs/DefaultCollection")
Dim tpc As New TfsTeamProjectCollection(collectionUri)
Dim workItemStore As WorkItemStore
workItemStore = tpc.GetService(Of WorkItemStore)()
Dim queryResults As WorkItemCollection
queryResults = workItemStore.Query(“
  Select [State], [Title]
  From WorkItems
  Where [Work Item Type] = ‘User Story’
  Order By [State] Asc, [Changed Date] Desc”)

Dans cette rubrique

• Langage de requête

• La clause where

  • Opérateurs de comparaison

  • Variables

  • Valeurs littérales

• Méthodes de requête et l'objet de requête

• Requêtes asynchrones

• Pagination des valeurs de champ

Autorisations requises

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

Conseil
Pour explorer les détails du langage d'interrogation de requête d'élément de travail, créez des requêtes à l'aide de Team Explorer, puis enregistrez -les comme fichiers de .wiql.Renommez les fichiers pour utiliser l'extension .xml, et les ouvrir dans Visual Studio.Recherchez l'élément d' wiql pour voir comment chaque requête est exprimée en langage d'interrogation de requête d'élément de travail.

Langage de requête

Le langage d'interrogation de requête d'élément de travail possède cinq parties.

          Select [State], [Title] 
From WorkItems
Where [Work Item Type] = 'User Story'
Order By [State] Asc, [Changed Date] Desc
AsOf '6/15/2010'

Select [State], [Title]	Identifie chaque Field dont la valeur est définie dans chaque WorkItem retournée par la requête.Vous pouvez spécifier le nom complet ou le nom de référence du champ.Vous devez utiliser des crochets ([]) si le nom contient des espaces ou des heures. Attention Vous pouvez utiliser WorkItem qui a été retourné par une requête pour obtenir la valeur d' Field, même si la requête n'a pas retourné la valeur.Si vous procédez ainsi, une autre boucle au serveur se produit.Pour plus d’informations, consultez Pagination des valeurs de champ.
From WorkItems	Indique si vous souhaitez que la requête pour rechercher des éléments de travail ou des liens entre des éléments de travail. From WorkItems Utilisation des éléments de travail. From WorkItemLinks Utilisation des liens entre des éléments de travail.Pour plus d’informations, consultez Requêtes pour les liens entre les éléments de travail.
Where [Work Item Type] = 'User Story'	Spécifie les critères de filtre de la requête.Pour plus d'informations, consultez La clause where plus loin dans cette rubrique.
Order By [State] Asc, [Changed Date] Desc	(Facultatif) spécifie comment trier WorkItemCollection que la requête retourne.
AsOf '6/15/2010'	(Facultatif) spécifie une requête historique en indiquant une date ou une heure auxquelles le filtre doit s'appliquer.Par exemple, cette requête retourne tous les récits utilisateur qui ont existé le 15 juin 2010. Remarque Vous ne pouvez pas créer de requêtes d'AsOf dans le concepteur de requêtes dans Visual Studio.Si vous créez un fichier de requête (.wiq) qui inclut une clause d'AsOf, puis charge que dans Visual Studio, la clause d'AsOf sera ignorée.

La clause where

Lorsque la clause spécifie les critères de filtre d'une requête pour des éléments de travail.La requête retourne uniquement les éléments de travail qui répondent à ces conditions.La requête d'exemple suivant retourne les récits utilisateur qui sont actifs qui vous sont assigné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 si vous utilisez des parenthèses pour regrouper des critères de recherche.Par exemple, pour retourner les éléments de travail ou qui vous sont assignés ou que vous fermé, modifiez le filtre de requête pour qu'elle corresponde à l'exemple suivant :

Where [Work Item Type] = 'User Story'
AND [State] = ‘Active’
AND ( [Assigned to] = @Me
OR [Closed by] = @Me )

Le tableau suivant décrit la syntaxe de la clause where :

	Syntaxe	Exemple
Où clause	Where FilterCondition [Group|{LogicalOperator FilterCondition}]
Groupe	(FilterCondition LogicalOperator FilterCondition [LogicalOperator Filter Condition]…)	([Assigned to] = @Me OR [Created by = @Me]) Les opérateurs logiques de regroupement sont AND et OR.
FilterCondition	Field ComparisonOperator Value	[Work Item Type] = ‘Help Topic’ Vous pouvez spécifier le nom de référence ou le nom complet d'un champ.Si le nom contient des espaces ou des heures, vous devez le placer entre crochets ([]). Les opérateurs de comparaison sont décrits dans Opérateurs de comparaison plus loin dans cette rubrique. Pour la valeur, vous pouvez spécifier une valeur littérale (" récit utilisateur ") ou une macro (@Me).
Valeur	LiteralValue|Variable|Field	'User Story' Valeur littérale La valeur réelle à comparer à la valeur du champ.Pour plus d'informations, consultez Valeurs littérales plus loin dans cette rubrique. Variable Une expression qui indique une valeur.Par exemple, @Me indique la personne qui exécute la requête.Pour plus d'informations, consultez Variables plus loin dans cette rubrique. Champ Le 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.

Opérateurs de comparaison

Vous pouvez utiliser des opérateurs dans le tableau suivant pour spécifier comment un champ doit associer à la valeur correspondante :

Opérateur de requête	Description	Types applicables de champs
=	Correspond à la valeur.	Nombre, texte, date, arborescence
<>	Ne correspond pas à la valeur.	Nombre, texte, date, arborescence
>	Est supérieure à la valeur.	Nombre, texte, date
<	Est inférieure à la valeur.	Nombre, texte, date
>=	Est supérieure ou égale à la valeur.	Nombre, texte, date
<=	Est inférieure ou égale à la valeur.	Nombre, texte, date
Contient	Contient la chaîne.	du texte ;
Ne contient pas	Ne contient pas la chaîne.	du texte ;
Dans	Correspond à n'importe quelle valeur dans un jeu délimité par des virgules.Par exemple, [System.Id] In (100, 101, 102) recherche des éléments de travail dont les ID sont 100, 101, et 102.	Nombre, texte, date, arborescence
Dans le groupe	Est membre du groupe.Le groupe peut être un groupe d' Team Foundation ([Assigned to] In Group [Project]\Contributors) ou une catégorie d'élément de travail lorsque vous utilisez au champ de type d'élément de travail ([Work Item Type] In Group Requirements).Pour plus d'informations sur les groupes de catégorie, consultez Définir des catégories pour regrouper des types d'éléments de travail.	du texte ;
Pas dans le groupe	N'est pas membre du groupe.Pour plus d'informations, consultez l'entrée de In Group.	du texte ;
Toujours	Correspondances si le champ appariait jamais la valeur, même si elle a été modifiée à une valeur différente.	Texte, date
Sous	Pour les zones et itérations, correspondances si l'élément de travail dans ce nœud ou à l'un de ses nœuds enfants.Pour plus d'informations sur les zones et itérations, consultez Créer et modifier des zones et des itérations.	Arborescence
Pas sous	Pour les zones et itérations, correspondances si l'élément de travail n'est pas dans ce nœud ou des aucuns de ses nœuds enfants.	Arborescence

Variables

Vous pouvez utiliser des variables dans vos requêtes pour passer les entrées d'utilisateur ou des valeurs calculées.Pour créer une requête qui inclut des variables, créez des espaces réservés dans la chaîne de requête à l'aide de @variable.Passez le nom et la valeur de chaque variable à la méthode de requête en utilisant une implémentation d' IDictionary, comme le montre l'exemple suivant

// Define a query that uses a variable for the type of work item. 
string queryString = "Select [State], [Title] From WorkItems Where [Work Item Type] = @Type";

// Set up a dictionary to pass "User Story" as the value of the type variable.
Dictionary<string, string> variables = new Dictionary<string, string>();
variables.Add("Type", "User Story");

// Create and run the query.
Query query = new Query(workItemStore, queryString, variables); 
WorkItemCollection results = query.RunQuery();

// Define a query that uses a variable for the type of work item.
Dim queryString As New StringBuilder("SELECT [State], [Title] FROM WorkItems WHERE [WorkItemtype] = @Type")

// Set up a dictionary to pass "User Story" as the value of a type variable.
Dim variables = New Dictionary(Of String, String)
variables.Add("Type", "User Story")

// Create and run the query.
Dim query As New Query(workItemStore, queryString, variables)                   
WorkItemCollection results = query.RunQuery()

Vous pouvez également utiliser @Me ou @Today dans votre requête sans fournir des valeurs de ces variables.Lorsque ces variables s'affichent dans la requête mais n'ont aucune valeur associée passée dans l'implémentation d' IDictionary , les variables sont évaluées comme décrit dans le tableau suivant :

Variable	Utilisation
@Me	Indique l'utilisateur actuel dans un domaine qui contient les noms d'utilisateurs.Par exemple, vous pouvez rechercher les éléments de travail que vous avez activés si vous spécifiez [Activated by] =@Me.
@Today	Indique la date du jour.Vous pouvez également modifier la variable d' @Today en ajoutant ou en soustrayant des jours.Par exemple, vous pouvez rechercher tous les éléments qui ont été activés dans la dernière semaine si vous spécifiez [Activated Date] > @Today - 7.

Valeurs littérales

Lorsque vous spécifiez une valeur pour chaque champ, la valeur doit correspondre au type de données de ce champ.Tous les champs d' Team Foundation ont un des types de données répertoriés dans le tableau suivant :

Type de données	Données stockées
DateTime	Une valeur d' datetime définie par SQL Server.Par défaut, les valeurs datetime dans les requêtes d'éléments de travail sont traitées comme ayant la précision de date.Par exemple, un élément de travail créé à tout moment du jour le 1er juin 2010, [Created Date] = 6/1/2010correspondrait les critères de filtre. Pour plus d'informations, consultez Méthodes de requête et l'objet de requête plus loin dans cette rubrique et la page suivante sur le site Web Microsoft : datetime (Transact-SQL).
Double	Nombre réel, tel que 0,2 ou 3,5.
GUID	Une chaîne de caractères qui représente un GUID.
HTML	Chaînes de texte qui contiennent le code HTML.
Entier	Entier 32 bits signé, tel que 0, 1, 2 ou 34.
PlainText	Une chaîne de texte non mis en forme qui peut être supérieure à 255 caractères.
Chaîne	Une chaîne de texte qui contient jusqu'à 255 caractères.
TreePath	Une arborescence de branche, telle qu'une zone ou itération.

Requêtes pour les liens entre les éléments de travail

Vous pouvez également utiliser des requêtes pour rechercher des liens entre des éléments de travail.Une condition dans laquelle la clause peut s'appliquer aux liens ou à tout élément de travail qui est la source ou la cible du lien.Le tableau suivant résume les différences entre ces types de requêtes et requêtes uniquement pour les éléments de travail :

	Éléments de travail	Liens entre éléments de travail
De la clause	WorkItems	De WorkItemLinks
Où clause	[FieldName] = Value	Une des valeurs suivantes : [Source].[FieldName] = Value [Target].[FieldName] = Value [System.Links.LinkType] = 'LinkName'
Mode		Une des valeurs suivantes : mode(MustContain) (Valeur par défaut) retourne uniquement les enregistrements d' WorkItemLinkInfo où tous la source, la cible, et de lien sont les critères de contenu. mode(MayContain) Retourne WorkItemLinkInfo stocke pour tous les éléments de travail qui répondent aux critères de source et de lien, même si aucun élément de travail lié ne répond aux critères cibles. mode(DoesNotContain) Retourne WorkItemLinkInfo stocke pour tous les éléments de travail qui satisfont la source, uniquement si aucun élément de travail lié ne répond aux critères de liaison et de cible.
Returns (Retours)	[ T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemCollection ]	Tableau de WorkItemLinkInfo.

La requête suivante retourne les liens entre des récits utilisateur et leurs nœuds enfants actifs.

SELECT [System.Id]
FROM WorkItemLinks
WHERE ([Source].[System.WorkItemType] = 'User Story')
  And ([System.Links.LinkType] = 'Child')
  And ([Target].[System.State] = 'Active')
mode(MustContain)

Méthodes de requête et l'objet de requête

Vous pouvez rechercher les éléments de travail à l'aide de la méthode d' WorkItemStore.Query .Vous pouvez également identifier le nombre d'éléments de travail qui satisfont une requête sans retourner tous les éléments de travail à l'aide de la méthode d' WorkItemStore.QueryCount .

Vous pouvez créer un objet d' Query pour définir et exécuter des requêtes.

string queryString = "Select [Title] From WorkItems Where [Work Item Type] = 'User Story'"
Query query = new Query(workItemStore, queryString); 
int numWorkItems = query.RunCountQuery();
Console.WriteLine("The project collection has " + numWorkItems.ToString() + " user stories.");

Dim queryString As New StringBuilder("Select [Title] FROM WorkItems WHERE [WorkItemType] = 'User Story'"
Dim query As New Query(workItemStore, queryString)
Dim numWorkItems As Int
numWorkItems = query.RunCountQuery()
Console.Writeline("The project collection has " + numWorkItems.ToString() + " user stories.")

Requêtes asynchrones

Vous pouvez exécuter des requêtes de façon asynchrone à l'aide de la méthode d' Query.BeginQuery .L'exemple suivant exécute une requête de façon asynchrone et annule la requête après un délai d'attente très court.

// Run the query asynchronously, and time out after 0.05 seconds. 
ICancelableAsyncResult callback = query.BeginQuery();
callback.AsyncWaitHandle.WaitOne(50, false); 
if (!callback.IsCompleted) 
{
   callback.Cancel();
   Console.WriteLine("The query timed out");
}
else
{
   WorkItemCollection nextResults = query.EndQuery(callback); 
   Console.WriteLine("The project collection has " + nextResults.Count.ToString() + " work items."); 
}

Dim callback as ICancelableAsyncResult
callback = query.RunQuery()
callback.AsyncAWaitHandle.WaitOne(50, False)
If Not (callback.IsCompleted)
Then
callback.Cancel()
Console.Writeline("The query timed out")
Else
Dim nextResults As WorkItemCollection = query.EndQuery(callback)
Console.Writeline("The project collection has " + nextResults.Count.ToString() + " work items.") 
End If

Pagination des valeurs de champ

WorkItemCollection qu'une requête retourne contient des valeurs pour les champs suivants :

• ID

• Rev (balisage)

• AreaID

• IterationID

• TypeÉlémentTravail

Les valeurs des champs que vous spécifiez dans la clause SELECT sont retournées dans les pages.

[!REMARQUE]

Par défaut, chaque page contient des champs sélectionnés de 50 éléments de travail.Vous pouvez ajuster la taille d'une page à l'aide de WorkItemCollection.PageSize.

Vous pouvez réduire les accès répétés au serveur en sélectionnant tous les champs que votre code utilise.Le code suivant fait une boucle pour la requête et une boucle pour retourner une page des titres chaque fois qu'une page est accessible.

WorkItemCollection results = WorkItemStore.Query(
   "SELECT Title FROM Workitems WHERE (ID < 1000)"); 
foreach (WorkItem item in results) 
{
   Console.WriteLine(item.Fields["Title"].Value);
}

Si votre code accède à un champ que vous n'avez pas spécifié dans la clause SELECT, ce champ est ajouté à l'ensemble de champs paginés.Une autre boucle est exécutée pour actualiser cette page pour inclure les valeurs de ce champ.

Syntaxe de requête (EBNF)

La forme backus-naur (EBNF) étendu est le métalangage qui décrit la syntaxe des langages de manière compacte et non équivoque.Ce bloc de code utilise EBNF pour décrire la syntaxe du langage d'interrogation de requête d'élément de travail (WIQL).

Si vous n'êtes pas familiarisé avec EBNF, consultez l'autre description de WIQL dans Syntax for the Work Item Query Language.

<select> ::= <flat-select> | <one-hop-select> | <recursive-select>

<flat-select> ::= select <field list>
from workitems
[ where <expression> ]
[ order by <order by field list> ]
[ asof <datetime> ]

<one-hop-select> ::= select <field list>
from workitemlinks
[ where <one-hop-link-expression>  <source-expression>  <target-expression> ]
[ order by <source-target order by field list> ]
[ asof <datetime> ]
mode( mustcontain | maycontain | doesnotcontain )

<recursive-select> ::= select <field list>
from workitemlinks
where <recursive-link-expression> [ and <source-expression> <target-expression> ]
mode ( recursive | returnmatchingchildren )

<expression> ::= <expression4>

<expression4> ::= <expression3> [ or <expression4> ]
<expression3> ::= <expression2> [ and <expression3> ]

<expression2> ::=   {[ not | ever ] <expression2> }
                          | <expression1>

<expression1> ::= <conditional expression>

<conditional expression> ::=   { '(' <expression> ')' }  | <field reference name> <conditional operator> <value>  | <field reference name> [not] in '(' <value list> ')'

<value> ::= <number>
| <string>
| <datetime>

<value list> ::= <value> [ ',' <value list> ]

<conditional operator> ::=   { '=' | '<>' | '<' | '<=' | '>' | '>=' } 
                             | { [ever] [not] { like | under }} 
<link operator> ::= '=' | '<>'

<field list> ::= <field name> [ ',' <field list> ]
<order by field list> ::= <order by field> [ ',' <order by field list> ]
<source-target order by field list> ::= [ <source> |<target> ] <order by field> [ ',' <source-target order by field list> ]
<order by field> ::= <field name> [ 'asc' | 'desc' ]

<number> ::= [ '-' ] <digit>* [ '.' [ <digit>* ]] [ { e | E } [ '-' ] <digit>* ]

<string> ::=   { ''' { <anychar except '''> | '''' }* ''' } 
                 | { '"' { <anychar except '"'> | '""' }* '"' }

<datetime> ::= <string>

<source> ::= '[source].'
<target> ::= '[target].'

<one-hop-link-expression> ::= <one-hop-link-expression4> | ''

<one-hop-link-expression4> ::= <one-hop-link-expression3> [ or <one-hop-link-expression4> ]
<one-hop-link-expression3> ::= <one-hop-link-expression2> [ and <one-hop-link-expression3> ]

<one-hop-link-expression2> ::= {[ not | ever ] <one-hop-link-expression2>}
                         | <one-hop-link-expression1>

<one-hop-link-expression1> ::= <conditional-link-expression>

<conditional-link-expression> ::= { '(' <one-hop-link-expression> ')' } | <linktype-field> <link operator> <linktype-name><linktype-direction> | <linktype-field> [not] 'in  (' <linktype list> ')'

<recursive-link-expression> ::= <linktype-field> '=' <linktype-name>'-forward'

<linktype list> ::= <linktype-name><linktype-direction> [, <linktype-name><linktype-direction>]

<linktype-direction> ::= '-forward' | '-reverse'

<source-expression> ::= <source-expression4> | ''

<source-expression4> ::= <source-expression3> [ or <source-expression4> ]
<source-expression3> ::= <source-expression2> [ and <source-expression3> ]

<source-expression2> ::=   {[ not | ever ] <source-expression2> }
                          | <source-expression1>

<source-expression1> ::= <conditional-source-expression>

<conditional-source-expression> ::=   { '(' <source-expression> ')' }  | <source><field reference name> <conditional operator> <value>  | <source><field reference name> [not] in '(' <value list> ')'

<target-expression> ::= <target-expression4> | ''

<target-expression4> ::= <target-expression3> [ or <target-expression4> ]
<target-expression3> ::= <target-expression2> [ and <target-expression3> ]

<target-expression2> ::=   {[ not | ever ] <target-expression2> }
                          | <target-expression1>

<target-expression1> ::= <conditional-target-expression>

<conditional-target-expression> ::=   { '(' <target-expression> ')' }  | <target><field reference name> <conditional operator> <value>  | <target><field reference name> [not] in '(' <value list> ')'

<linktype-field> ::= '[System.Links.LinkType] = '
<select> ::= select <field list>
from workitems
[ where <expression> ]
[ order by <order by field list> ]
[ asof <datetime> ]

<expression> ::= <expression4>

<expression4> ::= <expression3> [ or <expression4> ]
<expression3> ::= <expression2> [ and <expression3> ]

<expression2> ::=   {[ not | ever ] <expression2> }
                          | <expression1>

<expression1> ::= <conditional expression>

<conditional expression> ::=   { '(' <expression> ')' }  | <field reference name> <conditional operator> <value>  | <field reference name> [not] in '(' <value list> ')'

<value> ::= <number>
| <string>
| <datetime>

<value list> ::= <value> [ ',' <value list> ]

<conditional operator> ::=   { '=' | '<>' | '<' | '<=' | '>' | '>=' } 
                             | { [ever] [not] { like | under }} 

<field list> ::= <field name> [ ',' <field list> ]
<order by field list> ::= <field name> [ asc | desc ] [ ',' <order by field list> ]

<number> ::= [ '-' ] <digit>* [ '.' [ <digit>* ]] [ { e | E } [ '-' ] <digit>* ]

<string> ::=   { ''' { <anychar except '''> | '''' }* ''' } 
                 | { '"' { <anychar except '"'> | '""' }* '"' }

<datetime> ::= <string> Insert section body here.

Voir aussi

Concepts

Extension du suivi des éléments de travail à l'aide du Modèle d'objet client pour Team Foundation