選択リストの定義

[アーティクル]
08/09/2011

更新 : 2011 年 1 月

フィールドの定義の一部としてまたはワークフローのある時点で選択リストを定義することで、フィールドの一連の値を列挙できます。リストに許可値のみを含めたり禁止値を含めないようにしたりするように指定できます。または、値を推奨するように指定できます。値を推奨すると、ユーザーは選択リストの値以外の値を指定できます。

フィールドに 2 つ以上のリストを定義し、実行時に条件付き規則の評価に基づいて 1 つのリストだけを表示する、依存選択リストを定義することもできます。

このトピックの内容

選択リストを列挙する場合の構文構造
GLOBALLIST 要素と LISTITEM 要素の構文構造
既存の値の許可
一連の許可値の列挙
依存選択リストの定義

選択リストを列挙する場合の構文構造

ALLOWEDVALUES、SUGGESTEDVALUES、および PROHIBITEDVALUES の各要素を使用して、フィールドの値としてユーザーが指定する必要のある値、指定できる値、または指定できない値のリストを指定します。これらの各要素を使用すると、項目のリストを列挙したり、グローバルリストを指定したりできます。 ALLOWEXISTINGVALUE を使用すると、選択リストから項目を削除した場合に、フィールドに既存の値を格納できます。

これらの要素は、FIELD (定義) 要素または FIELD (ワークフロー) 要素の子要素として指定できます。

ユーザーが作業項目フォームまたはクエリエディターで指定できる値のリストを定義するには、ALLOWEDVALUES を使用します。ユーザーは、GLOBALLIST または一連の LISTITEM エントリにある値の 1 つを選択する必要があります。
```
<ALLOWEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">
   <GLOBALLIST name="globalListName" />
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</ALLOWEDVALUES>
```
フィールドに指定できない値のリストを定義するには、PROHIBITEDVALUES を使用します。フィールドに禁止値が設定されている場合は、ユーザーは作業項目を保存できません。この要素は、以前は許可されていたが有効でなくなった値の使用を制限するときに使用します。
```
<PROHIBITEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">
   <GLOBALLIST name="globalListName" />
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</PROHIBITEDVALUES>
```

フィールドに指定できる値のリストを定義するには、SUGGESTEDVALUES を使用します。ユーザーは、推奨値以外の値を指定することもできます。

<SUGGESTEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">
   <GLOBALLIST name="globalListName" />
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</SUGGESTEDVALUES>

これらの各要素の場合、次の表に示す 1 つ以上の属性を指定できます。

属性	説明
for	省略可能。この規則を適用する Team Foundation のユーザーまたはグループの名前を指定します。有効な名前は、1 ～ 255 文字のテキスト文字列で構成されます。パターン値: ^[^\\]+\\[^\\]+$ パターン値の例: Domain\UserID
not	省略可能。この規則を適用しない Team Foundation のユーザーまたはグループの名前を指定します。有効な名前は、1 ～ 255 文字のテキスト文字列で構成されます。パターン値: ^[^\\]+\\[^\\]+$ パターン値の例: Domain\UserID
expanditems	省略可能。 LISTITEM 要素で指定されたグループを拡張してリスト内の下位グループも含めるかどうかを指定します。既定値は true です。
filteritems	省略可能。グループのメンバーだけをリストに含め、グループ名を含めないことを指定します。この属性の有効な値は excludegroups のみです。

詳細については、「リスト、選択リスト、およびグローバルリストの定義と使用」を参照してください。

ページのトップへ

GLOBALLIST 要素と LISTITEM 要素の構文構造

GLOBALLIST 要素および LISTITEM 要素を使用すると、グローバルに更新できる項目または 1 つのフィールドに固有の項目のリストを列挙できます。

チームプロジェクトコレクション用に格納され、そのコレクションのすべてのチームプロジェクトで使用できる一連の LISTITEM 要素を定義するには、GLOBALLIST を使用します。 GLOBALLIST は、GLOBALLISTS 要素の必須の子要素であり、ALLOWEDVALUES 要素、SUGGESTEDVALUES 要素、および PROHIBITEDVALUES 要素の省略可能な子要素です。グローバルリストは、作業項目の定義、グローバルリストの定義、またはグローバルワークフロー内で定義できます。
```
<GLOBALLIST name="globalListName">
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</GLOBALLIST> 
```
globalListName: 1 ～ 255 文字で構成されたテキスト文字列です。

重要

作業項目の種類を定義する XML ファイルにグローバルリストを定義する場合は、リストに一意の名前を付ける必要があります。そうしないと、コレクションに定義されている既存のリストが上書きされる可能性があります。
一連の値を列挙するには、LISTITEM を使用します。 LISTITEM は、GLOBALLIST 要素の必須の子要素であり、ALLOWEDVALUES 要素、SUGGESTEDVALUES 要素、および PROHIBITEDVALUES 要素の省略可能な子要素です。
```
<LISTITEM value="listName" />
```
listName: 1 ～ 255 文字で構成されたテキスト文字列です。

ページのトップへ

既存の値の許可

ALLOWEDVALUES 要素を使用して項目の選択リストを指定した後で、ALLOWEXISTINGVALUE 要素を使用して、フィールドで既存の値を保持できるようにします。 ALLOWEXISTINGVALUE 要素を指定しない場合は、編集時にユーザーがそのフィールドに現在有効な値の 1 つを指定するように設定します。 ALLOWEXISTINGVALUE 要素は、同じブロック内の要素のみを変更します。

<ALLOWEXISTINGVALUE />

FIELD (ワークフロー) 要素の下でこの要素を指定すると、フィールドに定義された規則がこの要素に適用されます。このアプリケーションには、フィールドの STATE、TRANSITION、DEFAULTREASON、および REASON の各要素で指定される規則も含まれます。 STATE 要素の下でこの要素を指定すると、フィールドの状態に関して定義された規則がこの要素に適用されるだけでなく、その状態へのすべての遷移に関してフィールドに定義された規則も適用されます。

TRANSITION 要素の下でこの要素を指定すると、フィールドの遷移に関して定義された規則がこの要素に適用されるだけでなく、REASON 要素および DEFAULTREASON 要素内のフィールドに関して定義された規則も適用されます。

ページのトップへ

リストの列挙

フィールドリストは、個々のリスト項目で構成されています。各フィールドリストには、少なくとも 1 つの項目が含まれている必要があります。

注意

グローバルリストのスコープはプロジェクトではないため、グローバルリストにはプロジェクトをスコープとするグループは指定しないでください。

フィールドリスト内の項目を指定するには、<LISTITEM value=""> 要素を使用します。文字列、ユーザー名、またはグループ名を指定できます。

<LISTITEM value="Emergency"/>
<LISTITEM value="Major"/>
<LISTITEM value="Minor"/>
<LISTITEM value="Domain\joe"/>
<LISTITEM value="[Global]\GlobalGroup" />
<LISTITEM value="[Project]\ProjectGroup" />

注意

実行時に、リスト内の項目は、Visual Studio Team Foundation Server を実行しているサーバーの言語に基づいてアルファベット順に表示されます。

ページのトップへ

一連の許可値の列挙

この例では、Customer Severity フィールドは、Emergency、Major、および Minor の 3 つの値のいずれかを持つことができます。このフィールドは必須として定義されており、既定値は Minor です。実行時に、ドロップダウンリストのいずれか 1 つの値をユーザーが指定できます。

<FIELD refname="System.Title" name="Title" type="String">
<HELPTEXT>Provide a brief description of the work item</HELPTEXT>
<REQUIRED/>
</FIELD>
<FIELD refname="MyCorp.CusSeverity" name="Customer Severity" type="String">
<HELPTEXT>Indicate the severity of the problem</HELPTEXT>
    <ALLOWEDVALUES>
        <LISTITEM value="Emergency">
        <LISTITEM value="Major">
        <LISTITEM value="Minor">
    </ALLOWEDVALUES>
<DEFAULT from="value" value="Minor"/>
</FIELD>

ページのトップへ

依存選択リストの定義

親条件句が true の場合にのみアクティブになる選択リストを定義できます。次の例では、My Field に 2 セットの選択リストが定義されています。実行時に、Requirements が MyCompany.MyTeam.Discipline フィールドに割り当てられているかどうかに基づいて、どちらか一方のリストだけが表示されます。

注意

この例の WHEN 規則および WHENNOT 規則を他の規則に適用すると、どのような場合にそれらの規則を評価するのかを指定できます。詳細については、「条件付き値および条件付き規則の割り当て」を参照してください。

<FIELD name="My Field" refname="MyCompany.MyProcess.MyField" type="String" reportable="dimension">
  <WHEN field="MyCompany.MyTeam.Discipline" value="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Planning" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHEN>
  <WHENNOT field=" MyCompany.MyTeam.Discipline" value="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Process Management" />
      <LISTITEM value="Planning" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHENNOT>
</FIELD>

ページのトップへ