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

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

witadmin コマンドライン ツールは、プロジェクト コレクション内の作業項目フィールドを管理するための強力な機能を提供します。 これらのコマンドを使用すると、フィールドの名前の変更、データ型の調整、ID プロバイダーとの同期の構成を行う必要がある場合でも、作業の追跡エクスペリエンスをきめ細かく制御できます。

witadmin フィールド コマンドでできること

次の witadmin コマンドを使用して、コレクション内のすべての作業項目の種類とプロジェクトのフィールドを管理します。

• changefield: コレクション全体を適用するフィールド属性を変更します。次を含みます。
  • 形式とPlainText形式間のHTML

  重要

  Azure DevOps Server をアップグレードすると、[ 説明 ] フィールド (System.Description) が自動的に PlainText から HTMLに変換されます。 必要に応じて、 changefield コマンドを使用して元に戻します。

  • 作業項目クエリに表示されるフレンドリ名 (フォーム ラベルとは異なる場合があります)
  • データ ウェアハウス統合のレポート属性
  • Microsoft Entra ID または Active Directory との ID 同期
• deletefield: コレクションから未使用のフィールドを削除します
• listfields: プロジェクト全体のフィールド属性と使用状況を表示する

witadmin コマンド ライン ツールを実行する

witadminコマンド ライン ツールを実行するには、Visual Studio がインストールされているコマンド プロンプト ウィンドウを開きます。 witadmin コマンドライン ツールは、任意のバージョンの Visual Studio と共にインストールされます。 このツールにアクセスするには、 Visual Studio Community または Visual Studio チーム エクスプローラーの無料バージョンをインストールします。

Visual Studio 2022 の場合

%programfiles(x86)%\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

インストールしたバージョンに応じて、Professionalの代わりにEnterpriseまたはCommunity。

Visual Studio 2019 の場合

%programfiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

インストールしたバージョンに応じて、Professionalの代わりにEnterpriseまたはCommunity。

Visual Studio 2017 の場合

%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

インストールしたバージョンに応じて、TeamExplorerの代わりにProfessionalまたはEnterprise。

32 ビット 版の Windows では、 %programfiles(x86)% を %programfiles% に置き換えます。 Visual Studio Community (チーム エクスプローラーへのアクセスを提供する) または Visual Studio Team Explorer 2017 を無料でインストールできます。

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

前提条件

詳細については、「 プロジェクト コレクション レベルのアクセス許可を変更する」を参照してください。

構文

witadmin ツールを使用して作業項目フィールドを管理するには、次のコマンド構文パターンを使用します。

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 listfields /collection:CollectionURL /n:RefName [/unused]  

パラメーター

ユーザー名と Microsoft Entra ID と Active Directory の同期

ID プロバイダーでユーザー名が変更されたときに自動的に更新されるように、ユーザー名フィールドを構成します。

同期を有効にするタイミング

ユーザー設定フィールドのみ: ユーザー名の割り当てに使用するカスタム作業項目フィールドの同期を手動で有効にする必要があります。

システム フィールド: すべての組み込みユーザー名フィールドで同期が自動的に有効になります。

• System.AssignedTo
• System.ChangedBy
• System.CreatedBy

ID プロバイダーのサポート

同期のしくみ

グループ名の制限

文字列フィールドで syncnamechanges 属性を有効にすると、有効なユーザー名を受け入れますが、次のいずれかの条件が適用される場合、 グループ名は許可されません 。

• すべての作業項目の種類に対して指定されたルールをVALIDUSERする
• 特定VALIDUSER作業項目の種類に対して指定された規則
• グループALLOWEDVALUES除外するフィルター条件で指定されたルール

構成スコープ

詳細については、以下を参照してください。

• 割り当てフィールドとワークフロー フィールド
• すべての FIELD 要素。

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

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

• 作業項目フォームに表示される名前 。 WebLayout 要素と Control 要素または Control XML 要素リファレンスを参照してください。
• ヘルプ テキスト。 ルールとルールの評価を参照してください。
• 指定できる値 または選択リストまたはドロップダウン メニュー内の項目。 ALLOWEDVALUES、SUGGESTEDVALUES、および PROHIBITEDVALUES 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 パラメーターは、各プロジェクトの名前と、フィールドが使用されている作業項目の種類を示します。 フィールド属性の詳細については、「 作業項目フィールドのインデックスを参照してください。

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

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

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

名前付きプロジェクト コレクションのすべてのフィールドのフィールド情報が表示されます。 「 作業項目フィールドのインデックスを参照してください。

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

次のコマンドを入力して、プロジェクト コレクションで使用されなくなったフィールドを作業項目の種類別に一覧表示します。

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 キーを 押します。 次のメッセージが表示されるまで待ちます。

   フィールドの名前が変更された。

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

1. チーム エクスプローラーで、 Refresh を選択します。

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

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

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

   クエリを実行して、クエリの結果を表示します。 TF51005: クエリは存在しないフィールドを参照します。 エラーは <\<Rank>>が原因で発生します。

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

5. [<>] セルでを選択し、[値] セルに「1」と入力します。

6. Query ツール バーで、Run を選択します。

7. 結果内の任意の行のショートカット メニューを開き、 Column オプションを選択します。 Available 列一覧内を下にスクロールします。 Rank フィールドが存在しなくなったが、Important Rank フィールドが存在していることに注意してください。

8. [Available columns] ボックスで [Important Rank を選択し、> ボタン (選択した列を追加) を選択します。 OK を選択します。

   Microsoft.VSTS.Common のフレンドリ名に注意してください。 ランクは、クエリ ビルダーと結果リスト全体で Rank から Important Rank に名前が変更されます。

9. クエリを閉じます。 クエリを保存するように求められたら、[ いいえ ] を選択します。

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

    この作業項目は、変更およびインポートした作業項目タイプから作成されます。

11. [状態] ボックスで、名前が変更されたフィールド Rank のラベルが変更されなかったことに注意してください。 作業項目フォームのフィールド ラベルは親プロジェクトにスコープが設定され、指定されたサーバー全体のフィールド名に依存しません。

    Note

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

12. 作業項目を保存するように求められたら、新しいタスクを閉じ、[ いいえ ] を選択します。

フィールドの値としてレポートを変更する

次のコマンドは、DateTime フィールド AdventureWorks.CreatedOn の種類をディメンションに報告する機能を指定します。 このフィールドのデータは、レポートのフィルター処理に使用できるように、倉庫データベースと Analysis Services データベースに入ります。

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

次のコマンドは、測定する Double フィールド AdventureWorks.Field の種類を報告する機能を指定します。 すべてのメジャーは合計で集計されます。

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

ユーザー設定のユーザー名フィールドの同期を有効にする

次のコマンドは、作業項目フィールド AW の同期を有効にします。AdventureWorksServer の Collection1 に対して定義された 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. 次の確認プロンプトが表示されます。

   これにより、Azure DevOps Server のフィールド {0} のプロパティが変更されます。 Do you want to continue? (続行してもよろしいですか?)

3. 0を入力してフィールドを変更することを確認するか、要求を取り消1。

   変更要求が成功すると、次の確認メッセージが表示されます。

   フィールドが更新されました。

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

フィールドの削除

フィールドを削除する前に、フィールドが使用されていないことを確認します。 フィールドが使用中の場合は、プロジェクト コレクションからフィールドを削除する前に、フィールドを使用する作業項目の種類からフィールドを削除する必要があります。 次のコマンドは、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 の値が "使用されていません" であることを確認します。

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

2. Use フィールドが使用されていることを示す場合は、一覧に表示されている各プロジェクトの作業項目の種類ごとに削除する必要があります。 たとえば、[ Microsoft.VSTS.TCM.SystemInfo ] フィールドは、4 つのプロジェクト (Arroyo、Desert、Palm、Springs) のバグとコードディフェクトの作業項目の種類で使用されていることを示します。

   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 要素を削除して、作業項目の種類の定義を変更します。 作業項目の種類のインポート、エクスポート、管理、FIELD (定義) 要素のリファレンス、および Control を参照してください。

プロジェクト コレクションからフィールドを削除する

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

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

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

関連記事

• 作業追跡エクスペリエンスのカスタマイズ
• 作業項目フィールドのインデックス
• witAdmin: 作業を追跡するためのオブジェクトのカスタマイズおよび管理