管理工作專案欄位

  • 發行項

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

重要

針對內部部署 XML 進程模型，您可以使用 witadmin 來列出、匯入、匯出和修改項目的進程。 針對繼承和託管的 XML 進程模型，您只能使用 witadmin 來列出和匯出進程資訊。 如需程式模型的概觀和支持專案，請參閱 自定義您的工作追蹤體驗。

您可以使用下列 witadmin 命令來管理針對專案集合 （內部部署 XML） 定義之工作項目類型所定義的欄位。 如果您想要新增全域欄位（適用於內部部署 XML 有效），您可以修改 全域工作流程檔案 並將其 匯入集合來執行此動作。

  • changefield：變更欄位的一或多個屬性。 當您變更下列其中一個屬性時，您可以針對專案集合內的所有工作專案類型和專案進行變更：

    • 或 HTML 欄位的PlainText數據類型。

      重要

      當您將 Team Foundation Server 從舊版升級至目前版本時，[描述] 欄位的類型指派會自動從 PlainTextHTML轉換為 。 changefield使用 命令，您可以還原此欄位的內容以顯示純文字。

    • 工作項目查詢中顯示的易記名稱 。 此名稱可能與工作項目表單上顯示的名稱不同。

    • 報表屬性 ，其中包含在報表中出現的功能變數名稱、參考報表名稱和報告類型。

    • 與 Active Directory 同步 處理 - 您可以啟用/停用人員名稱欄位的同步處理。

  • deletefield：刪除指定的欄位。
  • listfields：列出所有欄位或指定欄位的屬性。

注意

命令 witadmin indexfield 已被 Azure DevOps Server 2019 和更新版本取代。 不再需要索引欄位。

witadmin執行命令行工具

若要執行 witadmin 命令行工具，請開啟已安裝 Visual Studio 的命令提示字元視窗。 witadmin命令行工具會安裝任何版本的 Visual Studio。 您可以安裝免費的 Visual Studio Community 或 Visual Studio Team Explorer 版本來存取此工具。

注意

若要連線到 Azure DevOps Services，建議您使用最新版的 Visual Studio 或 Visual Studio Community。

注意

若要連線到內部部署伺服器，建議您使用與 Azure DevOps Server 相同的或更新版本的 Visual Studio。 例如，如果您連線到 Azure DevOps Server 2019，請從 Visual Studio 2019 版本連線到您的專案。

針對 Visual Studio 2022

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

或或 ProfessionalEnterprise 取代 Community，視您安裝的版本而定。

針對 Visual Studio 2019

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

或或 ProfessionalEnterprise 取代 Community，視您安裝的版本而定。

針對 Visual Studio 2017

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

或或 TeamExplorerProfessional 取代 Enterprise，視您安裝的版本而定。

在 32 位版本的 Windows 上，將 %programfiles（x86）% 取代為 %programfiles%。 您可以 安裝 Visual Studio Community （提供 Team Explorer 的存取權）或 Visual Studio Team Explorer 2017 免費。

如需默認進程範本內定義的欄位概觀，請參閱 工作專案欄位索引。

提示

使用 witadmin，您可以 匯入和導出定義檔。 您可以使用的其他工具包括行程編輯器（需要您已安裝 Visual Studio 版本）。 從 Visual Studio Marketplace 安裝程式範本編輯器。

必要條件

  • 若要列出欄位，您必須擁有集合集合中專案 [允許] 的 [檢視專案層級資訊] 許可權。
  • 若要刪除或重新命名字段或變更字段的屬性，您必須是Team Foundation 管理員 istrators 安全組或 Project Collection 管理員 istrators 安全組的成員。

如需詳細資訊，請參閱 變更專案集合層級許可權。

注意

即使您使用系統管理許可權登入，也必須開啟提升許可權的命令提示字元視窗，在執行 Windows Server 2008 的伺服器上執行此函式。 若要開啟提升許可權的 [命令提示字元] 視窗，請選擇 [啟動]，開啟 [命令提示字元] 快捷方式功能表，然後選擇 [以 管理員 istrator 執行]。 如需詳細資訊，請參閱 Microsoft 網站：使用者 存取控制。

語法

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]

參數

參數 說明
/collection:CollectionURL 指定專案集合的 URI。 例如：

內部部署格式：http://ServerName:Port/VirtualDirectoryName/CollectionName
如果沒有使用虛擬目錄，請使用下列格式： http://ServerName:Port/CollectionName。
/n:RefName
/n:Name		 工作項目類型欄位的參考名稱。
/index 指定啟用或停用指定欄位的索引編制。 指定 on 以啟用索引編製和 關閉 以停用索引編製。
/name:NewName 指定欄位的新名稱。
/syncnamechanges 指定使用工作專案欄位來儲存名稱和更新，因為 Active Directory 或工作組中所做的變更。 只有在為 typename指定 String 資料類型的欄位時，此選項才有效。

指定 true 以啟用資料欄位的同步處理，請指定 false 以停用數據欄位的同步處理。
/reportingname:ReportingName 指定要用於報告之數據倉儲中的功能變數名稱。
/reportingrefname:ReportingRefName 指定要用於報告之數據倉儲中欄位的參考名稱。
/reportingtype:Type 指定欄位在倉儲中用於報告的方式。 下列是有效值：

- dimension: 用於 Integer、String 或 DateTime 欄位。
- detail: 用於 Integer、Double、String 或 DateTime 字段。
- measure: 用於 [整數] 和 [雙精度浮點數] 欄位。 默認匯總類型為 sum。 您可以使用公式參數來指定另一個匯總類型。
- none: 用來停用欄位的可報告性。

如需詳細資訊，請參閱 關於工作專案欄位和屬性。
/reportingformula:Formula 指定當欄位回報為 measure時要使用的匯總公式。 唯一支援的公式是 sum。
/type:HTML | PlainText 指定將欄位的內容從 PlainText 轉換為 HTML 或從 HTML 轉換為 PlainText。 您只能針對類型指派為 PlainText 或 HTML的欄位指定此選項。 請參閱 FIELD （定義） 元素參考。
/unused 列出專案集合中任何專案未使用的所有欄位。
/noprompt 停用確認的提示。
/? 或 help 在 [命令提示字元] 視窗中顯示命令的說明。

將人員名稱與 Active Directory 同步

您必須手動啟用任何自定義工作專案欄位的同步處理，這些欄位是用來指派參考 Active Directory 的人員名稱。 您必須針對包含自訂欄位的每個專案集合啟用每個欄位的同步處理。

顯示人員名稱的所有系統參考欄位都會將 屬性 syncnamechanges 設定為 true。 這類欄位包括 System.AuthorizedAs、System.AssignedTo、System.ChangedBy 和 System.CreatedBy。 針對其中一個預設進程範本中定義的每個人員名稱欄位啟用同步處理。 如需詳細資訊，請參閱 工作分派和工作流程欄位。

啟用同步處理之後，欄位就不會再顯示靜態字串。 相反地，欄位會顯示與用戶帳戶相關聯的名稱。 當您在 Active Directory 或 Workgroup 中變更使用者名稱時，設定 syncnamechanges 為 true 的欄位會自動顯示新名稱。

當您將 syncnamechanges 屬性指派給 String 欄位時，欄位一律會接受有效的使用者名稱。 不過，如果下列任一條件為 true，字段不允許儲存在 Team Foundation Server 或 Active Directory 中的組名：

  • 規則 VALIDUSER 會跨所有工作項目類型指定

  • 為 VALIDUSER 工作項目類型指定規則

  • 規則 ALLOWEDVALUES 是針對工作項目類型指定，而該規則具有排除群組的篩選準則

    如需詳細資訊，請參閱 所有 FIELD 元素。

您可以針對每個工作項目類型變更的屬性

您可以變更欄位出現的工作項目類型定義，以變更欄位定義的下列屬性或值：

範例

除非另有指定，否則每個範例中都會套用下列值：

  • 專案集合的 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.RankImportant Rank 的易記名稱重新命名。

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

  2. 在確認提示字元輸入 y ，然後按 ENTER。 等到您收到下列訊息：

    欄位已重新命名。

確認已匯入至單一項目的變更

  1. 在 [Team Explorer] 中，選擇 [Refresh重新整理]。

    最新的更新會從伺服器下載，其中包括您剛才對功能變數名稱所做的變更。 等候數秒，重新整理完成。

  2. 選擇 [ 新增查詢 ] 以建立查詢。

  3. 在 查詢編輯器 中，選擇 [按兩下這裡新增子句] 連結以新增數據列、選取空白的 Field 單元格，然後在單元格中輸入 Rank。 出現在結果清單上方的下列訊息。 此訊息表示找不到 Rank。

    執行查詢以查看查詢結果。 TF51005：查詢會參考不存在的欄位。 錯誤是由 <<Rank>> 所造成。

  4. 從 Field 單元格刪除 Rank 值，並在數據格中輸入 Important Rank。

  5. 在 [運算子] 儲存格中選取 <> ，然後在 [值] 資料格中輸入 1。

  6. 在 [查詢] 工具列上，選擇 [執行查詢執行]。

  7. 開啟結果中任何數據列的快捷方式功能表，然後選取 [ 數據行選項]。 在 [ 可用的數據行 ] 清單中向下捲動。 請注意， [排名 ] 字段已不存在，但 [ 重要排名 ] 字段已存在。

  8. 在 [可用的數據行] 方塊中選取 [重要排名]，然後選擇>按鈕（新增選取的數據行）。 選擇確定。

    請注意，Microsoft.VSTS.Common.Rank 的易記名稱已從 排名 重新命名為 重要排名 ，整個查詢產生器和結果清單。

  9. 關閉查詢。 當系統提示您儲存查詢時，請選擇 [否 ]。

  10. 建立新的工作工作專案。 選擇 [ 新增工作專案 ] 鏈接，然後選擇 [ 工作]。

    此工作專案是從您變更和匯入的工作項目類型建立。

  11. 請注意，在 [ 狀態] 方塊中，已重新命名字段 的標籤 Rank 尚未變更。 這是因為工作項目表單上的欄位卷標的範圍是父專案，而且與剛才指定的全伺服器域名無關。

    注意

    如需如何在工作專案窗體上變更欄位卷標的詳細資訊，請參閱 控制 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。

確認您要轉換之欄位的數據類型

  1. 輸入下列命令，確認指派給字段的數據類型，例如 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. 隨即出現下列確認提示：

    這會變更Team Foundation Server 上欄位 {0} 的屬性。 您要繼續嗎？

  3. 輸入 0 以確認您想要變更欄位，或 1 以取消要求。

    如果變更要求成功，會出現下列確認訊息：

    欄位已更新。

    如果變更要求失敗，會出現錯誤訊息。 最常見的錯誤是嘗試變更系統參考字段，或嘗試變更 String 以外的數據類型欄位。 不支援這些作業。

刪除欄位

刪除欄位之前，請確認欄位未使用中。 如果欄位正在使用中，您必須先從工作項目類型中移除該欄位，再從專案集合中刪除該欄位。 下列命令會從 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

    在欄位顯示的資訊中，確認 [使用] 的值為 「未使用中」，如下列範例所示。

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

  2. 如果 [ 使用 ] 欄位指出欄位正在使用中，則必須從每個列出的專案的工作項目類型中刪除它。 例如， Microsoft.VSTS.TCM.SystemInfo 欄位表示它正由 Bug 和程式代碼瑕疵工作專案類型用於四個專案：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 （定義） 元素參考和 控件。

從專案集合中刪除欄位

輸入下列命令來刪除 MyCompany.MyProcess.MyField 欄位，然後選擇 Enter。

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

在確認提示字元輸入 y 以完成此步驟。