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

witadmin コマンドを使用すると、チーム プロジェクト コレクションに定義されている作業項目の種類フィールドを管理できます。

• changefield: フィールドの 1 つ以上の属性を変更します。 次の属性のいずれかを変更すると、チーム プロジェクト コレクション内のすべての作業項目の種類とチーム プロジェクトに対して、その属性が変更されます。

  • フィールドまたは PlainText フィールドのHTMLデータ型。

    重要

    旧バージョンから現在のバージョンに Team Foundation Server をアップグレードする場合、[説明] (System.Description) フィールドに対する型の割り当ては PlainText から HTML に自動的に変換されます。changefield コマンドを使用すると、このフィールドの内容を復元してテキスト形式で表示できます。

  • 作業項目クエリに表示される表示名。 この名前は、作業項目フォームでの表示と異なる場合があります。

  • レポート、参照レポート名、レポートの種類に表示されるフィールドの名前を含むレポート属性。

  • Active Directory との同期 - 人名フィールドの同期を有効または無効にできます。

• deletefield: 指定したフィールドを削除します。

• indexfield: 指定したフィールドのインデックス作成をオンまたはオフにします。 フィールドのインデックス作成を有効にすると、クエリでそのフィールドを指定する作業項目を検索するパフォーマンスが向上することがあります。 作業項目クエリの多くで使用するカスタム フィールドを追加した場合、そのフィールドのインデックス作成を有効にすることをお勧めします。

• listfields: すべてのフィールドまたは指定したフィールドの属性の一覧を表示します。

witadmin コマンド ライン ツールは、オンプレミスの TFS に対して実行される場合にのみ機能します。 このツールを実行するには、Visual Studio またはチーム エクスプローラーがインストールされている環境でコマンド プロンプト ウィンドウを開き、次のように入力します。

cd %programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE

32 ビット版の Windows で、%programfiles(x86)% を %programfiles% に置き換えます。

既定のプロセス テンプレート内で定義されているフィールドの概要については、「Visual Studio ALM の作業項目フィールド参照」を参照してください。

注意

作業項目フィールドは、Visual Studio のパワー ツールであるプロセス エディターを使用して作成および変更できます。このツールはサポートされていません。詳細については、Microsoft Web サイトのページ「Team Foundation Server パワー ツール」を参照してください。

必要条件

• フィールドを一覧表示するには、コレクション内のチーム プロジェクトの [プロジェクトレベル情報を表示します] のアクセス許可が [許可] に設定されている必要があります。

• フィールドの削除や名前変更、またはフィールドの属性の変更を行うには、Team Foundation 管理者セキュリティ グループまたはプロジェクト コレクション管理者セキュリティ グループのメンバーである必要があります。

詳細については、「Team Foundation Server のアクセス許可の参照」を参照してください。

注意

管理者のアクセス許可を使ってログオンしている場合でも、Windows Server 2008 を実行中のサーバーでこの機能を実行するには、昇格した特権でコマンド プロンプト ウィンドウを開く必要があります。昇格した特権でコマンド プロンプト ウィンドウを開くには、[スタート] ボタンをクリックし、[コマンド プロンプト] ショートカット メニューを開いて、[管理者として実行] をクリックします。詳細については、Microsoft Web サイトの「ユーザー アカウント制御」を参照してください。

witadmin changefield /collection:CollectionURL /n:RefName
   [/name:NewName] 
   [/syncnamechanges:true | false]
   [/reportingname:ReportingName] 
   [/reportingrefname:ReportingRefName]
   [/reportingtype:Type]
   [/reportingformula:Formula]
   [/type:PlainText | HTML]
   [/noprompt]

witadmin deletefield /collection:CollectionURL /n:RefName [/noprompt]

witadmin indexfield /collection:CollectionURL /n:Name /index:on|off 

witadmin listfields /collection:CollectionURL /n:RefName [/unused]

パラメーター

パラメーター	説明
/collection:CollectionURL	チーム プロジェクト コレクションの URI を指定します。 URI の形式は http://ServerName:Port/VirtualDirectoryName/CollectionName です。 仮想ディレクトリを使用していない場合、URI の形式は次のようになります。 http://ServerName:Port/CollectionName
/n:RefName /n:Name	作業項目の種類フィールドの参照名です。
/index	指定したフィールドのインデックス作成を有効または無効にすることを指定します。 インデックス作成を有効にするには on を指定し、無効にするには off を指定します。
/name: NewName	フィールドの新しい名前を指定します。
/syncnamechanges	作業項目フィールドを使用して名前を格納し、Active Directory またはワークグループでの変更に合わせて更新することを指定します。 このオプションは、データ型が String のフィールドを typename に指定した場合にのみ有効です。 データ フィールドの同期を有効にする場合は true を指定し、データ フィールドの同期を無効にする場合は false を指定します。
/reportingname:ReportingName	レポートに使用するデータ ウェアハウス内のフィールドの名前を指定します。
/reportingrefname:ReportingRefName	レポートに使用するデータ ウェアハウス内のフィールドの参照名を指定します。
/reportingtype: Type	フィールドがウェアハウスでどのようにレポートに使用されるかを指定します。 有効な値は、次のとおりです。 dimension: Integer、String、または DateTime の各フィールドに使用されます。 detail: Integer、Double、String、または DateTime の各フィールドに使用されます。 measure: Integer および Double の各フィールドに使用されます。 既定の集計の種類は sum です。 formula パラメーターを使用すると、別の集計の種類を指定できます。 none: フィールドのレポート可能性を無効にするために使用されます。 詳細については、「作業項目フィールドの定義と変更」を参照してください。
/reportingformula: Formula	フィールドを measure としてレポートするときに使用する集計の式を指定します。 サポートされている式は sum のみです。
/type: HTML | PlainText	PlainText から HTML へ、または HTML から PlainText へのフィールド内容の変換を指定します。 型の割り当てが PlainText または HTML であるフィールドに対してのみ、このオプションを指定できます。 「FIELD (定義) 要素リファレンス」を参照してください。
/unused	チーム プロジェクト コレクションで定義されているどのチーム プロジェクトによっても使用されないすべてのフィールドを一覧表示します。
/noprompt	確認のプロンプトを無効にします。
/? or help	コマンド プロンプト ウィンドウにコマンドのヘルプを表示します。

解説

インデックス付きフィールド

クエリ インデックスは、インデックスの作成が有効なフィールドに基づいて作成されます。 このインデックスにより、インデックス付きフィールドが含まれるクエリを実行したときの応答時間が短縮されます。

既定では、"担当者"、"作成日"、"変更者"、"状態"、"理由"、"区分 ID"、"イテレーション ID"、"作業項目の種類" の各フィールドにインデックスが付けられます。 チームがクエリで頻繁に使用するフィールドが他にある場合、それをクエリ インデックスに追加できます。

Active Directory との人名の同期

Active Directory を参照する人名の割り当てに使用されているカスタムの作業項目フィールドの同期は、手動で有効にする必要があります。 カスタム フィールドを含んでいるチーム プロジェクト コレクションごとに、各フィールドの同期を有効にする必要があります。

人名を表すすべてのシステム参照フィールドは、属性 syncnamechanges が true に設定されます。 このようなフィールドには、System.AuthorizedAs、System.AssignedTo、System.ChangedBy、System.CreatedBy などがあります。  同期は、いずれかの既定のプロセス テンプレートで定義されている各ユーザー名フィールドで有効になります。 詳細については、「割り当ておよびワークフローのフィールド参照」を参照してください。

同期を有効にすると、フィールドは静的文字列ではなくなります。 代わりに、フィールドにはユーザー アカウントに関連付けられた名前が表示されます。 Active Directory またはワークグループ内のユーザー名を変更すると、syncnamechanges が true に設定されたフィールドにも、新しい名前が自動的に表示されます。

syncnamechanges 属性を String フィールドに割り当てると、そのフィールドは有効なユーザー名を常に受け付けます。 ただし、次のいずれかの条件が Team Foundation Server の場合、フィールドは true または Active Directory に格納されているグループ名を受け付けません。

• すべての作業項目の種類に対して VALIDUSER 規則が指定されている

• 個別の作業項目の種類に対して VALIDUSER 規則が指定されている

• 作業項目の種類に対して ALLOWEDVALUES 規則が指定されており、その規則にグループを除外するフィルター条件が含まれている

詳細については、「すべての FIELD XML 要素のリファレンス」を参照してください。

作業項目の種類ごとに変更できる属性

フィールドに対して定義されている次の属性または値を変更するには、フィールドが表示されている作業項目の種類の定義を変更します。

• 作業項目フォームに表示される名前。 「Control XML 要素のリファレンス」を参照してください。

• ヘルプ テキスト。 「作業項目フィールドへの規則の適用」を参照してください。

• 選択リストまたはドロップダウン メニュー内の許可値または項目。 「選択リストの定義」を参照してください。

使用例

特に指定されていない場合、それぞれの例に適用される値は次のとおりです。

• チーム プロジェクト コレクションの URI: http://AdventureWorksServer:8080/tfs/DefaultCollection

• 作業項目フィールド名: AdventureWorks.Field

• 既定のエンコーディング: UTF-8

リスト フィールド

witadmin listfields を使用して、使用中のフィールド セットを表示し、作業項目の種類に追加するものを選択します。 さらに、特定のフィールドに定義された属性の割り当てを一覧表示して、どのチーム プロジェクトによりどのフィールドが使用されているかを調べることができます。

作業項目フィールドの属性の表示

• Microsoft.VSTS.Common.Issue など、指定したフィールドに対して定義されている属性を一覧表示するには、次のコマンドを入力します。

  witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Issue
  

  次に示すように、指定したフィールドのフィールドおよび属性情報が表示されます。

  Field: Microsoft.VSTS.Common.Issue
  Name: Issue
  Type: String
  Reportable As: dimension
  Use: Adventure Works (Shared Steps), AW Future (Shared Steps), AW Current (Shared Steps)
  Indexed: False
  

  Use パラメーターは、各プロジェクトの名前と、フィールドが使用されている作業項目の種類を示しています。 フィールド属性の詳細については、「Visual Studio ALM の作業項目フィールド参照」を参照してください。

チーム プロジェクト コレクションのすべてのフィールドの一覧表示

• チーム プロジェクト コレクションに対して定義されているすべてのフィールドを一覧表示するには、次のコマンドを入力します。

  witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection
  

  指定したプロジェクト コレクションのすべてのフィールドのフィールド情報が表示されます。 「Visual Studio ALM の作業項目フィールド参照」を参照してください。

使用されていないフィールドの一覧表示

• どの作業項目の種類からもチーム プロジェクト コレクションで使用されていないフィールドを一覧表示するには、次のコマンドを入力します。

  witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /unused
  

  次に示すように、使用されていない各フィールドのフィールド情報および属性情報が表示されます。

  Field: Microsoft.VSTS.CMMI.TaskType
  Name: Task Type
  Type: String
  Reportable As: dimension
  Use: Not In Use
  Indexed: False
  
  Field: Microsoft.VSTSUE.Common.Flag
  Name: Flag
  Type: String
  Reportable As: dimension
  Use: Not In Use
  Indexed: False
  
  Field: Microsoft.VSTSUE.Common.Progress
  Name: Progress
  Type: String
  Reportable As: dimension
  Use: Not In Use
  Indexed: False
  

フィールド名の変更

作業項目フィールドの表示名は、チームが使用する名前付け規則に合わせて変更できます。 新しい名前は、プロジェクト コレクション内のすべてのチーム プロジェクトの変更されたフィールドを参照する、すべての作業項目の種類に適用されます。 表示名は、作業項目クエリでフィルター条件を定義するときに表示されます。 作業項目フォームに表示される名前は、フィールドに定義される表示名とは異なる場合があります。

作業項目フィールドの名前を変更するには

1. Microsoft.VSTS.Common.Rank に割り当てられている表示名を Important Rank に変更するには、次のコマンドを入力します。

   witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Rank /name:"Important Rank"
   

2. 確認プロンプトで「y」と入力し、Enter キーを押します。 次のメッセージが表示されるまで待ちます。

   Field renamed.

1 つのプロジェクトにインポートされた変更を検証するには

1. チーム エクスプローラーで、 ([最新の情報に更新]) を選択します。

   先ほどフィールド名に加えた変更を含む、最新の更新情報がサーバーからダウンロードされます。 更新が完了するまで数秒待ちます。

2. [新しいクエリ] を選択してクエリを作成します。

3. クエリ エディターで [句を追加するにはここをクリックします] というリンクを選択して新しい行を追加し、空白の [フィールド] セルを選択して「Rank」と入力します。 結果リストの上に次のメッセージが表示されます。 このメッセージは、Rank が見つからないことを示しています。

   **結果を表示するには、クエリを実行します。**TF51005: クエリは、存在しないフィールドを参照しています。 エラーの原因は、<<Rank>> であると考えられます。

4. [フィールド] セルから値 Rank を削除し、このセルに「Important Rank」と入力します。

5. [演算子] セルの [<>] を選択して、[値] セルに 1 を入力します。

6. [クエリ] ツール バーの ([実行]) を選択します。

7. 結果の任意の行のショートカット メニューを開き、[列のオプション] を選択します。 [使用可能な列] 一覧でスクロール ダウンします。 Rank フィールドはなくなっていますが、Important Rank フィールドは存在しています。

8. [使用可能な列] ボックスの [Important Rank] を選択し、[>] ボタン ([選択された列を追加する]) を選択します。 [OK] をクリックします。

   クエリ ビルダーと結果リスト全体にわたって、Microsoft.VSTS.Common.Rank の表示名が、Rank から Important Rank に変更されています。

9. クエリを閉じます。 クエリを保存するかどうかを確認するメッセージが表示されたら、[いいえ] を選択します。

10. 新しいタスク作業項目を作成します。 [新しい作業項目] リンクを選択し、[タスク] を選択します。

    この作業項目は、変更してインポートした作業項目の種類から作成されます。

11. [状態] ボックスでは、名前を変更した Rank フィールドのラベルが変更されていないことに注意してください。 これは、作業項目フォームのフィールド ラベルは、親チーム プロジェクトにスコープが設定されており、先ほど指定したサーバー全体のフィールド名から独立しているためです。

    注意

    作業項目フォームのフィールド ラベルを変更する方法の詳細については、「Control XML 要素のリファレンス」を参照してください。

12. 新しいタスクを閉じ、作業項目を保存するかどうかを確認するメッセージが表示されたら、[いいえ] を選択します。

フィールドのレポートされる値の種類の変更

次のコマンドは、DateTime フィールドである AdventureWorks.CreatedOn の種類をレポートする機能を dimension に指定します。 このフィールドのデータは、レポートのフィルター処理に使用できるように、ウェアハウス データベースおよび Analysis Services データベースに格納されます。

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.CreatedOn /reportingtype:dimension

次のコマンドは、Double フィールドである AdventureWorks.Field の種類をレポートする機能を measure に指定します。 すべての measure は sum によって集約されます。

witadmin reportfield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field /reportingtype:measure

カスタム人名フィールドの同期の有効化

次のコマンドは、AdventureWorksServer 上の Collection1 に定義されている作業項目フィールド AW.CustomerName の同期を有効にします。

変換するフィールドのデータ型の確認

• 次のコマンドを入力して、同期する MyCompany.CustomerName などのフィールドに割り当てられているデータ型を確認します。

  witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName
  

同期の有効化

1. 人名フィールドの同期を有効にするには、次のコマンドを入力します。ただし、引数には独自のデータを使用してください。

   witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName /syncnamechanges:true
   

2. 次のような確認プロンプトが表示されます。

   This will change properties for field {0} on the Team Foundation Server. Do you want to continue?

3. フィールドを変更することを確認するには「0」を入力し、この要求を取り消すには「1」を入力します。

   変更要求が成功した場合は、次の確認メッセージが表示されます。

   The field was updated.

   変更要求が失敗した場合は、エラー メッセージが表示されます。 最もよくある間違いは、システム参照フィールドを変更しようとしたり、文字列以外のデータ型のフィールドを変更しようとしたりすることです。 このような操作はサポートされていません。

フィールドの削除

フィールドを削除する前に、フィールドが使用されていないことを確認します。 フィールドが使用中である場合、チーム プロジェクト コレクションから削除する前に、そのフィールドを使用している作業項目の種類からフィールドを削除する必要があります。 次のコマンドは、Collection1 からフィールド AdventureWorks.Field を削除します。

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field

フィールドが使用中でないことの確認

1. MyCompany.MyProcess.MyField などの作業項目フィールドの参照名を指定したうえで、次のコマンドを入力します。

   witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.MyProcess.MyField
   

   フィールドごとに表示される情報で、次の例で示すように Use の値が "Not In Use" になっていることを検証します。

   Field: MyCompany.MyProcess.MyField
   Name: MyField
   Type: String
   Reportable As: dimension
   Use: Not In Use
   Indexed: False
   

2. Use フィールドで、そのフィールドが使用中であると示された場合は、一覧表示されている各チーム プロジェクトの各作業項目の種類から、そのフィールドを削除する必要があります。 たとえば、Microsoft.VSTS.TCM.SystemInfo フィールドは、Arroyo、Desert、Palm および Springs という 4 つのプロジェクトで、Bug および Code Defect という作業項目の種類によって使用されています。

   Field: Microsoft.VSTS.TCM.SystemInfo
   Name: System Info
   Type: Html
   Reportable As: None
   Use: Arroyo (Bug), Desert (Bug), Palm (Bug), Springs (Bug, Code Defect)
   Indexed: False
   

   このフィールドを削除する前に、このフィールドが定義されている各チーム プロジェクトについて一覧表示されている作業項目の種類から、フィールドを削除する必要があります。 フィールドを削除するには、フィールドの参照名を含む FIELD 要素と Control 要素を削除して、作業項目の種類の定義を変更します。 「作業項目の種類のインポート、エクスポート、および管理 [witadmin]」、「FIELD (定義) 要素リファレンス」、および「Control XML 要素のリファレンス」を参照してください。

チーム プロジェクト コレクションからのフィールドの削除

• MyCompany.MyProcess.MyField フィールドを削除するには、次のコマンドを入力して Enter キーを押します。

  witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:RefName
  

  確認プロンプトで「y」と入力して、この手順を完了します。

Q & A

Q: どのようなカスタマイズが可能ですか。 また、TFS のアップグレード後も機能の構成ウィザードを使用してチーム プロジェクトを更新できますか。

A: カスタム フィールドを追加したり、選択リストをカスタマイズしたり、フィールドにルールを追加したりできます。 機能の構成ウィザードは、チーム プロジェクトを更新し、最新機能へのアクセスを可能にします。

フィールド属性の変更はお勧めできません。 安全なカスタマイズおよび避けるべきカスタマイズの詳細については、「作業追跡エクスペリエンスのカスタマイズ: カスタマイズの前に、メンテナンスおよびアップグレードの影響について理解する」を参照してください。

参照

概念

データ ウェアハウスで発生しているスキーマ競合の解消

レポート作成をサポートするための作業項目フィールドの追加および変更

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

Visual Studio ALM のレポート可能フィールド参照

その他の技術情報

witAdmin: 作業を追跡するためのオブジェクトのカスタマイズおよび管理