Referencia de sintaxis del lenguaje de consultas de elemento de trabajo (WIQL)

  • Artículo

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

Puede usar la sintaxis WIQL para definir una consulta como hipervínculo o cuando se usa el lenguaje de consultas de elemento de trabajo (API de REST).

La sintaxis WIQL admite todas las funciones disponibles a través del Editor de consultas del portal web, y algunas más. Puede especificar los campos que se van a devolver y especificar la agrupación lógica de cláusulas de consulta. Además, puede usar una cláusula ASOF para filtrar según las asignaciones basadas en una fecha anterior.

Importante

La sintaxis WIQL se usa para ejecutar la API de REST de Query By Wiql. Actualmente, no hay ninguna manera de llamar a la API para devolver la información detallada del elemento de trabajo desde una consulta WIQL directamente. Independientemente de los campos que incluya en la instrucción SELECT, la API solo devuelve los id. de elemento de trabajo. Para obtener la información completa, debe realizar dos pasos: (1) obtener el id. de los elementos de trabajo de una WIQL y (2) obtener los elementos de trabajo a través de Obtener una lista de elementos de trabajo por id. y para campos específicos.

Requisitos previos

Una consulta devuelve solo los elementos de trabajo para los que tenga el 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 Lectores y Colaboradores de cada proyecto de equipo. Para obtener más información, consulte Permisos y grupos.

Información general del lenguaje de consulta

El lenguaje de consulta de elementos de trabajo tiene cinco partes que se muestran en el siguiente fragmento de sintaxis y se describen en la tabla siguiente. La sintaxis WIQL no distingue mayúsculas de minúsculas.

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'

Sugerencia

Al instalar la extensión de Marketplace Wiql Editor, puede construir las consultas mediante el Editor de consultas, y a continuación, ver la sintaxis WIQL. A continuación, puede copiar y modificar la sintaxis de WIQL y ejecutar la consulta mediante el centro de Wiql Playground agregado a Boards.

Cláusula

Ejemplo

SELECT

Identifica los campos que se van a devolver para cada elemento de trabajo devuelto por la consulta. Puede especificar el nombre descriptivo o el nombre de referencia. Use corchetes ([]) si el nombre contiene espacios en blanco o puntos.

FROM

Indica si desea que la consulta busque elementos de trabajo o vínculos entre elementos de trabajo.

  • Use FROM WorkItems para devolver elementos de trabajo.
  • Use FROM workItemLinks para devolver vínculos entre elementos de trabajo. Para obtener más información, consulte Consultas para vínculos entre elementos de trabajo, más adelante en este artículo.

WHERE

Especifica los criterios de filtro de la consulta. Para obtener más información, consulte Condiciones de filtro (WHERE) más adelante en este artículo.

ORDER BY

Especifica el criterio de ordenación de los elementos de trabajo devueltos. Puede especificar Ascendiente (Asc) o Descendiente (Desc) para uno o varios campos. Por ejemplo:
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

Especifica una consulta histórica indicando una fecha en la que se debe aplicar el filtro. Por ejemplo, esta consulta devuelve todos los casos de usuario definidos como Activo el 11 de febrero de 2020. Especifique la fecha según las instrucciones proporcionadas en el Patrón de fecha y hora. ASOF '02-11-2020'

Nota:

La longitud del código WIQL de las consultas realizadas en Azure Boards, no debe superar los 32 000 caracteres. El sistema no le permitirá crear ni ejecutar consultas que superen esa longitud.

Patrón de fecha y hora

El patrón de fecha y hora que escriba para los campos DateTime debe coincidir con el que seleccione mediante el perfil. Para ver o cambiar la selección, consulte Establecer preferencias de usuario de hora y configuración regional.

Captura de pantalla de las opciones desplegables de Patrón de fecha en el panel Hora y configuración regional.Captura de pantalla de las opciones desplegables de Patrón de hora en el panel Hora y configuración regional.

Captura de pantalla del panel Hora y configuración regional con los campos Patrón de fecha y Patrón de hora.

Colocar entre comillas (se admiten comillas simples o dobles) literales de DateTime utilizados en las comparaciones. Deben estar en el formato DateTime de .NET del equipo cliente local que ejecuta la consulta. A menos que se especifique una zona horaria, los literales DateTime se encuentran en la zona horaria del equipo 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')

Cuando la hora se omite en un literal DateTime y el parámetro dayPrecision es false, se supone que la hora es cero (medianoche). La configuración predeterminada para el parámetro dayPrecision es false.

O bien, puede especificar el formato ISO 8601 que es válido independientemente de la configuración regional. ISO 8601 representa la fecha y hora empezando por el año, el mes, el día, la hora, los minutos, los segundos y los milisegundos. Por ejemplo, 2021-12-10 15:00:00.000, representa el 10 de diciembre de 2021 a las 15:00 de la hora local. Un ejemplo de uso del formato ISO 8601 es el siguiente.

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')

Custom Fields

Puede agregar un campo personalizado a una cláusula de consulta. Con WIQL, debe especificar el nombre de referencia para el campo personalizado. En el caso de los proyectos que usan un modelo de proceso heredado, los campos personalizados normalmente se etiquetan con Custom. antepuesto al nombre y se quitan los espacios. Por ejemplo:

Nombre descriptivo Nombre de referencia
Aprobador Custom.Approver
Tipo de solicitud Custom.RequestType
Estimación del ámbito Custom.CustomEstimate

En el caso de los proyectos que usan el modelo de proceso XML local, el nombre de referencia se define según las definiciones de tipo de elemento de trabajo XML.

Para obtener más información, consulte Campos y atributos de elementos de trabajo.

Especificar cláusulas de filtro (WHERE)

La cláusula WHERE especifica los criterios de filtro. La consulta devuelve solo los elementos de trabajo que cumplen estas condiciones. Por ejemplo, la siguiente cláusula de ejemplo WHERE devuelve casos de usuario activos que tiene asignados.

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

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

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

Condiciones de filtro

Cada condición de filtro se compone de tres partes, cada una de las cuales debe cumplir las siguientes reglas:

  • Campo: puede especificar el nombre de referencia o el nombre descriptivo. Los siguientes ejemplos son sintaxis WIQL válida:
    • Nombre de referencia: SELECT [System.AssignedTo] ...
    • Nombre descriptivo con espacios: SELECT [Assigned To] ...
    • Los nombres sin espacios no requieren corchetes: SELECT ID, Title ...
  • Operador: los valores válidos se especifican en la sección Operadores más adelante en este artículo.
  • Valor de campo: puede especificar uno de los tres valores siguientes en función del campo especificado.
    • Un valor literal debe coincidir con el tipo de datos del valor de campo.
    • *Variable o macro que indica un valor determinado. Por ejemplo, @Me indica la persona que ejecuta la consulta. Para obtener más información, consulte Macros y variables, más adelante en este tema.
    • El nombre de otro campo. Por ejemplo, puede usar [Assigned to] = [Changed by] para buscar elementos de trabajo asignados a la persona que modificó el elemento de trabajo por última vez.

Para obtener una descripción y nombres de referencia de todos los campos definidos por el sistema, consulte Índice de campo de elementos de trabajo.

Operadores

Las consultas usan expresiones lógicas para calificar conjuntos de resultados. Estas expresiones lógicas están formadas por una o varias operaciones de unión.

A continuación, se enumeran algunas operaciones de consulta simples.

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

En la tabla siguiente se resumen todos los operadores admitidos para distintos tipos de campo. Para obtener más información sobre cada tipo de campo, consulte Campos y atributos de elementos de trabajo.

Los operadores =, <>, >, <, >=, and <= funcionan según lo previsto. Por ejemplo, System.ID > 100 consulta todos los elementos de trabajo con un id. superior a 100. Las consultas System.ChangedDate > '01-01-19 12:00:00' de todos los elementos de trabajo cambiaron después de las 12:00 del 1 de enero de 2019.

Además de estos operadores básicos, existen algunos comportamientos y operadores específicos de determinados tipos de campo.

Nota:

Los operadores disponibles dependen de la plataforma y la versión. Para más información, consulte Consulta de referencia rápida.

Tipo de campo

Operadores admitidos

Boolean

= , <> , =[Field] , <>[Field]

DateTime

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Double, GUID, Integer

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

identidad

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever

PlainText

Contains Words, Not Contains Words, Is Empty, Is Not Empty

String

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever

TreePath

=, <>, In, Not In, Under, Not Under

Agrupaciones lógicas

Puede usar los términos AND y OR en el sentido booleano típico para evaluar dos cláusulas. Puede usar los términos AND EVER y OR EVER al especificar un operador WAS EVER. Puede agrupar expresiones lógicas y unirlas aún más, según sea necesario. A continuación se muestran ejemplos.

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>'
        )
    )

Puede negar los operadores contains, under, y in mediante not. No se puede negar el operador ever. En el ejemplo siguiente se consultan todos los elementos de trabajo que no están asignados en el subárbol de Fabrikam Fiber\Account Management.

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

Consulta de ejemplo, Se asignó alguna vez a

En el ejemplo de Editor de consultas siguiente se buscan todos los elementos de trabajo asignados a Jamal Hartnett.

Captura de pantalla del Editor de consultas, consulta de lista plana, se asignó alguna vez...

Aquí está la sintaxis WIQL correspondiente.

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 o variables

En la tabla siguiente se enumeran las macros o variables que puede usar en una consulta WIQL.

Macro Uso
@Me Utilice esta variable para buscar automáticamente el alias del usuario actual en un campo que contiene los alias de usuario. Por ejemplo, puede buscar los elementos de trabajo que ha abierto si establece la columna Campo en Activado por, la columna Operador en = y la columna Valor en @Me.
@CurrentIteration Use esta variable para filtrar automáticamente los elementos de trabajo asignados al sprint actual para el equipo seleccionado en función del contexto del equipo seleccionado.
@Project Utilice esta variable para buscar elementos de trabajo en el proyecto actual. Por ejemplo, puede buscar todos los elementos de trabajo en el proyecto de equipo actual si establece la columna Campo en Proyecto de equipo, la columna Operador en = y la columna Valor en @Project.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Use estas macros para filtrar los campos DateTime en función del inicio del día actual, semana, mes, año o un desplazamiento a uno de estos valores. Por ejemplo, puede buscar todos los elementos creados durante los 3 últimos meses si establece la columna Campo en Fecha de creación, la columna Operador en >= y la columna Valor en @StartOfMonth - 3.
@Today Utilice esta variable para buscar los elementos de trabajo relacionados con la fecha actual o una fecha anterior. También puede modificar la variable @Today restando días. Por ejemplo, puede buscar todos los elementos activados la semana pasada si establece la columna Campo en Fecha de activación, la columna Operador en >= y la columna Valor en @Today - 7.
[Any] Utilice esta variable para buscar los elementos de trabajo relacionados con cualquier valor definido para un campo determinado.

@meMacro

La macro @me reemplaza el nombre de la cuenta integrada de Windows del usuario que ejecuta la consulta. En el ejemplo siguiente se muestra cómo usar la macro y la instrucción estática equivalente. La macro está pensada para su uso con campos de identidad como Assigned To.

WHERE  
   [System.AssignedTo] = @Me

@todayMacro

Puede usar la macro @today con cualquier campo DateTime. Esta macro reemplaza la medianoche de la fecha actual en el equipo local que ejecuta la consulta. También puede especificar @today+x o @today-y mediante desplazamientos enteros durante X días después de @today, y Y días antes de @today, respectivamente. Una consulta que usa la macro @today puede devolver diferentes conjuntos de resultados en función de la zona horaria en la que se ejecuta.

En los ejemplos siguientes se supone que hoy es 1/3/19.

WHERE  
   [System.CreatedDate] = @today

Es el equivalente de:

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

Y

WHERE  
   [System.CreatedDate] > @today-2

Es el equivalente de:

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

Macros @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear

Puede usar las macros @StartOf... con cualquier campo DateTime. Esta macro reemplaza la medianoche del día actual, el inicio de la semana, el inicio del mes o el inicio del año en el equipo local que ejecuta la consulta.

Nota:

Requiere Azure DevOps Server 2019 Update 1 o una versión posterior.

Estas macros aceptan una cadena modificadora que tiene un formato de (+/-)nn(y|M|w|d|h|m). De forma similar a la macro @Today, puede especificar desplazamientos enteros positivos o negativos. Si se omite el calificador de unidad de tiempo, el valor predeterminado es el período natural de la función. Por ejemplo, @StartOfWeek("+1") es lo mismo que @StartOfWeek("+1w"). Si se omite el signo más/menos (+/-), se supone que es más.

Esta sintaxis permite anidar modificadores y desplazar la consulta dos veces. Por ejemplo, la cláusula Closed Date >= @StartOfYear - 1, filtra los elementos de trabajo que se han cerrado desde el año pasado. Al modificarlo a Closed Date >= @StartOfYear('+3M') - 1, excluye los elementos de trabajo cerrados en los tres primeros meses del último año. La sintaxis WIQL es como se muestra en el ejemplo siguiente.

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

En los ejemplos siguientes se supone que hoy es 4/5/19.

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

Es el equivalente de:


WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2019'

Y

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

Es el equivalente de:

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2019'

Macros personalizadas

WIQL también admite macros personalizadas arbitrarias. Cualquier cadena precedida por un @ se trata como una macro personalizada y se sustituye. El valor de reemplazo de la macro personalizada se recupera del parámetro de contexto del método de consulta en el modelo de objetos. El método siguiente es la API que se usa para macros:

public WorkItemCollection Query(string wiql, IDictionary context)

El parámetro de contexto contiene pares clave-valor para macros. Por ejemplo, si el contexto contiene un par clave-valor de (proyecto, MiProyecto), @proyect o se sustituye por MyProject en el WIQL. Este reemplazo es el modo en que el generador de consultas del elemento de trabajo controla la macro @project en Visual Studio.

Especificar consultas de historial (ASOF)

Puede usar una cláusula ASOF en una consulta para filtrar los elementos de trabajo que cumplan las condiciones de filtro especificadas según se definieron en una fecha y hora específicas.

Nota:

No se pueden crear consultas ASOF en el generador de consultas de Visual Studio. Si se crea un archivo de consulta (.wiq) que incluya una cláusula ASOF y, a continuación, se carga en Visual Studio, la cláusula ASOF se omitirá.

Supongamos que un elemento de trabajo se clasificó en una ruta de iteración de Fabrikam Fiber\Release 1 y se asignó a "Jamal Hartnett" antes del 5/5/2022. Sin embargo, el elemento de trabajo se asignó recientemente a "Raisa Pokrovskaya" y se movió a una nueva ruta de iteración de la versión 2. El siguiente ejemplo de consulta devuelve los elementos de trabajo asignados a Jamal Hartnett porque la consulta se basa en el estado de los elementos de trabajo a partir de una fecha y hora pasadas.

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'

Nota:

Si no se especifica ninguna hora, WIQL usa medianoche. Si no se especifica ninguna zona horaria, WIQL usa la zona horaria del equipo cliente local.

Establecer el criterio de ordenación (ORDER BY)

Puede usar la cláusula ORDER BY para ordenar los resultados de una consulta por uno o varios campos en orden ascendente o descendente.

Nota:

Las preferencias de ordenación del servidor SQL Server en el nivel de datos determinan el criterio de ordenación predeterminado. Sin embargo, puede usar los parámetros asc o desc para elegir un criterio de ordenación explícito.

En el ejemplo siguiente se ordenan los elementos de trabajo primero por Prioridad en orden ascendente (valor predeterminado) y, a continuación, por Fecha de creación en orden descendente (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

Para devolver vínculos entre elementos de trabajo, especifique FROM WorkItemLinks. Pueden aplicarse condiciones de filtro en la cláusula WHERE a los vínculos o a cualquier elemento de trabajo que sea el origen o el destino de un vínculo. Por ejemplo, la consulta siguiente devuelve los vínculos entre elementos de trabajo pendiente de producto y sus elementos secundarios activos.

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)

En la tabla siguiente se resumen las diferencias entre las consultas de elementos de trabajo y las consultas de vínculos entre elementos de trabajo.

Cláusula

Elementos de trabajo

Vínculos entre elementos de trabajo

FROM

FROM WorkItems

FROM WorkItemLinks

WHERE

[FieldName] = Value

Specify one or more of the following:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'

MODE

no aplicable

Especifique uno de los siguientes:

  • MODE (MustContain): (Valor predeterminado) Devuelve solamente registros WorkItemLinkInfo donde se cumplen todos los criterios de origen, destino y vínculo.
  • MODE (MayContain): Devuelve registros WorkItemLinkInfo para todos los elementos de trabajo que cumplen los criterios de origen y vínculo, incluso si ningún elemento de trabajo vinculado cumple los criterios de destino.
  • MODE (DoesNotContain): Devuelve registros WorkItemLinkInfo para todos los elementos de trabajo que cumplen los criterios de origen, solo si ningún elemento de trabajo vinculado cumple los criterios de vínculo y destino.
  • MODE (Recursive): se usa para consultas de árbol ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). El tipo de vínculo debe ser topología de árbol y dirección de avance. Devuelve registros WorkItemLinkInfo para todos los elementos de trabajo que satisfacen el origen de forma recursiva para el destino. ORDER BY y ASOF no son compatibles con las consultas de árbol.

RETURNS

WorkItemQueryResult

WorkItemLink

Puede especificar uno de los siguientes nombres de tipo de vínculo del sistema.

Puede especificar uno de los nombres de tipo de vínculo del sistema, enumerados a continuación o un tipo de vínculo personalizado que haya definido con el proceso XML local.

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

Para obtener más información, consulte Referencia de tipo de vínculo.

Ejemplo de consulta de tipo de árbol

La consulta siguiente devuelve todos los tipos de elementos de trabajo definidos en el proyecto actual. La consulta que aparece en el Editor de consultas aparece igual en la imagen siguiente.

Captura de pantalla del Editor de consultas, consulta de árbol, todos los elementos de trabajo y estados.

A continuación se muestra la sintaxis WIQL equivalente.

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)

La consulta siguiente devuelve todos los tipos de elementos de trabajo definidos en el proyecto actual. La consulta que aparece en el Editor de consultas aparece igual en la imagen siguiente.

Captura de pantalla del Editor de consultas, consulta de vínculo directo, todos los elementos de trabajo y estados.

La sintaxis WIQL equivalente es la que se muestra.

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)

Más ejemplos de consultas

En el siguiente ejemplo típico de consulta WIQL se usan nombres de referencia para los campos. La consulta selecciona elementos de trabajo (sin ningún tipo de elemento de trabajo especificado) con Prioridad=1. La consulta devuelve el id. y el título del conjunto devuelto como columnas. Los resultados se ordenan por id. en orden ascendente.

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

Patrón de fecha y hora

Especifique el patrón de fecha y hora según uno de estos dos patrones:

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

Cláusulas de ejemplo

En las instrucciones de ejemplo siguientes se muestran cláusulas aptas específicas.

Cláusula

Ejemplo

AND

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

OR

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>' )

NOT

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

EVER

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

UNDER

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'

ORDER BY

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]

ASOF (Filtro de tiempo)

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

String y PlainText

Colocar entre comillas (se admiten comillas simples o dobles) literales de cadena en una comparación con un campo de texto sin formato o cadena. Los literales de cadena admiten todos los caracteres Unicode.

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

Puede usar el operador contains para buscar una subcadena en cualquier parte del valor del campo.

WHERE [System.Description] contains 'WIQL'

Área e iteración (TreePath)

Puede usar el operador UNDER para los campos Área y Ruta de iteración. El operador UNDER evalúa si un valor está dentro del subárbol de un nodo de clasificación específico. Por ejemplo, la expresión siguiente se evaluaría como true si la ruta de acceso del área fuera "MyProject\Server\Administration", "MyProject\Server\Administration\Feature 1", "MyProject\Server\Administration\Feature 2\SubFeature 5", o cualquier otro nodo del subárbol.

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

Modificadores y operadores especiales

Puede usar algunos modificadores y operadores especiales en una expresión de consulta.

Use el operador IN para evaluar si un valor de campo es igual a cualquiera de un conjunto de valores. Este operador es compatible con los tipos de campo Cadena, Entero, Doble y DateTime. Vea el ejemplo siguiente junto con su equivalente semántico.

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>'
    )

El operador EVER se usa para evaluar si un valor de campo es igual o ha igualado un valor determinado en todas las revisiones anteriores de los elementos de trabajo. Los tipos de campo Cadena, Entero, Doble y DateTime admiten este operador. Hay sintaxis alternativa para el operador EVER. Por ejemplo, los fragmentos de código siguientes consultan si todos los elementos de trabajo se asignaron alguna vez a Jamal, Raise o Christie.

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>'
    )