Eseguire una query per trovare bug, attività e altri elementi di lavoro

Articolo
03/05/2013

È possibile eseguire una query per i bug, le attività, altri tipi di elementi di lavoro e collegamenti tra elementi di lavoro utilizzando uno dei metodi WorkItemStore.Query o di un oggetto Query.Queste query utilizzano il linguaggio (WIQL) di query elemento di lavoro, simile a 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”)

In questo argomento

Autorizzazioni necessarie

Una query restituirà solo gli elementi di lavoro per il quale si dispone di autorizzazioni Visualizza elementi di lavoro in questo nodo o Visualizza elementi di lavoro.In genere, queste autorizzazioni concesse ai membri dei gruppi Contributors e Readers per ogni progetto team.Per ulteriori informazioni, vedere Autorizzazioni per Team Foundation Server.

Suggerimento
Per visualizzare i dettagli del linguaggio di query elemento di lavoro, creare query tramite Team Explorerquindi salvarli come file di .wiql.Rinominare i file per utilizzare l'estensione xml e per aprirli in Visual Studio.Trovare l'elemento wiql per vedere come ogni query è espresso nel linguaggio di query elemento di lavoro.

Linguaggio di query

Il linguaggio di query elemento di lavoro sono disponibili cinque parti.

          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]	Identifica ogni Field il cui valore viene impostato in ogni WorkItem restituito dalla query.È possibile specificare il nome visualizzato o il nome di riferimento del campo.È necessario utilizzare le parentesi quadre ([]) se il nome contiene spazi vuoti o punti. Attenzione È possibile utilizzare WorkItem che è stato restituito da una query per ottenere il valore Field, anche se la query non ha restituito il valore.In questo caso, un altro round trip al server si verifichi.Per ulteriori informazioni, vedere Il paging dei valori di campo.
From WorkItems	Indica se si desidera che la query per trovare elementi di lavoro o collegamenti tra elementi di lavoro. From WorkItems Utilizzare per gli elementi di lavoro. From WorkItemLinks Utilizzo dei collegamenti tra elementi di lavoro.Per ulteriori informazioni, vedere Query di collegamenti tra elementi di lavoro.
Where [Work Item Type] = 'User Story'	Specifica i criteri di filtro della query.Per ulteriori informazioni, vedere La clausola where più avanti in questo argomento.
Order By [State] Asc, [Changed Date] Desc	(Facoltativo) specificare come ordinare WorkItemCollection restituite dalla query.
AsOf '6/15/2010'	(Facoltativo) specificare una query cronologico visualizzata una data o un'ora in cui il filtro deve essere applicato.Ad esempio, questa query restituisce tutte le storie utente esistenti il 15 giugno 2010. Nota Non è possibile creare query di AsOf del generatore di query in Visual Studio.Se si crea un file di query (con estensione wiq) che include una clausola di AsOf quindi caricate che in Visual Studio, la clausola di AsOf verrà ignorata.

La clausola where

La clausola specifica i criteri di filtro di una query elemento di lavoro.La query restituisce solo gli elementi di lavoro che soddisfano queste condizioni.La seguente query di esempio restituisce le storie utente attive e che sono state assegnate.

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

È possibile controllare l'ordine in cui gli operatori logici sono valutati se utilizzare le parentesi per raggruppare i criteri di ricerca.Ad esempio, restituire elementi di lavoro che sono assegnati o che chiuso, modificare il filtro della query in base all'esempio seguente:

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

Nella tabella seguente viene descritta la sintassi della clausola where:

	Sintassi	Esempio
La clausola where	Where FilterCondition [Group\|{LogicalOperator FilterCondition}]
Gruppo	(FilterCondition LogicalOperator FilterCondition [LogicalOperator Filter Condition]…)	([Assigned to] = @Me OR [Created by = @Me]) Gli operatori di raggruppamento logici sono AND e OR.
FilterCondition	Field ComparisonOperator Value	[Work Item Type] = ‘Help Topic’ È possibile specificare il nome di riferimento o il nome visualizzato di un campo.Se il nome contiene spazi o punti, deve essere racchiuso tra parentesi quadre ([]). Gli operatori di confronto vengono descritti più avanti in Operatori di confronto in questo argomento. Per il valore, è possibile specificare un valore letterale (" storia utente ") o una macro (@Me).
Valore	LiteralValue\|Variable\|Field	'User Story' Valore letterale Il valore effettivo da confrontare il valore del campo.Per ulteriori informazioni, vedere Valori letterali più avanti in questo argomento. Variabile Un'espressione che indica il valore.Ad esempio, il @Me indica la persona che esegue la query.Per ulteriori informazioni, vedere Variabili. più avanti in questo argomento. Campo Il nome di un altro campo.Ad esempio, è possibile utilizzare [Assigned to] = [Changed by]per trovare elementi di lavoro assegnati all'utente che ha modificato per ultimo l'elemento di lavoro.

Operatori di confronto

È possibile utilizzare gli operatori nella tabella seguente per specificare come campo deve essere correlato al valore corrispondente:

Operatore di query	Descrizione	Tipi di campi applicabili
=	Corrisponde al valore.	Numero, Testo, Data, Struttura ad albero
<>	Non corrisponde al valore.	Numero, Testo, Data, Struttura ad albero
>	È maggiore del valore.	Numero, Testo, Data
<	È minore del valore.	Numero, Testo, Data
>=	È maggiore o uguale al valore.	Numero, Testo, Data
<=	È minore o uguale al valore.	Numero, Testo, Data
Contiene	Contiene la stringa.	Testo
Non contiene	Non contiene la stringa.	Testo
In	Corrisponde a qualsiasi valore in un set delimitato da virgole.Ad esempio, [System.Id] In (100, 101, 102) cerca gli elementi di lavoro i cui ID sono 100, 101 e 102.	Numero, Testo, Data, Struttura ad albero
In Group	È un membro del gruppo.Il gruppo può essere un gruppo Team Foundation ([Assigned to] In Group [Project]\Contributors) o una categoria elemento di lavoro si utilizzano il campo tipo di elemento di lavoro ([Work Item Type] In Group Requirements).Per informazioni sui gruppi di categorie, vedere Definire categorie per raggruppare tipi di elementi di lavoro.	Testo
Non nel gruppo	Non è un membro del gruppo.Per ulteriori informazioni, vedere la voce relativa a In Group.	Testo
Era sempre	Trova la corrispondenza di se il campo corrisponda al valore, anche se è stato modificato un valore diverso.	Testo, Data
Incluso	Per aree e iterazioni, corrisponde a se l'elemento di lavoro si trova nel nodo o uno dei relativi nodi figlio.Per informazioni sulle aree e iterazioni, vedere Creare e modificare aree e iterazioni.	Struttura ad albero
Non incluso	Per aree e iterazioni, corrisponde a se l'elemento di lavoro non si trova nel nodo o uno dei relativi nodi figlio.	Struttura ad albero

Variabili.

È possibile utilizzare le variabili nelle query per il passaggio dell'input o valori calcolati.Per creare una query che include le variabili, creare i segnaposto nella stringa di query utilizzando @variable.Passare il nome e il valore di ciascuna variabile al metodo della query utilizzando un'implementazione IDictionary, come illustrato nell'esempio

// 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()

È inoltre possibile utilizzare @Me o @Today nella query senza fornire valori per le variabili.Quando queste variabili vengono visualizzati nella query ma non è collegato valore passato nell'implementazione IDictionary, le variabili vengono valutate durante la tabella seguente:

Variabile	Utilizzo
@Me	Indica all'utente corrente in un campo contenente i nomi utente.Ad esempio, è possibile trovare elementi di lavoro già attivato se si specifica [Activated by] =@Me.
@Today	Indica la data corrente.È inoltre possibile modificare la variabile @Today aggiungendo o sottraendo giorni.Ad esempio, trovare tutti gli elementi che sono stati attivati nell'ultima settimana se si specifica [Activated Date] > @Today - 7.

Valori letterali

Quando si specifica un valore per un campo, il valore deve corrispondere al tipo di dati del campo.Tutti i campi in Team Foundation dispongono di uno dei tipi di dati che sono elencati nella tabella seguente:

Tipo di dati	Dati archiviati
DateTime	Un valore datetime come definito da SQL Server.Per impostazione predefinita, i valori DateTime nelle query per gli elementi di lavoro vengono considerati come con precisione della data.Ad esempio, un elemento di lavoro creato in qualsiasi momento il giorno il 1° giugno 2010, corrisponderebbe i criteri di filtro [Created Date] = 6/1/2010. Per ulteriori informazioni, vedere più avanti Metodi di query e l'oggetto query in questo argomento e nella pagina seguente nel sito Web Microsoft: datetime (Transact-SQL).
Double	Un numero reale, quale 0,2 o 3,5.
GUID	Una stringa di caratteri che rappresenta un GUID.
HTML	Stringhe di testo che contengono l'html.
Integer	Un Integer a 32 bit con segno, ad esempio 0, 1, 2, o 34.
PlainText	Una stringa di testo non formattato che possono superare i 255 caratteri.
String	Una stringa di testo che contiene fino a 255 caratteri.
TreePath	Una struttura con diramazioni, come area o iterazione.

Query di collegamenti tra elementi di lavoro

È inoltre possibile utilizzare query per trovare i collegamenti tra elementi di lavoro.Una condizione in cui la clausola può essere applicato ai collegamenti o a qualsiasi elemento di lavoro che è l'origine o la destinazione di un collegamento.Nella tabella seguente vengono riepilogate le differenze tra questi tipi di query e query solo per gli elementi di lavoro:

	Elementi di lavoro	Collegamenti tra elementi di lavoro
Clausola FROM	Gli elementi di lavoro	Da WorkItemLinks
La clausola where	[FieldName] = Value	Uno dei seguenti: [Source].[FieldName] = Value [Target].[FieldName] = Value [System.Links.LinkType] = 'LinkName'
Modalità		Uno dei seguenti: mode(MustContain) (Impostazione predefinita) restituisce solo i record WorkItemLinkInfo in cui l'origine, arrivo e tutti i criteri di collegamento sono soddisfatti. mode(MayContain) Restituisce record WorkItemLinkInfo per tutti gli elementi di lavoro che soddisfano i criteri di collegamento e di origine, anche se nessun elemento di lavoro collegato soddisfa i criteri di destinazione. mode(DoesNotContain) Restituisce record WorkItemLinkInfo per tutti gli elementi di lavoro che soddisfano il database di origine, solo se nessun elemento di lavoro collegato soddisfa il collegamento e risolvere i criteri.
Valore restituito	[ T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemCollection ]	Matrice di istanze della classe WorkItemLinkInfo.

La seguente query restituisce i collegamenti tra storie utente e i relativi nodi figlio attivi.

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

Metodi di query e l'oggetto query

È possibile eseguire una query per gli elementi di lavoro tramite il metodo WorkItemStore.Query.È inoltre possibile identificare il numero di elementi di lavoro che soddisfano una query senza restituire tutti gli elementi di lavoro tramite il metodo WorkItemStore.QueryCount.

È possibile creare un oggetto Query per definire ed eseguire query.

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.")

Query asincroni

È possibile eseguire query in modo asincrono tramite il metodo Query.BeginQuery.Nell'esempio seguente viene eseguita una query in modo asincrono e annulla la query dopo un periodo di timeout molto breve.

// 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

Il paging dei valori di campo

WorkItemCollection restituito da una query contiene i valori per i campi seguenti:

ID
Rev (revisione)
AreaID
IterationID
WorkItemType

I valori dei campi specificati nella clausola SELECT vengono restituiti nelle pagine.

[!NOTA]

Per impostazione predefinita, ogni pagina contenente i campi selezionati per 50 elementi di lavoro.È possibile modificare la dimensione di una pagina utilizzando WorkItemCollection.PageSize.

È possibile ridurre al minimo i round trip al server selezionando tutti i campi che il codice verrà utilizzata.Il codice seguente effettua un round trip per la query e un round trip per restituire ogni volta che una pagina dei libri che una nuova pagina viene eseguito.

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

Se i il codice accede a un campo che non è stata specificata nella clausola SELECT, il campo verrà aggiunto al set di campi di paging.Un altro round trip viene eseguito per aggiornare la pagina per includere i valori del campo.

Sintassi di query (EBNF)

Il form esteso (EBNF) di Backus-Naur è metalinguaggio che descrive la sintassi dei linguaggi in una modalità compressa e inequivocabile.Questo blocco di codice utilizza EBNF per descrivere la sintassi del linguaggio (WIQL) di query elemento di lavoro.

Se non si ha familiarità con EBNF, vedere una descrizione alternativa di WIQL in 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.

Vedere anche

Concetti

Estensione della gestione degli elementi di lavoro tramite il modello a oggetti del client per Team Foundation

Condividi tramite