バグ、タスク、およびその他の作業項目の照会

作業項目のバグ、タスク、他の型、および WorkItemStore.Query のメソッドまたは Query のオブジェクトの1種類を使用して、作業項目間のリンクを照会できます。これらのクエリは、Transact-SQLに似ている作業項目クエリ言語(WIQL)を使用します。

TfsTeamProjectCollection tpc = new TfsTeamProjectCollection(
      new Uri("https://server:8080/tfs/DefaultCollection"));
WorkItemStore workItemStore = (WorkItemStore)tpc.GetService(typeof(WorkItemStore)); 
WorkItemCollection queryResults = workItemStore.Query("
   Select [State], [Title] 
   From WorkItems
   Where [Work Item Type] = 'User Story'
   Order By [State] Asc, [Changed Date] Desc");

Dim collectionUri As Uri
collectionUri = New Uri("https://Server:8080/tfs/DefaultCollection")
Dim tpc As New TfsTeamProjectCollection(collectionUri)
Dim workItemStore As WorkItemStore
workItemStore = tpc.GetService(Of WorkItemStore)()
Dim queryResults As WorkItemCollection
queryResults = workItemStore.Query(“
  Select [State], [Title]
  From WorkItems
  Where [Work Item Type] = ‘User Story’
  Order By [State] Asc, [Changed Date] Desc”)

このトピックの内容

• Query Language

• Where句

  • 比較演算子

  • 変数

  • 文字のValue

• クエリとクエリのオブジェクトのメソッド

• 非同期クエリ

• フィールド値のページング

必要なアクセス許可

クエリは、[作業項目の表示] または [このノードの作業項目を表示します] のアクセス許可がある作業項目のみを返します。通常、これらのアクセス許可は、チーム プロジェクトの [閲覧者] と [共同作成者] のグループのメンバーに付与されます。詳細については、「Team Foundation Server のアクセス許可」を参照してください。

ヒント
作業項目クエリ言語の詳細を調べるには、クエリを チーム エクスプローラーを使用して作成し、.wiqlファイルとして保存します。.xmlの拡張機能を使用するファイルの名前を変更するVisual Studioの開きます。各クエリが作業項目クエリ言語でどのように表現されるかについて wiql の要素を検索します。

Query Language

作業項目クエリ言語に5つがあります。

          Select [State], [Title] 
From WorkItems
Where [Work Item Type] = 'User Story'
Order By [State] Asc, [Changed Date] Desc
AsOf '6/15/2010'

Select [State], [Title]	クエリによって返される値は、WorkItem に設定されている各 Field を識別します。フィールドの表示名や参照の名前を指定できます。名前がnullまたはピリオドが含まれている場合は、角かっこを使用する必要があります ([]) 注意 クエリが値を戻さなくても Fieldの値を取得するには、クエリによって返される WorkItem を使用できます。この場合、サーバーへのラウンド トリップが発生します。詳細については、「フィールド値のページング」を参照してください。
From WorkItems	クエリに作業項目間の作業項目またはリンクを検索するかどうかを示します。 From WorkItems 作業項目の使用。 From WorkItemLinks 作業項目間のリンクの使用。詳細については、「作業項目間のリンクのクエリ」を参照してください。
Where [Work Item Type] = 'User Story'	クエリのフィルター条件を指定します。詳細については、このトピックで後述する「Where句」を参照してください。
Order By [State] Asc, [Changed Date] Desc	(省略可能) クエリが返す WorkItemCollection を並べ替える方法を指定します。
AsOf '6/15/2010'	(省略可能) フィルターが適用される時点または日付を指定することによって履歴クエリを指定します。たとえば、このクエリは、2010年1月6日15 userあるすべてのストーリーを返します。 メモ Visual Studioのクエリ ビルダーAsOfのクエリを作成できません。クエリ ファイルAsOfの句を指定し、読み込むこと (.wiq) をVisual Studioで作成する場合は、AsOfの句は無視されます。

Where句

句が作業項目のクエリのフィルター条件を指定する位置。クエリは、これらの条件を満たす作業項目のみを返します。次の例のクエリでは、アクティブな自分に割り当てられていて、userストーリーを返します。

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

検索条件をグループ化するためにかっこを使用して論理演算子が評価される順序を制御できます。たとえば、割り当てられたバグまたは自分に終了した次の例に示すように、クエリのフィルターを変更する作業項目を返す場合:

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

次の表は、Where句の構文を示しています:

	構文	例
句。	Where FilterCondition [Group|{LogicalOperator FilterCondition}]
グループ	(FilterCondition LogicalOperator FilterCondition [LogicalOperator Filter Condition]…)	([Assigned to] = @Me OR [Created by = @Me]) 論理グループの演算子は AND と ORです。
FilterCondition	Field ComparisonOperator Value	[Work Item Type] = ‘Help Topic’ フィールドの参照名または表示名を指定できます。名前に空白またはピリオドが含まれている場合は、角かっこで囲む必要があります ([])。 比較演算子は、このトピックの 比較演算子 の後半で説明します。 値がの場合、またはリテラル値 (「User」ストーリーの) またはマクロ (@Me) を指定できます。
価値	LiteralValue|Variable|Field	'User Story' リテラル値 フィールドの値と比較する実際の値。詳細については、このトピックで後述する「文字のValue」を参照してください。 変数 特定の値を表す式。たとえば、@Meは、クエリを実行しているユーザーを示します。詳細については、このトピックで後述する「変数」を参照してください。 フィールド 別のフィールドの名前。たとえば、作業項目が最近変更したユーザーに割り当てられている作業項目を検索するに [Assigned to] = [Changed by]を使用できます。

比較演算子

次の表のフィールドに対応する値に関連付ける方法を指定するには、演算子を使用できます:

クエリ演算子	説明	フィールドに適用される型
=	値に一致します。	数値、テキスト、日付、ツリー
<>	値と一致しない。	数値、テキスト、日付、ツリー
>	値より大きい。	数値、テキスト、日付
<	値未満です。	数値、テキスト、日付
>=	値より大きいか等しい。	数値、テキスト、日付
<=	値以下です。	数値、テキスト、日付
次の値を含む	文字列が含まれます。	テキスト
次の値を含まない	文字列が含まれていません。	テキスト
In	コンマで区切られた値と一致する。たとえば、[System.Id] In (100, 101, 102) は、IDが100、101、および102の作業項目を検索します。	数値、テキスト、日付、ツリー
グループ内	グループのメンバーです。グループは、作業項目の種類のフィールド ([Work Item Type] In Group Requirements) とともに使用すると Team Foundation のグループ ([Assigned to] In Group [Project]\Contributors) または作業項目のカテゴリのいずれかです。カテゴリ グループの詳細については、「作業項目の種類のカテゴリをグループ化するカテゴリの定義」を参照してください。	テキスト
グループ外	グループのメンバーではありません。詳細については、In Groupについては、" "を参照してください。	テキスト
次の値と等しかったことがある	別の値に変更しても、フィールドの値と一致すると一致します。	テキスト、日付
次の値の下	区分とイテレーションに、作業項目に子ノードのノードまたはそのいずれかにあるか。区分とイテレーションについては、区分およびイテレーションの作成および修正を参照してください。	ツリー
次の値の下ではない	区分とイテレーションに、作業項目に子ノードのノードまたはそのいずれかに存在します。	ツリー

変数

クエリのuserの入力または計算された値を渡すために変数を使用できます。変数を含むクエリを作成するには、@variableを使用してクエリ文字列のプレースホルダーを作成します。次 IDictionaryの実装を使用してクエリのメソッドに変数の名前と値を渡します。次の例に示すように、

// Define a query that uses a variable for the type of work item. 
string queryString = "Select [State], [Title] From WorkItems Where [Work Item Type] = @Type";

// Set up a dictionary to pass "User Story" as the value of the type variable.
Dictionary<string, string> variables = new Dictionary<string, string>();
variables.Add("Type", "User Story");

// Create and run the query.
Query query = new Query(workItemStore, queryString, variables); 
WorkItemCollection results = query.RunQuery();

// Define a query that uses a variable for the type of work item.
Dim queryString As New StringBuilder("SELECT [State], [Title] FROM WorkItems WHERE [WorkItemtype] = @Type")

// Set up a dictionary to pass "User Story" as the value of a type variable.
Dim variables = New Dictionary(Of String, String)
variables.Add("Type", "User Story")

// Create and run the query.
Dim query As New Query(workItemStore, queryString, variables)                   
WorkItemCollection results = query.RunQuery()

また、クエリでこれらの変数に値を指定せずに @Me か @Today を使用できます。これらの変数は、クエリに表示されますが、IDictionary の実装に渡された関連する値がない場合、変数は、次の表に示すように評価されます:

変数	使用方法
@Me	ユーザー名を含むフィールドの現在のuserを示します。たとえば、[Activated by] = @Meを指定すると、アクティブにした作業項目を検索できます。
@Today	現在の日付を示します。また、日付の加算または減算して @Today の変数を変更できます。たとえば、[Activated Date] > @Today - 7を指定すると前の週にアクティブ化されたすべての項目を検索できます。

文字のValue

各フィールドの値を指定するときは、値がそのフィールドのデータ型と一致する必要があります。Team Foundation のすべてのフィールドには、次の表のデータ型の1つがあります:

データ型	格納されるデータ
DateTime	SQL Serverで定義されている datetime の値。既定では、扱われ、日付の有効桁数を持つと作業項目のクエリの日時の値も。たとえば、に2010年が6年12月1日 [Created Date] = 6/1/2010日のフィルター条件にときに作成される作業項目一致します。 詳細については、Microsoft Webサイトのトピックと クエリとクエリのオブジェクトのメソッド の次のページを参照します: datetime (Transact-SQL)。
Double (倍精度浮動小数点型)	0.2、3.5 などの実数。
GUID	GUIDを表す文字列。
HTML	HTMLを含む文字列。
整数	0、1、2、34 などの符号付き 32 ビット整数。
PlainText	255文字よりも長い書式指定されていない文字列。
String	最大255文字を含む文字列。
TreePath	区分またはイテレーションのような分岐ツリー構造。

作業項目間のリンクのクエリ

また、作業項目間のリンクを検索するには、クエリを使用できます。句は、リンクまたはリンクのリンク元またはリンク先である作業項目に適用される場合の条件。次の表に、これらの種類のクエリと作業項目に対してのみがクエリの違いを示しています:

	作業項目	作業項目間のリンク
FROM句	から、WorkItems	からWorkItemLinks
句。	[FieldName] = Value	次のいずれかになります。 [Source].[FieldName] = Value [Target].[FieldName] = Value [System.Links.LinkType] = 'LinkName'
モード		次のいずれかになります。 mode(MustContain) (既定値) ソース、ターゲット、およびリンクの条件がすべて満たされている WorkItemLinkInfo のレコードのみを返します。 mode(MayContain) リンクされた作業項目がターゲットの基準を満たさなく場合でも、ソースおよびリンクの条件を満たすすべての作業項目の WorkItemLinkInfo のレコードを返します。 mode(DoesNotContain) ソースを満たすすべての作業項目の WorkItemLinkInfo のレコードを返しますが、リンクされた作業項目をリンクとターゲットの基準を満たしている が。
戻り値	[ T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemCollection ]	WorkItemLinkInfo の配列。

次のクエリでは、userストーリーとアクティブな子ノードとリンクを返します。

SELECT [System.Id]
FROM WorkItemLinks
WHERE ([Source].[System.WorkItemType] = 'User Story')
  And ([System.Links.LinkType] = 'Child')
  And ([Target].[System.State] = 'Active')
mode(MustContain)

クエリとクエリのオブジェクトのメソッド

作業項目に WorkItemStore.Query のメソッドを使用します。また WorkItemStore.QueryCount のメソッドを使用して、すべての作業項目を返さないでクエリを満たす作業項目の数を指定できます。

クエリを定義し、実行するに Query のオブジェクトを作成できます。

string queryString = "Select [Title] From WorkItems Where [Work Item Type] = 'User Story'"
Query query = new Query(workItemStore, queryString); 
int numWorkItems = query.RunCountQuery();
Console.WriteLine("The project collection has " + numWorkItems.ToString() + " user stories.");

Dim queryString As New StringBuilder("Select [Title] FROM WorkItems WHERE [WorkItemType] = 'User Story'"
Dim query As New Query(workItemStore, queryString)
Dim numWorkItems As Int
numWorkItems = query.RunCountQuery()
Console.Writeline("The project collection has " + numWorkItems.ToString() + " user stories.")

非同期クエリ

Query.BeginQuery のメソッドを使用してクエリを非同期的に実行できます。次の例は、クエリを非同期的に実行し、非常に短いタイムアウト期間の後でクエリをキャンセルします。

// Run the query asynchronously, and time out after 0.05 seconds. 
ICancelableAsyncResult callback = query.BeginQuery();
callback.AsyncWaitHandle.WaitOne(50, false); 
if (!callback.IsCompleted) 
{
   callback.Cancel();
   Console.WriteLine("The query timed out");
}
else
{
   WorkItemCollection nextResults = query.EndQuery(callback); 
   Console.WriteLine("The project collection has " + nextResults.Count.ToString() + " work items."); 
}

Dim callback as ICancelableAsyncResult
callback = query.RunQuery()
callback.AsyncAWaitHandle.WaitOne(50, False)
If Not (callback.IsCompleted)
Then
callback.Cancel()
Console.Writeline("The query timed out")
Else
Dim nextResults As WorkItemCollection = query.EndQuery(callback)
Console.Writeline("The project collection has " + nextResults.Count.ToString() + " work items.") 
End If

フィールド値のページング

クエリが返す WorkItemCollection は、次のフィールドの値が含まれます:

• ID

• Rev. (変更)

• AreaID

• IterationID

• WorkItemType

SELECT、句で指定するフィールドの値は、ページで返されます。

[!メモ]

既定では、各ページが50の作業項目に対して選択したフィールドがあります。WorkItemCollection.PageSizeを使用してページのサイズを調整できます。

サーバーにコードで使用するすべてのフィールドのオプションでラウンド トリップを最小限に抑えることができます。次のコードは、クエリの1種類のラウンド トリップの新しいページがアクセスするたびにページのタイトルを返すために1でラウンド トリップを作成します。

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

作成したコードが、が選択句で指定されていないフィールドにアクセスし、そのフィールドがページをページング フィールド セットに追加されます。別のラウンド トリップがそのフィールドの値を含むようにそのページを更新するように実行されます。

クエリの構文 (EBNF)

拡張Backus-Naur form (EBNF)は、.NET Compact、異なる方法で言語の引数を表すメタ言語です。このコード ブロックは、作業項目クエリ言語(WIQL)の引数の説明にEBNFを使用します。

EBNFの詳細については、Syntax for the Work Item Query LanguageのWIQLの代替説明を参照してください。

<select> ::= <flat-select> | <one-hop-select> | <recursive-select>

<flat-select> ::= select <field list>
from workitems
[ where <expression> ]
[ order by <order by field list> ]
[ asof <datetime> ]

<one-hop-select> ::= select <field list>
from workitemlinks
[ where <one-hop-link-expression>  <source-expression>  <target-expression> ]
[ order by <source-target order by field list> ]
[ asof <datetime> ]
mode( mustcontain | maycontain | doesnotcontain )

<recursive-select> ::= select <field list>
from workitemlinks
where <recursive-link-expression> [ and <source-expression> <target-expression> ]
mode ( recursive | returnmatchingchildren )

<expression> ::= <expression4>

<expression4> ::= <expression3> [ or <expression4> ]
<expression3> ::= <expression2> [ and <expression3> ]

<expression2> ::=   {[ not | ever ] <expression2> }
                          | <expression1>

<expression1> ::= <conditional expression>

<conditional expression> ::=   { '(' <expression> ')' }  | <field reference name> <conditional operator> <value>  | <field reference name> [not] in '(' <value list> ')'

<value> ::= <number>
| <string>
| <datetime>

<value list> ::= <value> [ ',' <value list> ]

<conditional operator> ::=   { '=' | '<>' | '<' | '<=' | '>' | '>=' } 
                             | { [ever] [not] { like | under }} 
<link operator> ::= '=' | '<>'

<field list> ::= <field name> [ ',' <field list> ]
<order by field list> ::= <order by field> [ ',' <order by field list> ]
<source-target order by field list> ::= [ <source> |<target> ] <order by field> [ ',' <source-target order by field list> ]
<order by field> ::= <field name> [ 'asc' | 'desc' ]

<number> ::= [ '-' ] <digit>* [ '.' [ <digit>* ]] [ { e | E } [ '-' ] <digit>* ]

<string> ::=   { ''' { <anychar except '''> | '''' }* ''' } 
                 | { '"' { <anychar except '"'> | '""' }* '"' }

<datetime> ::= <string>

<source> ::= '[source].'
<target> ::= '[target].'

<one-hop-link-expression> ::= <one-hop-link-expression4> | ''

<one-hop-link-expression4> ::= <one-hop-link-expression3> [ or <one-hop-link-expression4> ]
<one-hop-link-expression3> ::= <one-hop-link-expression2> [ and <one-hop-link-expression3> ]

<one-hop-link-expression2> ::= {[ not | ever ] <one-hop-link-expression2>}
                         | <one-hop-link-expression1>

<one-hop-link-expression1> ::= <conditional-link-expression>

<conditional-link-expression> ::= { '(' <one-hop-link-expression> ')' } | <linktype-field> <link operator> <linktype-name><linktype-direction> | <linktype-field> [not] 'in  (' <linktype list> ')'

<recursive-link-expression> ::= <linktype-field> '=' <linktype-name>'-forward'

<linktype list> ::= <linktype-name><linktype-direction> [, <linktype-name><linktype-direction>]

<linktype-direction> ::= '-forward' | '-reverse'

<source-expression> ::= <source-expression4> | ''

<source-expression4> ::= <source-expression3> [ or <source-expression4> ]
<source-expression3> ::= <source-expression2> [ and <source-expression3> ]

<source-expression2> ::=   {[ not | ever ] <source-expression2> }
                          | <source-expression1>

<source-expression1> ::= <conditional-source-expression>

<conditional-source-expression> ::=   { '(' <source-expression> ')' }  | <source><field reference name> <conditional operator> <value>  | <source><field reference name> [not] in '(' <value list> ')'

<target-expression> ::= <target-expression4> | ''

<target-expression4> ::= <target-expression3> [ or <target-expression4> ]
<target-expression3> ::= <target-expression2> [ and <target-expression3> ]

<target-expression2> ::=   {[ not | ever ] <target-expression2> }
                          | <target-expression1>

<target-expression1> ::= <conditional-target-expression>

<conditional-target-expression> ::=   { '(' <target-expression> ')' }  | <target><field reference name> <conditional operator> <value>  | <target><field reference name> [not] in '(' <value list> ')'

<linktype-field> ::= '[System.Links.LinkType] = '
<select> ::= select <field list>
from workitems
[ where <expression> ]
[ order by <order by field list> ]
[ asof <datetime> ]

<expression> ::= <expression4>

<expression4> ::= <expression3> [ or <expression4> ]
<expression3> ::= <expression2> [ and <expression3> ]

<expression2> ::=   {[ not | ever ] <expression2> }
                          | <expression1>

<expression1> ::= <conditional expression>

<conditional expression> ::=   { '(' <expression> ')' }  | <field reference name> <conditional operator> <value>  | <field reference name> [not] in '(' <value list> ')'

<value> ::= <number>
| <string>
| <datetime>

<value list> ::= <value> [ ',' <value list> ]

<conditional operator> ::=   { '=' | '<>' | '<' | '<=' | '>' | '>=' } 
                             | { [ever] [not] { like | under }} 

<field list> ::= <field name> [ ',' <field list> ]
<order by field list> ::= <field name> [ asc | desc ] [ ',' <order by field list> ]

<number> ::= [ '-' ] <digit>* [ '.' [ <digit>* ]] [ { e | E } [ '-' ] <digit>* ]

<string> ::=   { ''' { <anychar except '''> | '''' }* ''' } 
                 | { '"' { <anychar except '"'> | '""' }* '"' }

<datetime> ::= <string> Insert section body here.

参照

概念

Team Foundation のクライアント オブジェクト モデルを使用した作業項目トラッキングの拡張