Macros (Work Item Query Reference)

The Work Item Query Language (WIQL) supports several built-in macros. Use these macros to substitute dynamic values into expressions.

Macros

The @me macro substitutes the Windows Integrated account name of the user who runs the query. The example below shows how to use the macro and the equivalent static statement. Although the macro is intended for fields such as Assigned To, you can use it for any String field, although the result may not be meaningful.

[System.AssignedTo] = @Me
[System.AssignedTo] = 'joselugo'

You can use the @today macro with any DateTime field. When used, it substitutes midnight of the current date on the local computer that runs the query. Users can also specify @today+x or @today-y using integer offsets for x days after @today and y days before @today, respectively. Note that a query that uses the @today macro can return different result sets depending on the time zone in which it is run. The example below assumes that today is 1/3/06.

[System.CreatedDate] = @today

is the equivalent of:

[System.CreatedDate] = '1/3/06'

and

[System.CreatedDate] > @today-2

is the equivalent of:

[System.CreatedDate] > '1/1/06'

WIQL also supports arbitrary custom macros. Any string prefixed by an '@' is treated as a custom macro and will be substituted. The substitute value for the custom macro is retrieved from the context parameter of the query method in the object model. The following method is the API used for macros: 

public WorkItemCollection Query(string wiql, IDictionary context)

The context parameter contains key-value pairs for macros. For example, if the context contains a key-value pair of (project, MyProject), then '@project' will be replaced by 'MyProject' in the WIQL. This is how the work item query builder handles the @project macro in Visual Studio.

See Also

Other Resources

Syntax for the Work Item Query Language