Consultar errores, tareas y otros elementos de trabajo

Artículo
02/19/2013

Puede consultar los errores, tareas, otros tipos de elementos de trabajo, y los vínculos entre elementos de trabajo mediante uno de los métodos WorkItemStore.Query o un objeto Query .Estas consultas utilizan el lenguaje (WIQL) de consulta de elementos de trabajo, que se parece 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”)

En este tema

Permisos necesarios

Una consulta devolverá sólo los elementos de trabajo para los que tenga permiso Ver elementos de trabajo o Ver los elementos de trabajo en este nodo .Normalmente, estos permisos se conceden a los miembros de los grupos Readers y Contributors para cada proyecto de equipo.Para obtener más información, vea Permisos de Team Foundation Server.

Sugerencia
Para explorar los detalles del lenguaje de consulta de elementos de trabajo, crear consultas mediante Team Explorery, a continuación guárdelo como archivos de .wiql.Cambie el nombre de los archivos para utilizar la extensión .xml, y abrirlos en Visual Studio.Busque el elemento wiql para ver cómo cada consulta se expresa en el lenguaje de consulta de elementos de trabajo.

Lenguaje de consulta

El lenguaje de consulta de elementos de trabajo tiene 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 cuyo valor esté establecido en cada WorkItem devuelto por la consulta.Puede especificar el nombre para mostrar o el nombre de referencia de campo.Debe utilizar corchetes ([]) si el nombre contiene espacios en blanco o puntos. Precaución Puede utilizar WorkItem que se devuelto por una consulta para obtener el valor Field, incluso si la consulta no devuelve el valor.Si lo hace, otra acción de ida y vuelta al servidor aparecerá.Para obtener más información, vea Paginación de valores de campo.
From WorkItems	Indica si desea que la consulta para buscar elementos de trabajo o vínculos entre los elementos de trabajo. From WorkItems Uso de los elementos de trabajo. From WorkItemLinks Uso de los vínculos entre los elementos de trabajo.Para obtener más información, vea Consulta los elementos de trabajo entre los vínculos.
Where [Work Item Type] = 'User Story'	Especifica los criterios de filtro para la consulta.Para obtener más información, vea La cláusula where más adelante en este tema.
Order By [State] Asc, [Changed Date] Desc	(Opcional) especifica cómo ordenar WorkItemCollection que devuelve la consulta.
AsOf '6/15/2010'	(Opcional) especifica una consulta histórica indicando una fecha o un momento en el que debe el filtro aplicar.Por ejemplo, esta consulta devuelve todos los casos de usuario que ya existían el 15 de junio de 2010. Nota No puede crear consultas de AsOf en el generador de consultas en Visual Studio.Si crea un archivo de consulta (.wiq) que incluye una cláusula de AsOf, y a continuación carga que en Visual Studio, la cláusula de AsOf se omitirá.

La cláusula where

La cláusula where especifica los criterios de filtro de una consulta de elementos de trabajo.La consulta devuelve sólo los elementos de trabajo que cumplen estas condiciones.La siguiente consulta de ejemplo devuelve los casos de usuario activas y que tiene asignados.

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

Puede controlar el orden en que se evalúan los operadores lógicos si utiliza paréntesis para agrupar criterios de búsqueda.Por ejemplo, devolver elementos de trabajo que tiene asignados o que se haya cerrado, cambia el filtro de la consulta para que coincida con el ejemplo siguiente:

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

La tabla siguiente se describe la sintaxis de la cláusula where:

	Sintaxis	Ejemplo
La cláusula where	Where FilterCondition [Group\|{LogicalOperator FilterCondition}]
Grupo	(FilterCondition LogicalOperator FilterCondition [LogicalOperator Filter Condition]…)	([Assigned to] = @Me OR [Created by = @Me]) Los operadores de agrupación lógica son AND y OR.
FilterCondition	Field ComparisonOperator Value	[Work Item Type] = ‘Help Topic’ Puede especificar el nombre de referencia o el nombre para mostrar de un campo.Si el nombre contiene espacios o puntos, debe agregarlo entre corchetes ([]). Se describen los operadores de comparación en Operadores de comparación más adelante en este tema. Por valor, puede especificar un valor literal (“caso de usuario ") o una macro (@Me).
Valor	LiteralValue\|Variable\|Field	'User Story' Valor literal El valor real a comparar el valor del campo.Para obtener más información, vea Valores literales más adelante en este tema. Variable Una expresión que indica un determinado valor.Por ejemplo, @Me indica a la persona que ejecuta la consulta.Para obtener más información, vea Variables más adelante en este tema. Campo El nombre de otro campo.Por ejemplo, puede utilizar [Assigned to] = [Changed by]para buscar elementos de trabajo asignados a la persona que modificó el elemento de trabajo por última vez.

Operadores de comparación

Puede usar los operadores en la tabla siguiente para especificar cómo un campo debe relacionar con el valor correspondiente:

Operador de consulta	Descripción	Tipos aplicables de campos
=	Coincide con el valor.	Número, Texto, Fecha, Árbol
<>	No coincide con el valor.	Número, Texto, Fecha, Árbol
>	Es mayor que el valor.	Número, Texto, Fecha
<	Es menor que el valor.	Número, Texto, Fecha
>=	Es mayor o igual que el valor.	Número, Texto, Fecha
<=	Es menor o igual que el valor.	Número, Texto, Fecha
Contiene	Contiene la cadena.	Texto
No contiene	No contiene la cadena.	Texto
In	Coincide con cualquier valor de un conjunto separados por comas.Por ejemplo, [System.Id] In (100, 101, 102) busque los elementos de trabajo cuyos id. son 100, 101, y 102.	Número, Texto, Fecha, Árbol
En grupo	Es un miembro del grupo.El grupo puede ser un grupo Team Foundation ([Assigned to] In Group [Project]\Contributors) o una categoría de elemento de trabajo si se usa con el campo tipo de elemento de trabajo ([Work Item Type] In Group Requirements).Para obtener información sobre los grupos de categorías, vea Definir categorías para agrupar los tipos de elementos de trabajo.	Texto
No en grupo	No es miembro del grupo.Para obtener más información, vea la entrada In Group.	Texto
Fue	Coincide con si coincide con el campo nunca el valor, incluso si ha cambiado a un valor diferente.	Texto, Fecha
Pertenece a	Para las áreas y las iteraciones, coincidencias si el elemento de trabajo está en ese nodo o de sus nodos secundarios.Para obtener información sobre las áreas e iteraciones, vea Crear y modificar áreas e iteraciones.	Tree
No pertenece a	Para las áreas y las iteraciones, coincidencias si el elemento de trabajo no está en ese nodo o ninguno de sus nodos secundarios.	Tree

Variables

Puede usar variables en las consultas para pasar los datos proporcionados por el usuario o valores calculados.Para crear una consulta que incluye variables, cree los marcadores en la cadena de consulta utilizando @variable.A continuación pase el nombre y el valor de cada variable al método de consulta mediante una implementación IDictionary, como se muestra en el ejemplo siguiente

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

También puede utilizar @Me o @Today en la consulta sin proporcionar los valores de esas variables.Cuando estas variables aparecen en la consulta pero no tienen ningún valor asociado pasado en la implementación IDictionary , se evalúan las variables mientras se describen en la tabla siguiente:

Variable	Uso
@Me	Indica al usuario actual en un campo que contenga los nombres de usuario.Por ejemplo, puede buscar elementos de trabajo que se provocó si especifica [Activated by] =@Me.
@Today	Indica la fecha actual.También puede modificar la variable @Today agregando o restando días.Por ejemplo, puede buscar todos los elementos que se activó en la última semana si especifica [Activated Date] > @Today - 7.

Valores literales

Cuando se especifica un valor para cada campo, el valor debe coincidir con el tipo de datos de ese campo.Todos los campos Team Foundation tienen uno de los tipos de datos que se muestran en la siguiente tabla:

Tipo de datos	Datos almacenados
DateTime	Un valor datetime definido por SQL Server.De forma predeterminada, los valores de datetime en consultas para los elementos de trabajo se tratan como si tuvieran precisión de fecha.Por ejemplo, un elemento de trabajo que se crea en cualquier momento del día el 1 de junio de 2010, coincidiría con los criterios de filtro [Created Date] = 6/1/2010. Para obtener más información, vea Métodos del objeto de consulta más adelante en este tema y la página siguiente en el sitio web de Microsoft: fecha y hora (Transact-SQL).
Double	Un número real, como 0,2 o 3,5.
GUID	Una cadena de caracteres que representa el GUID.
HTML	Cadenas de texto que contienen HTML.
Integer	Un entero de 32 bits con signo, como 0, 1, 2, 34.
PlainText	Una cadena de texto sin formato que puede ser más de 255 caracteres.
Cadena.	Una cadena de texto que contiene hasta 255 caracteres.
TreePath	Una estructura de árbol de bifurcación, como un área o iteración.

Consulta los elementos de trabajo entre los vínculos

También puede utilizar consultas para buscar los vínculos entre elementos de trabajo.Una condición en la cláusula where puede aplicar a los vínculos o a cualquier elemento de trabajo que será el origen o el destino de un vínculo.La tabla siguiente se resumen las diferencias entre estos tipos de consultas y consultas solo para los elementos de trabajo:

	Elementos de trabajo	Vínculos entre los elementos de trabajo
De cláusula	Grupo De tareas workitemtracking	De WorkItemLinks
La cláusula where	[FieldName] = Value	Uno de los siguientes: [Source].[FieldName] = Value [Target].[FieldName] = Value [System.Links.LinkType] = 'LinkName'
Modo		Uno de los siguientes: mode(MustContain) (Valor predeterminado) solo devuelve los registros WorkItemLinkInfo donde se satisfacen el origen, el destino, y los criterios todos del vínculo. mode(MayContain) Devuelve los registros WorkItemLinkInfo para todos los elementos de trabajo que satisfacen los criterios de origen y de vínculo, incluso si ningún elemento de trabajo vinculado satisfacen los criterios de destino. mode(DoesNotContain) Devuelve los registros WorkItemLinkInfo para todos los elementos de trabajo que satisfacen el origen, sólo si ningún elemento de trabajo vinculado satisfacen los criterios del vínculo y de destino.
Valores devueltos	[ T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemCollection ]	Matriz de objetos WorkItemLinkInfo.

La consulta siguiente devuelve los vínculos entre los casos de usuario y sus nodos secundarios activos.

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 del objeto de consulta

Puede consultar los elementos de trabajo utilizando el método WorkItemStore.Query .También puede identificar el número de elementos de trabajo que satisfacen una consulta sin devolver todos los elementos de trabajo utilizando el método WorkItemStore.QueryCount .

Puede crear un objeto Query para definir y ejecutar 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 asincrónicas

Puede ejecutar consultas de forma asincrónica utilizando el método Query.BeginQuery .El ejemplo siguiente ejecuta una consulta de forma asincrónica y cancela la consulta después de un tiempo de espera muy corto.

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

Paginación de valores de campo

WorkItemCollection que una consulta devuelve contiene los valores de los campos siguientes:

Id.
Rev (revisión)
AreaID
IterationID
WorkItemType

Los valores de los campos que se especifica en la cláusula select se devuelven en páginas.

[!NOTA]

De forma predeterminada, cada página contiene los campos seleccionados para 50 elementos de trabajo.Puede ajustar el tamaño de una página mediante WorkItemCollection.PageSize.

Puede minimizar recorridos de ida y vuelta al servidor seleccionando todos los campos que el código.El código siguiente realiza un viaje de ida y vuelta para la consulta y una acción de ida y vuelta para devolver una página titles cada vez que una nueva página vez.

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

Si el código tiene acceso a un campo que no especificó en la cláusula select, dicho campo se agrega al conjunto de campos paginados.Otra acción de ida y vuelta se realiza para actualizar esa página para incluir valores de ese campo.

Sintaxis de consulta (EBNF)

La forma de Backus-Naur extendida (EBNF) es el metalenguaje que describe la gramática de lenguajes de una manera concisa e inequívoca.Este bloque de código utiliza EBNF para describir la gramática del lenguaje (WIQL) de la consulta de elementos de trabajo.

Si no está familiarizado con EBNF, vea una descripción de WIQL en 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.

Vea también

Conceptos

Extender el seguimiento de elementos de trabajo usando el modelo de objetos de cliente para Team Foundation

Compartir a través de