次の方法で共有


FIELD (定義) 要素

FIELD (定義) 要素を使用して、作業項目フィールドを定義し、そのフィールドに適用される規則および条件を指定します。フィールドに割り当てる属性により、作業項目フォームにどのように表示されるか、また、レポートに含めることができるかどうかが決定されます。チーム プロジェクト コレクションのためのフィールド割り当てのセットを管理します。このため、ある種類の作業項目で定義されるフィールドに割り当てる属性は、コレクション内のすべてのチーム プロジェクトにあるすべての種類の作業項目と一致する必要があります。また、すべてのコレクションのレポート可能フィールドはすべて、データ ウェアハウスのデータベースにエクスポートされます。

[!メモ]

状態変更中、またはワークフロー遷移中にフィールドに規則と条件を指定するために使用する FIELD (ワークフロー) 要素の詳細については、「FIELD (ワークフロー) 要素」を参照してください。

witadmin コマンド ツールを使用すると、コレクションのために既存のフィールドに対する属性の割り当てを変更できます。詳細については、「作業項目フィールドの管理 [witadmin]」を参照してください。

スキーマの階層

WITD

   WORKITEMTYPE

      FIELDS

            FIELD

<xs:element name="FIELD" type="FieldDefinition" maxOccurs="unbounded"/>

<FIELD name="fieldDisplayName" refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID" syncnamechanges ="true | false" reportable="Dimension | Detail | Measure" formula="sum" reportingname="ReportingDisplayName" reportingrefname="ReportingReferenceName" >
   <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
   <ALLOWEXISTINGVALUE />
   <CANNOTLOSEVALUE />
   <COPY />
   <DEFAULT />
   <EMPTY />
   <FROZEN />
   <HELPTEXT> . . . </HELPTEXT>
   <MATCH />
   <NOTSAMEAS />
   <PROHIBITEDVALUES /> . . . </PROHIBITEDVALUES>
   <READONLY />
   <REQUIRED />
   <SERVERDEFAULT />
   <SUGGESTEDVALUES /> . . . </SUGGESTEDVALUES>
   <VALIDUSER />
   <WHEN>> . . . </WHEN>
   <WHENNOT> . . . </WHENNOT>
   <WHENCHANGED> . . . </WHENCHANGED>
   <WHENNOTCHANGED> . . . </WHENNOTCHANGED>
</FIELD>

属性および要素

以降のセクションでは、属性、子要素、および親要素について説明します。

属性

属性

説明

name

必須です。作業項目クエリのドロップダウン メニューに表示されるフィールドの表示名。表示名は、チーム プロジェクト内で定義されるすべてのフィールドで一意である必要があります。また、作業項目フォームのフィールドの横に表示されるラベルとは異なる場合があります。詳細については、「Control XML 要素のリファレンス」を参照してください。

属性型は typelib:FieldName です。最小長は 1、最大長は 128 です。

パターン値 : ^[^\\[\]]+$

パターン値の例 : Assigned To

refname

必須です。1 つのフィールドと、チーム プロジェクト コレクションで定義される他のすべてのフィールドを区別する固有のラベル。

表示名および参照名のその他の要件については、「作業項目トラッキング オブジェクトの名前付け規則」を参照してください。

属性型は typelib:ReferenceFieldName です。最小長は 1、最大長は 70 です。

パターン値 : ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

パターン値の例: Company.IssueType

type

必須です。フィールドに設定できるデータの種類を指定します。

メモメモ
別のプロジェクト コレクションのフィールドで、同じ reportingrefname を持つ場合は、 type に同じ値を割り当てる必要があります。値が異なると、データ ウェアハウスが処理された際にデータの競合が発生する可能性があります。詳細については、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

次の表に、この属性の有効な値の一覧を示します。

価値使用方法
DateTime 世界協定時刻 (UTC) に従って日付を指定します。
Double 浮動小数点値を指定します。
GUID 一意の識別子が格納されるフィールドを指定します。
History
ディスカッション スレッドをサポートし、その他の履歴情報を追跡します。
メモメモ
System.History フィールドだけがこのデータ型を使用します。このデータ型を使用して、カスタム フィールドを定義することはできません。
HTML リッチ テキスト データのキャプチャをサポートし、作業項目の説明など、長いテキストの説明に使用されます。
Integer 32 ビットの符号付き整数値を指定します。
PlainText 255 文字以上の Unicode 文字を含む文字列を入力できます。
String 最大 255 文字の Unicode 文字を含む文字列を入力できます。String フィールドは、ラベルや、長さが 1 行以下の短い他のテキスト文字列に使用します。
TreePath
製品の領域パスとイテレーション パスを表示するための要件など、階層構造またはツリー構造でエントリを表示するフィールドを指定します。子ノードを定義するには、区分およびイテレーションの作成および修正を参照してください。
メモメモ
System.AreaPath フィールドと System.IterationPath フィールドだけがこのデータ型を使用します。このデータ型を使用して、カスタム フィールドを定義することはできません。

syncnamechanges

省略可能です。Active Directory またはワークグループでの変更に合わせて、更新する名前を作業項目フィールドを使用して格納するかどうかを指定します。このオプションは、type="String" の場合にのみ有効です。属性型は xs:boolean です。

データ フィールドの同期を有効にする場合は true を指定し、データ フィールドの同期を無効にする場合は false を指定します。

reportable

省略可能です。レポートを含めるのにフィールドのデータが使用できるかどうかを指定します。既定値 None を持つフィールドは、リレーショナル データ ウェアハウスへエクスポートされることもなければ、SQL Server Analysis Services キューブとして処理されることもありません。レポート可能フィールドの詳細については、「作業項目フィールドの追加および修正とレポート作成のサポート」を参照してください。

メモメモ
別のプロジェクト コレクションのフィールドで同じ reportingrefname の値を持つ場合は、reportable に同じ値を割り当てる必要があります。値が異なると、データ ウェアハウスが処理された際にデータの競合が発生する可能性があります。詳細については、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

次の表に、この属性の有効な値の一覧を示します。

Value 使用方法
Detail DateTime、Double、Integer、または String 型のフィールドに指定できます。このフィールドのデータは、リレーショナル ウェアハウス データベースの作業項目テーブルおよび現在の作業項目テーブルに移動されますが、Analysis Services キューブには移動されません。この型は、レポートで使用する際にキューブが巨大になるのを防ぐことができるため、無制限のテキスト フィールドに適しています。
Dimension DateTime、Double、Integer、または String 型のフィールドに指定できます。このフィールドのデータは、リレーショナル ウェアハウス データベースおよび Analysis Services キューブに対し、作業項目ディメンションの属性として入力され、レポートのフィルターに使用できます。この型は、有効値のリストを持つフィールドに対して使用します。Work Item Type および State はディメンションの典型例です。
Measure measure 型は、Integer フィールドと Double フィールドに対してのみ使用します。メジャーは、レポートに含まれる数値です。Analysis Services キューブが処理される際、データは reportable 属性が測定に設定されるフィールドで事前に計算されます。たとえば、作業項目と現在の作業項目のメジャー グループには、最初の見積もり、残存時間数、実績作業時間数のフィールドの累積データが含まれます。measure を指定する場合、formula 属性を指定する必要があります。
None レポートを含めるフィールドを使用しない場合には、None を指定します。これは、既定値の割り当てです。

formula

省略可能です。reportable の種類が measure である場合の集計の種類です。有効な値は sum のみで、セットのすべての値の合計を返します。

reportingname

省略可能です。レポートに表示される名前を指定します。値を指定しない場合は、name 属性に割り当てられた値が使用されます。

メモメモ
別のプロジェクト コレクションのフィールドで同じ reportingrefname を持つ場合は、reportingname に同じ値を割り当てる必要があります。値が異なると、データ ウェアハウスが処理された際にデータの競合が発生する可能性があります。詳細については、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

属性型は typelib:FieldName です。最小長は 1、最大長は 128 です。

パターン値 : ^[^\\[\]]+$

パターン値の例 : Assigned To

reportingrefname

省略可能です。レポート可能フィールドを処理する際に使用する参照名を指定します。値を指定しない場合は、refname 属性に割り当てられた値が使用されます。

この属性を使用して、処理されるフィールドをデータ ウェアハウスに結合または分岐することができます。別の参照名があり、かつ別のプロジェクト コレクションで定義された 2 つのフィールドを結合するには、両方に同じ reportingrefname を割り当てる必要があります。同じ参照名を持っているが別のプロジェクト コレクションで定義されている 2 つのフィールドを分岐するには、各フィールドに別の reportingrefname を割り当てる必要があります。

ウェアハウスのフィールド数を最小化できる場合やレポート可能フィールドの上限を 1024 に維持できる場合は常に、フィールドを結合する必要があります。結合されたフィールドを使用して、複数のグループにわたるレポートを生成することができます。

属性型は typelib:ReferenceFieldName です。最小長は 1、最大長は 70 です。

パターン値 : ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

パターン値の例: Company.IssueType

子要素

要素

説明

ALLOWEDVALUES

省略可能です。フィールドで許可される値のリストを定義します。許可される値は、作業項目フォームのフィールド リストおよびクエリ ビルダーで選択可能な値です。これらの値の 1 つを選択する必要があります。

ALLOWEXISTINGVALUE

省略可能です。既存の値を許可するようにフィールドを定義します。この要素は、既に存在するフィールド値が、たとえ無効値であっても使用できるようにします。新しいフィールド値は有効である必要があります。

CANNOTLOSEVALUE

省略可能です。値を失わないフィールドとして定義します。この要素を指定すると、現在のフィールド値が維持され、クリアすることも、空にすることもできません。

COPY

省略可能です。現在のフィールドに値がコピーされる別のフィールドを指定します。

DEFAULT

省略可能です。フィールドの既定値を定義します。

EMPTY

省略可能です。フィールドを空として定義します。

FROZEN

省略可能です。フィールドを固定として定義します。変更がコミットされた後、固定されたフィールドを空でない値に変更することはできません。ただし、手動でフィールドをクリアし、作業項目を保存して、別の値を指定することはできます。

HELPTEXT

省略可能です。フィールドのツール ヒントに表示されるテキストを定義します。

MATCH

省略可能です。フィールド値が一致する必要があるフィールド パターンを定義します。

NOTSAMEAS

省略可能です。現在のフィールドの値と一致する値を持つことができない別のフィールドを指定します。

PROHIBITEDVALUES

省略可能です。フィールドで禁止される値のリストを定義します。

READONLY

省略可能です。フィールドを読み取り専用として定義します。

REQUIRED

省略可能です。フィールドを必須として定義します。

SERVERDEFAULT

省略可能です。フィールドに値を設定するサーバー コンポーネントを指定します。

SUGGESTEDVALUES

省略可能です。フィールドで推奨される値のリストを定義します。推奨値は、作業項目フォームのフィールド リストおよびクエリ ビルダーで選択可能な値です。リストに含まれていない、他の値を入力することもできます。

VALIDUSER

省略可能です。許容値のリストがシステム内の有効なユーザーのみで構成される必要があることを指定します。

WHEN

省略可能です。別のフィールドが特定の値を持つときに現在のフィールドに適用する 1 つまたは複数の規則を指定します。

WHENCHANGED

省略可能です。特定のフィールドの値が変更されたときに現在のフィールドに適用される 1 つ以上の規則を指定します。

WHENNOT

省略可能です。別のフィールドが特定の値ではないときに現在のフィールドに適用される 1 つ以上の規則を指定します。

WHENNOTCHANGED

省略可能です。特定のフィールドの値が変更されないときに現在のフィールドに適用される 1 つ以上の規則を指定します。

親要素

要素

説明

FIELDS

必須です。作業項目の種類フィールドの定義を含みます。

解説

FIELD (定義) は、FIELDS (定義) の必須の子要素です。

minOccurs="1"

同じチーム プロジェクト コレクション内で 1024 を超える数の作業項目フィールドを定義することはできません。また、すべてのチーム プロジェクト コレクションで 1024 を超える数のフィールドを reportable に設定することもできません。詳細については、「作業項目フィールドの追加および修正とレポート作成のサポート」を参照してください。

[!メモ]

既存のフィールドを別の種類の作業項目に追加するときは、reportable 属性の現在の値が使用されます。

フィールドの表示名および参照名のその他の要件については、「作業項目トラッキング オブジェクトの名前付け規則」を参照してください。レポート用のフィールドにラベルを付ける方法については、「作業項目フィールドの追加および修正とレポート作成のサポート」を参照してください。

System. プレフィックスで始まるカスタム フィールドを定義することはできません。Microsoft. プレフィックスを使用してフィールドを定義することはできますが、この方法は使用しないことを強くお勧めします。Team Foundation Server の機能が阻害される可能性があるためです。

作業項目トラッキング オブジェクトの概要については、「作業項目フィールドの使用」を参照してください。

Microsoft Solutions Framework (MSF) for Agile Software Development v5.0 プロセス テンプレートに対して定義されるすべてのシステム フィールドおよび定義済みフィールドの概要については、「Visual Studio ALM の作業項目フィールド参照」を参照してください。

フィールド参照名は名前変更できません。witadmin コマンド ライン ツールを使用して、フィールドの一覧表示、フィールドの表示名の変更、およびフィールド属性の変更を行うことができます。詳細については、「作業項目フィールドの管理 [witadmin]」を参照してください。

チーム プロジェクト コレクション間でフィールドを使用する方法については、「データ ウェアハウスで発生しているスキーマ競合の解消 」および「 作業項目フィールドの追加および修正とレポート作成のサポート」を参照してください。

使用例

<FIELD name="Activity" refname="Microsoft.VSTS.Common.Activity" type="String" reportable="dimension">
   <HELPTEXT>Type of work involved</HELPTEXT>
   <SUGGESTEDVALUES>
      <LISTITEM value="Development"/>
      <LISTITEM value="Testing"/>
      <LISTITEM value="Requirements"/>
      <LISTITEM value="Design"/>
      <LISTITEM value="Deployment"/>
      <LISTITEM value="Documentation"/>
   </SUGGESTEDVALUES>
</FIELD>

参照

関連項目

作業項目フィールドの管理 [witadmin]

概念

作業項目トラッキング オブジェクトの名前付け規則

Visual Studio ALM の作業項目フィールド参照

プロジェクトの追跡データ、フォーム、ワークフロー、その他のオブジェクトのカスタマイズ

作業項目フィールドの使用

その他の技術情報

作業項目の種類に応じた XML 要素定義に対するインデックス