Condividi tramite

Informazioni di riferimento sulla sintassi Work Item Query Language (WIQL)

  • Articolo

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

È possibile usare la sintassi WIQL per definire una query come collegamento ipertestuale o quando si usa l'API REST (Work Item Query Language).

La sintassi WIQL supporta tutte le funzioni disponibili tramite il portale Web Editor di query più altri. È possibile specificare i campi da restituire e specificare il raggruppamento logico delle clausole di query. Inoltre, è possibile usare una ASOF clausola per filtrare in base alle assegnazioni in base a una data precedente.

Importante

La sintassi WIQL viene usata per eseguire l'API REST Query by Wiql. Attualmente, non è possibile chiamare l'API per restituire direttamente le informazioni dettagliate sugli elementi di lavoro da una query WIQL. Indipendentemente dai campi inclusi nell'istruzione SELECT, l'API restituisce solo gli ID elemento di lavoro. Per ottenere le informazioni complete, è necessario eseguire due passaggi: (1) ottenere l'ID degli elementi di lavoro da un WIQL e (2) ottenere gli elementi di lavoro tramite Ottenere un elenco di elementi di lavoro per ID e per campi specifici.

Prerequisiti

Una query restituisce solo gli elementi di lavoro per i quali si dispone dell'autorizzazione Visualizza elementi di lavoro o Visualizza elementi di lavoro in questo nodo . In genere, queste autorizzazioni vengono concesse ai membri dei gruppi Lettori e Collaboratori per ogni progetto team. Per altre informazioni, vedere Autorizzazioni e gruppi.

Panoramica dei linguaggi di query

Il linguaggio di query dell'elemento di lavoro include cinque parti illustrate nel frammento di sintassi seguente e descritte nella tabella seguente. La sintassi WIQL non fa distinzione tra maiuscole e minuscole.

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'

Suggerimento

Installando l'estensione Marketplace dell'editor Wiql, è possibile costruire le query usando il Editor di query e quindi visualizzare la sintassi WIQL. È quindi possibile copiare e modificare la sintassi WIQL ed eseguire la query usando l'hub Wiql Playground aggiunto a Boards.

Clausola

Esempio

SELECT

Identifica i campi da restituire per ogni elemento di lavoro restituito dalla query. È possibile specificare il nome descrittivo o il nome di riferimento. Usare parentesi quadre ([]) se il nome contiene spazi vuoti o punti.

FROM

Indica se si desidera che la query trovi elementi di lavoro o collegamenti tra elementi di lavoro.

  • Usare FROM WorkItems per restituire elementi di lavoro.
  • Utilizzare FROM workItemLinks per restituire collegamenti tra elementi di lavoro. Per altre informazioni, vedere Query per i collegamenti tra gli elementi di lavoro più avanti in questo articolo.

WHERE

Specifica i criteri di filtro per la query. Per altre informazioni, vedere Condizioni di filtro (WHERE) più avanti in questo articolo.

ORDER BY

Specifica l'ordinamento degli elementi di lavoro restituiti. È possibile specificare Ascending (Asc) o Descending (Desc) per uno o più campi. Ad esempio:
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

Specifica una query cronologica che indica una data di applicazione del filtro. Ad esempio, questa query restituisce tutte le storie utente definite come Attive il 11 febbraio 2020. Specificare la data in base alle indicazioni fornite in Data e ora. ASOF '02-11-2020'

Nota

La lunghezza di WIQL delle query eseguite su Azure Boards non deve superare i 32.000 caratteri. Il sistema non consente di creare o eseguire query che superano tale lunghezza.

Modello di data e ora

Il modello di data e ora immesso per i campi DateTime deve corrispondere a quello selezionato tramite il profilo. Per visualizzare o modificare la selezione, vedere Impostare le preferenze utente.

Screenshot che mostra le opzioni dell'elenco a discesa Modello di data nel riquadro Ora e impostazioni locali.Screenshot che mostra le opzioni dell'elenco a discesa Modello di tempo nel riquadro Ora e impostazioni locali.

Screenshot che mostra il riquadro Ora e impostazioni locali con i campi Modello di data e Ora.

I valori letterali DateTime usati nei confronti sono virgolette singole o doppie. Devono essere nel formato DateTime .NET del computer client locale che esegue la query. A meno che non venga specificato un fuso orario, i valori letterali DateTime si trovano nel fuso orario del computer locale.

WHERE 
   AND [System.ChangedDate] >= '01-18-2019 GMT'
   AND ([Closed Date] < '01-09-2022 GMT'
   OR [Resolved Date] >= '01-18-2019 14:30:01')

Quando l'ora viene omessa in un valore letterale DateTime e il parametro dayPrecision è uguale a false, si presuppone che l'ora sia zero (mezzanotte). L'impostazione predefinita per il parametro dayPrecision è false.

In alternativa, è possibile specificare il formato ISO 8601 valido indipendentemente dalle impostazioni locali. ISO 8601 rappresenta data e ora a partire dall'anno, seguito dal mese, dal giorno, dall'ora, dai minuti, dai secondi e dai millisecondi. Ad esempio, 2021-12-10 15:00:00.000, rappresenta il 10 dicembre 2021 alle 13:00 nell'ora locale. Di seguito è riportato un esempio di utilizzo del formato ISO 8601.

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

Campi personalizzati

È possibile aggiungere un campo personalizzato a una clausola di query. Con WIQL è necessario specificare il nome di riferimento per il campo personalizzato. Per i progetti che usano un modello di processo ereditato, i campi personalizzati vengono in genere etichettati con Custom. Anteporti al nome e gli spazi rimossi. Ad esempio:

Nome descrittivo Nome riferimento
Approver Custom.Approver
Tipo di richiesta Custom.RequestType
Stima ambito Custom.CustomEstimate

Per i progetti che utilizzano il modello di processo XML locale, il nome di riferimento è definito dalle definizioni dei tipi di elemento di lavoro XML.

Per altre informazioni, vedere Campi e attributi dell'elemento di lavoro.

Specificare le clausole di filtro (WHERE)

La WHERE clausola specifica i criteri di filtro. La query restituisce solo gli elementi di lavoro che soddisfano i criteri specificati. Ad esempio, la clausola di esempio WHERE seguente restituisce storie utente attive e assegnate all'utente.

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

È possibile controllare l'ordine in cui gli operatori logici vengono valutati racchiudendoli tra parentesi per raggruppare i criteri di filtro. Ad esempio, per restituire elementi di lavoro assegnati all'utente o chiusi, modificare il filtro di query in modo che corrisponda all'esempio seguente.

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

Condizioni filtro

Ogni condizione di filtro è costituita da tre parti, ognuna delle quali deve essere conforme alle regole seguenti:

  • Campo: è possibile specificare il nome del riferimento o il nome descrittivo. Gli esempi seguenti sono la sintassi WIQL valida:
    • Nome riferimento: SELECT [System.AssignedTo] ...
    • Nome descrittivo con spazi: SELECT [Assigned To] ...
    • I nomi senza spazi non richiedono parentesi quadre: SELECT ID, Title ...
  • Operatore: i valori validi vengono specificati nella sezione Operatori più avanti in questo articolo.
  • Valore campo: è possibile specificare uno dei tre valori seguenti a seconda del campo specificato.
    • Un valore letterale deve corrispondere al tipo di dati del valore del campo.
    • *variabile o macro che indica un determinato valore. Ad esempio, @Me indica la persona che esegue la query. Per altre informazioni, vedere Macro e variabili più avanti in questo articolo.
    • Nome di un altro campo. Ad esempio, è possibile usare [Assigned to] = [Changed by] per trovare gli elementi di lavoro assegnati alla persona che ha modificato l'elemento di lavoro più di recente.

Per una descrizione e nomi di riferimento di tutti i campi definiti dal sistema, vedere Indice dei campi elemento di lavoro.

Operatori

Le query usano espressioni logiche per qualificare i set di risultati. Queste espressioni logiche sono costituite da una o più operazioni congiunte.

Di seguito sono elencate alcune semplici operazioni di query.

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

La tabella seguente riepiloga tutti gli operatori supportati per i diversi tipi di campo. Per altre informazioni su ogni tipo di campo, vedere Campi e attributi dell'elemento di lavoro.

Gli =, <>, >, <, >=, and <= operatori funzionano come previsto. Ad esempio, System.ID > 100 le query per tutti gli elementi di lavoro con ID maggiore di 100. System.ChangedDate > '01-01-19 12:00:00' query per tutti gli elementi di lavoro modificati dopo il 1° gennaio 2019.

Oltre a questi operatori di base, esistono alcuni comportamenti e operatori specifici per determinati tipi di campo.

Nota

Gli operatori disponibili dipendono dalla piattaforma e dalla versione. Per altre informazioni, vedere Informazioni di riferimento rapido sulle query.

Tipo di campo

Operatori supportati

Booleano

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

Data/Ora

= , <> , > , < , >= , <= , =[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

Identità

= , <> , > , < , >= , <= , =[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

Raggruppamenti logici

È possibile usare i termini AND e OR nel senso booleano tipico per valutare due clausole. È possibile usare i termini AND EVER e OR EVER quando si specifica un WAS EVER operatore. È possibile raggruppare le espressioni logiche e unirle ulteriormente in base alle esigenze. Di seguito sono riportati alcuni esempi.

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

È possibile negare gli contains, under, operatori e in usando not. Non è possibile negare l'operatore ever . Nell'esempio seguente vengono eseguite query per tutti gli elementi di lavoro non assegnati nel sottoalbero di Fabrikam Fiber\Account Management.

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

Query di esempio, mai assegnata a

Nell'esempio di Editor di query seguente vengono trovati tutti gli elementi di lavoro che sono stati assegnati a Jamal Hartnett.

Screenshot di Editor di query, query elenco flat, mai assegnata.

Ed ecco la sintassi WIQL corrispondente.

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

Macro o variabili

Nella tabella seguente sono elencate le macro o le variabili che è possibile usare all'interno di una query WIQL.

Macro Utilizzo
@Me Usare questa variabile per cercare automaticamente l'alias dell'utente corrente in un campo contenente alias utente. Ad esempio, è possibile trovare gli elementi di lavoro aperti se si imposta la colonna Field su Activated By, la colonna Operator su =e la colonna Value su @Me.
@CurrentIteration Usare questa variabile per filtrare automaticamente gli elementi di lavoro assegnati allo sprint corrente per il team selezionato in base al contesto del team selezionato.
@Project Usare questa variabile per cercare gli elementi di lavoro nel progetto corrente. Ad esempio, è possibile trovare tutti gli elementi di lavoro nel progetto corrente se si imposta la colonna Field su Team Project, la colonna Operator su =e la colonna Value su @Project.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Utilizzare queste macro per filtrare i campi DateTime in base all'inizio del giorno, della settimana, del mese, dell'anno o di un offset a uno di questi valori. Ad esempio, è possibile trovare tutti gli elementi creati negli ultimi 3 mesi se si imposta la colonna Campo su Data creazione, la colonna Operatore su >=e la colonna Valore su @StartOfMonth - 3.
@Today Utilizzare questa variabile per cercare gli elementi di lavoro correlati alla data corrente o a una data precedente. È anche possibile modificare la variabile @Today sottraendo giorni. Ad esempio, è possibile trovare tutti gli elementi attivati nell'ultima settimana se si imposta la colonna Campo su Data attivata, la colonna Operatore su >=e la colonna Valore su @Today - 7.
[Qualsiasi] Utilizzare questa variabile per cercare gli elementi di lavoro correlati a qualsiasi valore definito per un campo specifico.

@me macro

La @me macro sostituisce il nome dell'account integrato di Windows dell'utente che esegue la query. L'esempio seguente illustra come usare la macro e l'istruzione statica equivalente. La macro è destinata all'uso con campi Identity, Assigned Toad esempio .

WHERE  
   [System.AssignedTo] = @Me

@today macro

È possibile utilizzare la @today macro con qualsiasi campo DateTime . Questa macro sostituisce la mezzanotte della data corrente nel computer locale che esegue la query. È anche possibile specificare @today+x o @today-y usare offset integer per x giorni dopo @today e y giorni prima @todayrispettivamente. Una query che usa la @today macro può restituire set di risultati diversi a seconda del fuso orario in cui viene eseguita.

Gli esempi seguenti presuppongono che oggi sia 1/3/19.

WHERE  
   [System.CreatedDate] = @today

Equivale a:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Equivale a:

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

@StartOfDay, @StartOfWeek, @StartOfMonth@StartOfYear macro

È possibile utilizzare le @StartOf... macro con qualsiasi campo DateTime . Questa macro sostituisce la mezzanotte del giorno corrente, l'inizio della settimana, l'inizio del mese o l'inizio dell'anno nel computer locale che esegue la query.

Nota

Richiede Azure DevOps Server 2019 Update 1 o versione successiva.

Queste macro accettano una stringa di modifica con formato .(+/-)nn(y|M|w|d|h|m) Analogamente alla @Today macro, è possibile specificare offset di interi più o meno. Se il qualificatore di unità di tempo viene omesso, per impostazione predefinita viene impostato il periodo naturale della funzione. Ad esempio, @StartOfWeek("+1") è identico a @StartOfWeek("+1w"). Se il segno più/meno (+/-) viene omesso, si presuppone più.

Questa sintassi consente di annidare i modificatori e di sfalsare la query due volte. Ad esempio, la clausola Closed Date >= @StartOfYear - 1, filtra gli elementi di lavoro chiusi dall'anno precedente. Modificandolo in Closed Date >= @StartOfYear('+3M') - 1, esclude gli elementi di lavoro chiusi entro i primi tre mesi dell'anno precedente. La sintassi WIQL è come illustrato nell'esempio seguente.

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

Gli esempi seguenti presuppongono che oggi sia 4/5/19.

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

Equivale a:


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

And

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

Equivale a:

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

Macro personalizzate

WIQL supporta anche macro personalizzate arbitrarie. Qualsiasi stringa preceduta da un oggetto @ viene considerata come una macro personalizzata e viene sostituita. Il valore di sostituzione per la macro personalizzata viene recuperato dal parametro di contesto del metodo di query nel modello a oggetti. Il metodo seguente è l'API usata per le macro:

public WorkItemCollection Query(string wiql, IDictionary context)

Il parametro di contesto contiene coppie chiave-valore per le macro. Ad esempio, se il contesto contiene una coppia chiave-valore di (progetto, MyProject), @project viene sostituito da MyProject in WIQL. Questa sostituzione è il modo in cui il generatore di query dell'elemento di lavoro gestisce la macro @project in Visual Studio.

Specificare query cronologiche (ASOF)

È possibile usare una ASOF clausola in una query per filtrare gli elementi di lavoro che soddisfano le condizioni di filtro specificate in base a una data e un'ora specifiche.

Nota

Non è possibile creare ASOF query nel generatore di query in Visual Studio. Se si crea un file di query (con estensione wiq) che include una ASOF clausola e quindi lo si carica in Visual Studio, la ASOF clausola viene ignorata.

Si supponga che un elemento di lavoro sia stato classificato in un percorso di iterazione di Fabrikam Fiber\Release 1 e assegnato a "Jamal Hartnett" prima del 5/05/2022. Tuttavia, l'elemento di lavoro è stato recentemente assegnato a "Raisa Pokrovska" e spostato in un nuovo percorso di iterazione della versione 2. La query di esempio seguente restituisce gli elementi di lavoro assegnati a Jamal Hartnett perché la query si basa sullo stato degli elementi di lavoro a partire da una data e un'ora precedenti.

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

Se non viene specificata alcuna ora, WIQL usa mezzanotte. Se non viene specificato alcun fuso orario, WIQL usa il fuso orario del computer client locale.

Impostare l'ordinamento (ORDER BY)

È possibile utilizzare la ORDER BY clausola per ordinare i risultati di una query in base a uno o più campi in ordine crescente o decrescente.

Nota

Le preferenze di ordinamento del server SQL nel livello dati determinano l'ordinamento predefinito. Tuttavia, è possibile usare i asc parametri o desc per scegliere un ordinamento esplicito.

Nell'esempio seguente gli elementi di lavoro vengono ordinati prima per Priorità in ordine crescente (impostazione predefinita) e quindi in base alla data di creazione in ordine decrescente (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

Per restituire collegamenti tra elementi di lavoro, specificare FROM WorkItemLinks. Le condizioni di filtro nella WHERE clausola possono essere applicate ai collegamenti o a qualsiasi elemento di lavoro che sia l'origine o la destinazione di un collegamento. Ad esempio, la query seguente restituisce i collegamenti tra elementi di backlog prodotto e i relativi elementi figlio attivi.

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)

La tabella seguente riepiloga le differenze tra le query degli elementi di lavoro e le query per i collegamenti tra gli elementi di lavoro.

Clausola

Elementi di lavoro

Collegamenti tra elementi di lavoro

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

non applicabile

Specificare uno dei seguenti elementi:

  • MODE (MustContain): (impostazione predefinita) Restituisce solo i record WorkItemLinkInfo in cui vengono soddisfatti tutti i criteri di origine, destinazione e collegamento.
  • MODE (MayContain): restituisce i record WorkItemLinkInfo per tutti gli elementi di lavoro che soddisfano i criteri di origine e collegamento, 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 l'origine, solo se nessun elemento di lavoro collegato soddisfa i criteri di collegamento e di destinazione.
  • MODE (Recursive): usare per le query albero([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). Il tipo di collegamento deve essere topologia ad albero e direzione in avanti. Restituisce i record WorkItemLinkInfo per tutti gli elementi di lavoro che soddisfano l'origine, in modo ricorsivo per la destinazione. ORDER BY e ASOF non sono compatibili con le query albero.

RETURNS

WorkItemQueryResult

WorkItemLink

È possibile specificare uno dei nomi dei tipi di collegamento di sistema seguenti.

È possibile specificare uno dei nomi dei tipi di collegamento di sistema, elencati di seguito o un tipo di collegamento personalizzato definito con il processo XML locale.

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

Per altre informazioni, vedere Informazioni di riferimento sul tipo di collegamento.

Esempio di query del tipo di albero

La query seguente restituisce tutti i tipi di elemento di lavoro definiti nel progetto corrente. La query come illustrato nella Editor di query viene visualizzata come illustrato nell'immagine seguente.

Screenshot di Editor di query, query ad albero, tutti gli elementi di lavoro e gli stati.

Di seguito è illustrata la sintassi 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 query seguente restituisce tutti i tipi di elemento di lavoro definiti nel progetto corrente. La query come illustrato nella Editor di query viene visualizzata come illustrato nell'immagine seguente.

Screenshot di Editor di query, query direct-link, tutti gli elementi di lavoro e gli stati.

La sintassi WIQL equivalente è come illustrato.

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)

Altri esempi di query

Nell'esempio di query WIQL seguente vengono usati nomi di riferimento per i campi. La query seleziona gli elementi di lavoro (nessun tipo di elemento di lavoro specificato) con priority =1. La query restituisce l'ID e il titolo del set restituito come colonne. I risultati vengono ordinati in base all'ID in ordine crescente.

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

Modello di data e ora

Specificare il modello di data e ora in base a uno dei due modelli seguenti:

  • Il formato modello di data e ora deriva dalle preferenze dell'utente, dall'ora e dalle impostazioni locali
  • Modello specificato dall'ora UTC, che segue questo modello (con Z aggiunto alla data e ora).

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

Clausole di esempio

Le istruzioni di esempio seguenti mostrano clausole di qualificazione specifiche.

Clausola

Esempio

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

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

Stringa e testo non crittografato

I valori letterali stringa virgoletta (virgolette singole o doppie sono supportati) in un confronto con un campo stringa o testo normale. I valori letterali stringa supportano tutti i caratteri Unicode.

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

È possibile usare l'operatorecontains per cercare una sottostringa in qualsiasi punto del valore del campo.

WHERE [System.Description] contains 'WIQL'

Area e iterazione (TreePath)

È possibile usare l'operatore UNDER per i campi Area e Percorso iterazione. L'operatore UNDER valuta se un valore si trova all'interno del sottoalbero di un nodo di classificazione specifico. Ad esempio, l'espressione seguente restituisce true se il percorso area era "MyProject\Server\Administration", "MyProject\Server\Administration\Feature 1", "MyProject\Server\Administration\Feature 2\SubFeature 5" o qualsiasi altro nodo all'interno del sottoalbero.

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

Modificatori e operatori speciali

È possibile usare alcuni modificatori e operatori speciali in un'espressione di query.

Utilizzare l'operatore IN per valutare se un valore di campo è uguale a un set di valori. Questo operatore è supportato per i tipi di campo String, Integer, Double e DateTime. Vedere l'esempio seguente insieme al relativo equivalente semantico.

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

L'operatore EVER viene usato per valutare se un valore di campo è uguale o ha mai uguale a un valore specifico in tutte le revisioni precedenti degli elementi di lavoro. I tipi di campo String, Integer, Double e DateTime supportano questo operatore. Esistono sintassi alternative per l'operatore EVER . Ad esempio, i frammenti di codice seguenti eseguono una query se tutti gli elementi di lavoro sono stati assegnati 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>'
    )