Consulta para, bugs, tarefas e outros itens de trabalho

Você pode consultar bugs, tarefas, outros tipos de itens de trabalho, e links entre itens de trabalho usando um dos métodos de WorkItemStore.Query ou de um objeto de Query .Essas consultas usam a linguagem de consulta (WIQL) de item de trabalho, que lembra o 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”)

Neste tópico

• Linguagem de consulta

• Cláusula where

  • Operadores de Comparação

  • As variáveis

  • valores literais

• Métodos de consulta e o objeto de consulta

• consultas assíncronos

• Valores de campo de paginação

Permissões Necessárias

Uma consulta retorna apenas estes itens de trabalho que você tem permissão de Exibir itens de trabalho ou de Exibir itens de trabalho em este nó .Normalmente, essas permissões são concedidas a membros de Leitores e grupos de Colaboradores para cada projeto de equipe.Para obter mais informações, consulte Team Foundation Permissões do servidor.

Dica
Para explorar os detalhes de linguagem de consulta de item de trabalho, crie consultas usando Team Explorer, e então salve as como arquivos de .wiql.Renomear arquivos para usar a extensão .xml, e para abri-las no Visual Studio.Procure o elemento de wiql para ver como cada consulta é expressa na linguagem de consulta de item de trabalho.

Linguagem de consulta

A linguagem de consulta de item de trabalho tem cinco partes.

          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 cada Field cujo valor será definido em cada WorkItem retornado pela consulta.Você pode especificar o nome para exibição ou o nome da referência do campo.Você deve usar os colchetes ([]) se o nome contém placas ou pontos. Cuidado você pode usar WorkItem que foi retornado por uma consulta para obter o valor de Field, mesmo se a consulta não retornou o valor.Se você fizer isso, outra processamento para o servidor ocorrerá.Para obter mais informações, consulte Valores de campo de paginação.
From WorkItems	Indica se você desejar que a consulta para localizar itens de trabalho ou links entre itens de trabalho. From WorkItems Use para itens de trabalho. From WorkItemLinks Use para links entre itens de trabalho.Para obter mais informações, consulte Consultas para links entre itens de trabalho.
Where [Work Item Type] = 'User Story'	Especifica os critérios de filtragem para a consulta.Para obter mais informações, consulte Cláusula where neste tópico posteriormente.
Order By [State] Asc, [Changed Date] Desc	(Opcional) especifique como classificar WorkItemCollection que a consulta retorna.
AsOf '6/15/2010'	(Opcional) especifique uma consulta históricas indicando uma data ou um ponto no tempo em que o filtro deve ser aplicado.Por exemplo, esta consulta retorna todas as histórias de usuário que existiam o 15 de junho de 2010. Observação Você não pode criar consultas de AsOf no construtor de consultas no Visual Studio.Se você criar um arquivo de consulta (.wiq) que inclua uma cláusula de AsOf e em seguida, carregue no Visual Studio, a cláusula de AsOf será ignorada.

Cláusula where

Onde a cláusula especifica os critérios de filtragem para uma consulta de itens de trabalho.O retorna de consulta trabalham somente os itens que satisfazem às condições.A seguinte consulta de exemplo retorna as histórias de usuário que são ativos e atribuídas a você.

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

Você pode controlar a ordem em que os operadores lógicos são avaliados se você usar parênteses para agrupar critérios de pesquisa.Por exemplo, para retornar os itens de trabalho que são atribuídos ou ou que você altera fechado, o filtro de consulta para coincidir com o seguinte exemplo:

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

A tabela a seguir descreve a sintaxe da cláusula where:

Operadores de Comparação

Você pode usar os operadores na tabela a seguir para especificar como um campo deve se relacionar ao valor correspondente:

As variáveis

Você pode usar variáveis nas consultas para passar entrada do usuário ou valores calculados.Para criar uma consulta que inclui variáveis, crie os espaços reservados na cadeia de caracteres de consulta usando @variable.Passar o nome e o valor de cada variável para o método de consulta usando uma implementação de IDictionary, como o exemplo a seguir mostra

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

Você também pode usar @Me ou @Today em sua consulta sem fornecer valores para as variáveis.Quando essas variáveis aparecem na consulta mas não têm nenhum valor associado passado na implementação de IDictionary , variáveis são avaliados como a tabela a seguir descreve:

valores literais

Quando você especificar um valor para cada campo, o valor deve corresponder ao tipo de dados de aquele campo.Todos os campos em Team Foundation têm um dos tipos de dados que são listados na tabela a seguir:

Consultas para links entre itens de trabalho

Você também pode usar consultas para localizar os links entre itens de trabalho.Uma condição no onde a cláusula pode aplicar aos links ou qualquer item de trabalho que é a origem ou o destino de um link.A tabela a seguir resume as diferenças entre esses tipos de consultas e consultas somente para itens de trabalho:

A seguinte consulta retorna os links entre as histórias de usuário e os seus filhos ativos.

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

Métodos de consulta e o objeto de consulta

Você pode ver para itens de trabalho usando o método de WorkItemStore.Query .Você também pode identificar o número de itens de trabalho que satisfazem uma consulta sem retornar todos os itens de trabalho usando o método de WorkItemStore.QueryCount .

você pode criar um objeto de Query para definir e executar consultas.

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

consultas assíncronos

você pode executar consultas de forma assíncrona usando o método de Query.BeginQuery .O exemplo executa uma consulta de forma assíncrona e cancela a consulta após um período de tempo limite muito tempo.

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

Valores de campo de paginação

WorkItemCollection que retorna uma consulta contém valores para os campos seguintes:

• ID

• Rev (revisão)

• AreaID

• IterationID

• WorkItemType

Os valores dos campos que você especificar na cláusula SELECT são retornados em páginas.

Observação
Por padrão, cada página contém os campos selecionados para 50 itens de trabalho.você pode ajustar o tamanho de uma página usando WorkItemCollection.PageSize.

Você pode minimizar viagens de ida e volta para o servidor selecionando todos os campos que seu código irá usar.O código a seguir faz processamento para a consulta e uma viagem para retornar todas as vezes em uma página de títulos que uma nova página é acessada.

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

Se seu código acessa um campo que você não especificar na cláusula SELECT, o campo é adicionado ao conjunto de campos paginados.Outra processamento é executada para atualizar a página para incluir os valores de aquele campo.

Sintaxe da consulta (EBNF)

O formato Backus-Naur (EBNF) é estendido para metalinguagem que descreve a gramática de idiomas de uma maneira mais compacta e ambígua.Este bloco de código usa EBNF para descrever a gramática de linguagem de consulta (WIQL) de item de trabalho.

Se você não estiver familiarizado com o EBNF, consulte uma descrição alternativo de WIQL em 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.

Consulte também

Conceitos

Estendendo o acompanhamento de item de trabalho usando o modelo de objeto de cliente para o team foundation