WIQL-Syntax (Work Item Query Language) – Syntaxreferenz

  • Artikel

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

Sie können die WIQL-Syntax verwenden, um eine Abfrage als Link oder bei Verwendung der Work Item Query Language (REST-API) zu definieren.

Die WIQL-Syntax unterstützt alle Funktionen, die über den Abfrage-Editor im Webportal verfügbar sind, sowie einige weitere Funktionen. Sie können die zurückzugebenden Felder und die logische Gruppierung von Abfrageklauseln angeben. Darüber hinaus können Sie eine ASOF-Klausel verwenden, um basierend auf Zuweisungen basierend auf einem vorherigen Datum zu filtern.

Wichtig

Die WIQL-Syntax wird verwendet, um die Query By Wiql-REST-API auszuführen. Derzeit gibt es keine Möglichkeit, die API aufzurufen, um die detaillierten Arbeitselementinformationen aus einer WIQL-Abfrage direkt zurückzugeben. Unabhängig davon, welche Felder Sie in die SELECT-Anweisung einschließen, gibt die API nur die Arbeitselement-IDs zurück. Um die vollständigen Informationen zu erhalten, müssen Sie zwei Schritte ausführen: (1) Abrufen der ID der Arbeitselemente aus einer WIQL-Abfrage und (2) Abrufen der Arbeitselemente über Abrufen einer Liste der Arbeitselemente nach ID und für bestimmte Felder.

Voraussetzungen

Von einer Abfrage werden nur die Arbeitselemente zurückgegeben, für die Sie über die Berechtigung Arbeitselemente anzeigen oder Arbeitselemente in diesem Knoten anzeigen verfügen. In der Regel werden diese Berechtigungen Mitgliedern der Gruppen Leser und Mitwirkende der einzelnen Teamprojekte erteilt. Weitere Informationen finden Sie unter Berechtigungen und Gruppen.

Übersicht über die Abfragesprache

Die Arbeitselement-Abfragesprache umfasst fünf Teile, die im folgenden Syntaxcodeschnipsel gezeigt und in der folgenden Tabelle beschrieben werden. Bei der WIQL-Syntax wird nicht zwischen Groß-/Kleinschreibung unterschieden.

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'

Tipp

Durch Installieren der Marketplace-Erweiterung Wiql-Editor können Sie Ihre Abfragen mithilfe des Abfrage-Editors erstellen und dann die WIQL-Syntax anzeigen. Anschließend können Sie die WIQL-Syntax kopieren und ändern und die Abfrage mithilfe des Wiql Playground-Hubs ausführen, der Boards hinzugefügt wurde.

Klausel

Beispiel

SELECT

Gibt die Felder an, die für jedes von der Abfrage zurückgegebene Arbeitselement zurückgegeben werden sollen. Sie können entweder den Anzeigenamen oder den Verweisnamen angeben. Verwenden Sie eckige Klammern ([]), wenn der Name Leerzeichen oder Punkte enthält.

FROM

Gibt an, ob die Abfrage Arbeitselemente oder Links zwischen Arbeitselementen suchen soll.

  • Verwenden Sie FROM WorkItems, um Arbeitselemente zurückzugeben.
  • Verwenden Sie FROM workItemLinks, um Links zwischen Arbeitselementen zurückzugeben. Weitere Informationen finden Sie unter Abfragen für Links zwischen Arbeitselementen.

WHERE

Gibt die Filterkriterien für die Abfrage an. Weitere Informationen finden Sie weiter unten in diesem Artikel unter Filterbedingungen (WHERE).

ORDER BY

Gibt die Sortierreihenfolge der zurückgegebenen Arbeitselemente an. Sie können Aufsteigend („Asc“) oder Absteigend („Desc“) für mehrere Felder angeben. Beispiel:
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

Gibt eine historische Abfrage an, indem ein Datum für die Anwendung des Filters festgelegt wird. Diese Abfrage gibt beispielsweise alle User Storys zurück, die am 11. Februar 2020 als Aktiv definiert waren. Geben Sie das Datum gemäß den Anleitungen unter Datums- und Uhrzeitmuster an. ASOF '02-11-2020'

Hinweis

Die WIQL-Länge von Abfragen für Azure Boards darf 32.000 Zeichen nicht überschreiten. Das System ermöglicht es Ihnen nicht, Abfragen zu erstellen oder auszuführen, die diese Länge überschreiten.

Datums- und Uhrzeitmuster

Das Datums- und Uhrzeitmuster, das Sie für DateTime-Felder eingeben, muss mit dem Muster übereinstimmen, das Sie über Ihr Profil auswählen. Um Ihre Auswahl anzuzeigen oder zu ändern, siehe Benutzereinstellungen für Zeit und Gebietsschema festlegen.

Screenshot, der die Dropdown-Optionen für das Datumsmuster im Bereich Zeit und Gebietsschema zeigt.Screenshot, der die Dropdown-Optionen für Zeitmuster im Bereich Zeit und Region zeigt.

Screenshot, der den Bereich Zeit und Gebietsschema mit den Feldern Datumsmuster und Zeitmuster zeigt.

Anführungszeichen (einfache oder doppelte Anführungszeichen werden unterstützt). DateTime-Literale, die in Vergleichen verwendet werden. Sie müssen im .NET DateTime-Format des lokalen Clientcomputers vorliegen, auf dem die Abfrage ausgeführt wird. Sofern keine Zeitzone angegeben wird, befinden sich DateTime-Literale in der Zeitzone des lokalen Computers.

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

Wenn die Uhrzeit in einem DateTime-Literal ausgelassen wird und der dayPrecision-Parameter den Wert FALSE aufweist, wird die Zeit als null (Mitternacht) angenommen. Die Standardeinstellung für den dayPrecision-Parameter ist FALSE.

Alternativ können Sie das ISO 8601-Format angeben, das unabhängig vom Gebietsschema gültig ist. ISO 8601 stellt Datum und Uhrzeit dar, indem mit dem Jahr begonnen wird, gefolgt vom Monat, dem Tag, der Stunde, den Minuten, Sekunden und Millisekunden. Beispielsweise stellt 2021-12-10 15:00:00:00.000 den 10. Dezember 2021 um 15 Uhr Ortszeit dar. Das folgende Beispiel zeigt die Verwendung des ISO 8601-Formats.

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

Benutzerdefinierte Felder

Sie können einer Abfrageklausel ein benutzerdefiniertes Feld hinzufügen. Bei WIQL müssen Sie den Verweisnamen für das benutzerdefinierte Feld angeben. Bei Projekten, die ein vererbtes Prozessmodell verwenden, wird dem Namen benutzerdefinierter Felder in der Regel Custom. vorangestellt, und Leerzeichen werden entfernt. Beispiel:

Anzeigename Verweisname
Genehmigende Person Custom.Approver
Anforderungstyp Custom.RequestType
Scope Estimate Custom.CustomEstimate

Für Projekte, die das lokale XML-Prozessmodell verwenden, wird der Verweisname durch die XML-Arbeitselement-Typdefinitionen definiert.

Weitere Informationen finden Sie unter Arbeitselementfelder und -attribute.

Angeben von Filterklauseln (WHERE)

Die WHERE-Klausel gibt die Filterkriterien an. Von der Abfrage werden nur Arbeitselemente zurückgegeben, die die angegebenen Kriterien erfüllen. Die folgende WHERE-Beispielklausel etwa gibt User Storys zurück, die aktiv und Ihnen zugewiesen sind.

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

Sie können die Reihenfolge steuern, in der logische Operatoren ausgewertet werden, indem Sie sie in Klammern einschließen, um die Filterkriterien zu gruppieren. Um beispielsweise Arbeitselemente zurückzugeben, die entweder Ihnen zugewiesen sind oder von Ihnen geschlossen wurden, ändern Sie den Abfragefilter so, dass er dem folgenden Beispiel entspricht.

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

Filterbedingungen

Jede Filterbedingung besteht aus drei Teilen, die jeweils den folgenden Regeln genügen müssen:

  • Feld: Sie können den Verweisnamen oder den Anzeigenamen angeben. Die folgenden Beispiele sind gültige WIQL-Syntax:
    • Verweisname: SELECT [System.AssignedTo] ...
    • Anzeigename mit Leerzeichen: SELECT [Assigned To] ...
    • Namen ohne Leerzeichen erfordern keine eckigen Klammern: SELECT ID, Title ...
  • Operator: Gültige Werte werden weiter unten in diesem Artikel im Abschnitt Operatoren angegeben.
  • Feldwert: Sie können je nach angegebenem Feld einen der folgenden drei Werte angeben.
    • Ein Literalwert muss mit dem Datentyp des Feldwerts übereinstimmen.
    • Eine *-Variable oder ein Makro, die bzw. das einen bestimmten Wert angibt. Beispielsweise gibt @Me die Person an, von der die Abfrage ausgeführt wird. Weitere Informationen finden Sie weiter unten in diesem Artikel unter Makros und Variablen.
    • Der Name eines anderen Felds. Beispielsweise können Sie mit [Assigned to] = [Changed by] Arbeitselemente suchen, die der Person zugewiesen sind, von der die letzten Änderungen an diesen Arbeitselementen vorgenommen wurden.

Eine Beschreibung und Verweisnamen aller systemseitig definierten Felder finden Sie unter Arbeitselement-Feldindex.

Operatoren

Abfragen verwenden logische Ausdrücke, um Resultsets zu qualifizieren. Diese logischen Ausdrücke werden durch einen oder mehrere zusammenhängende Vorgänge gebildet.

Einige einfache Abfragevorgänge werden unten aufgeführt.

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

In der folgenden Tabelle werden alle unterstützten Operatoren für verschiedene Feldtypen zusammengefasst. Weitere Informationen zu den einzelnen Feldtypen finden Sie unter Arbeitselementfelder und -attribute.

Die =, <>, >, <, >=, and <=-Operatoren funktionieren wie erwartet. Beispielsweise System.ID > 100-Abfragen für alle Arbeitselemente mit einer ID, die größer als 100 ist. System.ChangedDate > '01-01-19 12:00:00'-Abfragen für alle Arbeitselemente, die nach 12 Uhr am 1. Januar 2019 geändert wurden.

Neben diesen grundlegenden Operatoren gibt es einige Verhaltensweisen und Operatoren, die für bestimmte Feldtypen spezifisch sind.

Hinweis

Die für Sie verfügbaren Operatoren hängen von Ihrer Plattform und Version ab. Weitere Informationen finden Sie unter Abfragekurzreferenz.

Feldtyp

Unterstützte Operatoren

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

Identität

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

Logische Gruppierungen

Sie können die Operatoren AND und OR im typischen booleschen Sinne verwenden, um zwei Klauseln auszuwerten. Sie können die Operatoren AND EVER und OR EVER verwenden, wenn Sie einen WAS EVER-Operator angeben. Sie können logische Ausdrücke gruppieren und bei Bedarf weiter zusammenfügen. Im Anschluss finden Sie einige Beispiele.

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

Sie können die Operatoren contains, under, und in negieren, indem Sie not verwenden. Sie können den ever-Operator nicht negieren. Im folgenden Beispiel werden alle Arbeitselemente abgefragt, die nicht unter der Unterstruktur von Fabrikam Fiber\Account Management zugewiesen sind.

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

Beispielabfrage: „Was Ever Assigned To“

Im folgenden Abfrage-Editor-Beispiel werden alle Arbeitselemente gesucht, die Jamal Hartnett jemals zugewiesen waren.

Screenshot: Abfrage-Editor, Flatlistabfrage, jemals zugewiesen.

Hier sehen Sie die entsprechende WIQL-Syntax.

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

Makros oder Variablen

In der folgenden Tabelle werden die Makros oder Variablen aufgeführt, die Sie in einer WIQL-Abfrage verwenden können.

Makro Verbrauch
@Me Verwenden Sie diese Variable, um in einem Feld mit Benutzeraliasen automatisch nach dem Alias des aktuellen Benutzers zu suchen. Sie können beispielsweise nach von Ihnen geöffneten Arbeitselemente suchen, indem Sie die Spalte Feld auf Aktiviert von, die Spalte Operator auf = und die Spalte Wert auf @Me festlegen.
@CurrentIteration Verwenden Sie diese Variable, um basierend auf dem ausgewählten Teamkontext automatisch nach Arbeitselementen zu filtern, die dem aktuellen Sprint für das ausgewählte Team zugewiesen sind.
@Project Verwenden Sie diese Variable, um im aktuellen Projekt nach Arbeitselementen zu suchen. Sie können z. B. nach allen Arbeitselementen im aktuellen Projekt suchen, indem Sie die Spalte Feld auf Teamprojekt, die Spalte Operator auf = und die Spalte Wert auf @Project festlegen.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Verwenden Sie diese Makros, um DateTime-Felder basierend auf dem Beginn des aktuellen Tages, der aktuellen Woche, des Monats, des aktuellen Jahres oder eines Offsets zu einem dieser Werte zu filtern. Sie können beispielsweise alle in den letzten 3 Monaten erstellten Elemente finden, wenn Sie die Spalte Feld auf Erstellungsdatum, die Spalte Operator auf >= und die Spalte Wert auf @StartOfMonth - 3 festlegen.
@Today Verwenden Sie diese Variable, um nach Arbeitsaufgaben zu suchen, die sich auf das aktuelle Datum oder auf einen früheren Termin beziehen. Sie können die Variable @Today auch durch das Subtrahieren von Tagen ändern. Sie können beispielsweise alle Elemente suchen, die in der letzten Woche aktiviert wurden. Dazu legen Sie die Spalte Feld auf Aktivierungsdatum, die Spalte Operator auf >= und die Spalte Wert auf @Today -7 fest.
[Any] Verwenden Sie diese Variable, um nach Arbeitselementen zu suchen, die sich auf einen Wert beziehen, der für ein bestimmtes Feld definiert wurde.

@me-Makro

Das Makro @me ersetzt den in Windows integrierten Kontonamen des Benutzers, der die Abfrage ausführt. Das folgende Beispiel zeigt die Verwendung des Makros und der entsprechenden statischen Anweisung. Das Makro ist für die Verwendung mit Identitätsfeldern wie Assigned To vorgesehen.

WHERE  
   [System.AssignedTo] = @Me

@today-Makro

Sie können das Makro @today mit einem beliebigen DateTime-Feld verwenden. Dieses Makro ersetzt Mitternacht des aktuellen Datums auf dem lokalen Computer, auf dem die Abfrage ausgeführt wird. Sie können auch @today+x oder @today-y mit ganzzahligen Offsets für x Tage nach @today bzw. y Tage vor @today angeben. Eine Abfrage, die das Makro @today verwendet, kann je nach Zeitzone, in der es ausgeführt wird, unterschiedliche Resultsets zurückgeben.

In den folgenden Beispielen wird davon ausgegangen, dass heute der 03.01.2019 ist.

WHERE  
   [System.CreatedDate] = @today

Entspricht Folgendem:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Entspricht Folgendem:

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

Makros @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear

Sie können die @StartOf...-Makros mit einem beliebigen DateTime-Feld verwenden. Dieses Makro ersetzt Mitternacht des aktuellen Tages, des aktuellen Wochenbeginns, des aktuellen Monatsbeginns oder des aktuellen Jahresanfangs auf dem lokalen Computer, auf dem die Abfrage ausgeführt wird.

Hinweis

Erfordert Azure DevOps Server 2019, Update 1 oder höher.

Diese Makros akzeptieren eine Modifiziererzeichenfolge im Format (+/-)nn(y|M|w|d|h|m). Ähnlich wie beim @Today Makro können Sie ganzzahlige Offsets mit Plus- oder Minuszeichen angeben. Wenn der Zeiteinheitsqualifizierer ausgelassen wird, wird standardmäßig der natürliche Zeitraum der Funktion verwendet. @StartOfWeek("+1") entspricht beispielsweise @StartOfWeek("+1w"). Wenn das Plus-/Minuszeichen (+/-) ausgelassen wird, wird Plus angenommen.

Mit dieser Syntax können Sie Modifizierer schachteln und ihre Abfrage zwei Mal versetzen. Die Closed Date >= @StartOfYear - 1-Klausel filtert beispielsweise Arbeitselemente, die seit dem letzten Jahr geschlossen wurden. Durch die Änderung in Closed Date >= @StartOfYear('+3M') - 1 werden Arbeitselemente ausgeschlossen, die innerhalb der ersten drei Monate des letzten Jahres geschlossen wurden. Die WIQL-Syntax wird im folgenden Beispiel gezeigt.

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

In den folgenden Beispielen wird davon ausgegangen, dass heute der 05.04.2019 ist.

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

Entspricht Folgendem:


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

And

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

Entspricht Folgendem:

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

Benutzerdefinierte Makros

WIQL unterstützt auch beliebige benutzerdefinierte Makros. Jede Zeichenfolge mit dem Präfix @ wird als benutzerdefiniertes Makro behandelt und ersetzt. Der Ersetzungswert für das benutzerdefinierte Makro wird aus dem Kontextparameter der Abfragemethode im Objektmodell abgerufen. Die folgende Methode ist die API, die für Makros verwendet wird:

public WorkItemCollection Query(string wiql, IDictionary context)

Der Kontextparameter enthält Schlüssel-Wert-Paare für Makros. Enthält der Kontext beispielsweise ein Schlüssel-Wert-Paar von (project, MyProject), wird @project in der WIQL durch MyProject ersetzt. Mit dieser Ersetzung behandelt der Arbeitselementabfrage-Generator das Makro @project in Visual Studio.

Angeben von Verlaufsabfragen (ASOF)

Sie können eine ASOF-Klausel in einer Abfrage verwenden, um nach Arbeitselementen zu filtern, die die angegebenen Filterbedingungen erfüllen, weil sie an einem bestimmten Datum und zu einer bestimmten Uhrzeit definiert wurden.

Hinweis

ASOF-Abfragen können im Abfrage-Generator von Visual Studio nicht erstellt werden. Wenn Sie eine Abfragedatei (WIQ-Datei) mit einer ASOF-Klausel erstellen und diese anschließend in Visual Studio laden, wird die ASOF-Klausel ignoriert.

Angenommen, ein Arbeitselement wurde vor dem 5.05.2022 unter einem Iterationspfad von Fabrikam Fiber\Release 1 klassifiziert und „Jamal Hartnett“ zugewiesen. Das Arbeitselement wurde jedoch kürzlich „Raisa Pokrovskaya“ zugewiesen und in einen neuen Iterationspfad von Release 2 verschoben. Die folgende Beispielabfrage gibt Arbeitselemente zurück, die Jamal Hartnett zugewiesen sind, da die Abfrage auf einem Arbeitselementzustand basiert, der zu einem vergangenen Datum und einer vergangenen Uhrzeit erfasst wurde.

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'

Hinweis

Wenn keine Uhrzeit angegeben wird, verwendet WIQL Mitternacht. Wenn keine Zeitzone angegeben wird, verwendet WIQL die Zeitzone des lokalen Clientcomputers.

Festlegen der Sortierreihenfolge (ORDER BY)

Sie können die ORDER BY-Klausel verwenden, um die Ergebnisse einer Abfrage nach Feldern in auf- oder absteigender Reihenfolge zu sortieren.

Hinweis

Die Sortiereinstellungen von SQL Server auf der Datenebene bestimmen die Standardsortierreihenfolge. Sie können jedoch die asc oder desc-Parameter verwenden, um eine explizite Sortierreihenfolge auszuwählen.

Im folgenden Beispiel werden Arbeitselemente zuerst nach Priorität in aufsteigender Reihenfolge (Standard) und dann nach Erstellungsdatum in absteigender Reihenfolge (DESC) sortiert.

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

Geben Sie FROM WorkItemLinks an, um Links zwischen Arbeitselementen zurückzugeben. Die Filterbedingungen in der WHERE-Klausel können für die Links oder für jedes Arbeitselement gelten, das die Quelle oder das Ziel eines Links ist. Die folgende Abfrage gibt z. B. die Links zwischen Product Backlog Items und ihren aktiven untergeordneten Elementen zurück.

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)

In der folgenden Tabelle werden die Unterschiede zwischen Arbeitselementabfragen und Abfragen für Links zwischen Arbeitselementen zusammengefasst.

Klausel

Arbeitselemente

Links zwischen Arbeitsaufgaben

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

nicht zutreffend

Geben Sie eine der folgenden Optionen an:

  • MODE (MustContain): (Standard) Gibt nur WorkItemLinkInfo-Datensätze zurück, die sowohl die Quell-, die Ziel- als auch die Linkkriterien erfüllen.
  • MODE (MayContain): Gibt WorkItemLinkInfo-Datensätze für alle Arbeitselemente zurück, die die Quell- und Linkkriterien erfüllen, auch wenn keine der verknüpften Arbeitselemente den Zielkriterien entspricht.
  • MODE (DoesNotContain): Gibt WorkItemLinkInfo-Datensätze für alle Arbeitselemente zurück, die die Quellkriterien erfüllen, jedoch nur, wenn keines der verknüpften Arbeitselemente den Link- oder Zielkriterien entspricht.
  • MODE (Recursive): Wird für Strukturabfragen ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward') verwendet. Der Linktyp muss Strukturtopologie und Vorwärtsrichtung sein. Gibt WorkItemLinkInfo-Datensätze für alle Arbeitselemente rekursiv für das Ziel zurück, die der Quelle genügen. ORDER BY und ASOF sind nicht mit Strukturabfragen kompatibel.

RETURNS

WorkItemQueryResult

WorkItemLink

Sie können einen der folgenden Systemlink-Typnamen angeben.

Sie können einen der unten aufgeführten Systemlink-Typnamen oder einen benutzerdefinierten Linktyp angeben, den Sie mit dem lokalen XML-Prozess definiert haben.

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

Weitere Informationen finden Sie unter Linktypreferenz.

Beispiel für eine Strukturtypabfrage

Die folgende Abfrage gibt alle Arbeitselementtypen zurück, die im aktuellen Projekt definiert sind. Die Abfrage, wie im Abfrage-Editor dargestellt, wird wie in der folgenden Abbildung dargestellt angezeigt.

Screenshot: Abfrage-Editor, Strukturabfrage, alle Arbeitselemente und Status.

Die entsprechende WIQL-Syntax wird unten gezeigt.

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)

Die folgende Abfrage gibt alle Arbeitselementtypen zurück, die im aktuellen Projekt definiert sind. Die Abfrage, wie im Abfrage-Editor dargestellt, wird wie in der folgenden Abbildung dargestellt angezeigt.

Screenshot: Abfrage-Editor, Direktlinkabfrage, alle Arbeitselemente und Status.

Die entsprechende WIQL-Syntax sieht wie gezeigt aus.

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)

Weitere Abfragebeispiele

Im folgenden typischen WIQL-Abfragebeispiel werden Verweisnamen für die Felder verwendet. Die Abfrage wählt Arbeitselemente (kein Arbeitselementtyp angegeben) mit Priority=1 aus. Die Abfrage gibt die ID und den Titel des Rückgabesatzes als Spalten zurück. Die Ergebnisse werden in aufsteigender Reihenfolge nach ID sortiert.

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

Datums-/Uhrzeitmuster

Sie geben das Datums-/Uhrzeitmuster gemäß einem von zwei Mustern an:

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

Beispielklauseln

Die folgenden Beispielanweisungen zeigen bestimmte qualifizierende Klauseln.

Klausel

Beispiel

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

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

Zeichenfolge und Nur-Text

Anführungszeichen-Zeichenfolgenliterale (einfache oder doppelte Anführungszeichen werden unterstützt) in einem Vergleich mit einem Zeichenfolgen- oder Nur-Text-Feld. Zeichenfolgenliterale unterstützen alle Unicode-Zeichen.

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

Sie können den contains-Operator verwenden, um an einer beliebigen Stelle im Feldwert nach einer Teilzeichenfolge zu suchen.

WHERE [System.Description] contains 'WIQL'

Bereich und Iteration (TreePath)

Sie können den UNDER-Operator für die Felder „Bereich“ und „Iterationspfad“ verwenden. Der UNDER-Operator wertet aus, ob sich ein Wert innerhalb der Unterstruktur eines bestimmten Klassifizierungsknotens befindet. Der nachstehende Ausdruck würde beispielsweise in TRUE ausgewertet, wenn der Bereichspfad „MyProject\Server\Administration“, „MyProject\Server\Administration\Feature 1“, „MyProject\Server\Administration\Feature 2\SubFeature 5“ oder ein beliebiger anderer Knoten innerhalb der Teilstruktur lautet.

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

Modifizierer und spezielle Operatoren

Sie können einige Modifizierer und spezielle Operatoren in einem Abfrageausdruck verwenden.

Verwenden Sie den IN-Operator, um auszuwerten, ob ein Feldwert gleich einem Satz von Werten ist. Dieser Operator wird für die Feldtypen String, Integer, Double und DateTime unterstützt. Sehen Sie sich das folgende Beispiel zusammen mit der semantischen Entsprechung an.

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

Der EVER-Operator wird verwendet, um auszuwerten, ob ein Feldwert in allen vergangenen Überarbeitungen von Arbeitselementen gleich einem bestimmten Wert ist oder jemals gleich war. Die Feldtypen String, Integer, Double und DateTime unterstützen diesen Operator. Es gibt alternative Syntaxen für den EVER-Operator. Die folgenden Codeschnipsel fragen beispielsweise ab, ob alle Arbeitselemente jemals Jamal, Raise oder Christie zugewiesen wurden.

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