管理工作專案欄位

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

重要

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

witadmin 命令行工具提供強大的功能來管理專案集合中的工作專案欄位。無論您需要重新命名字段、調整數據類型或設定與識別提供者的同步處理，這些命令都可讓您更精細地控制工作追蹤體驗。

您可以使用 witadmin 欄位命令執行哪些動作

使用下列 witadmin 命令來管理集合中所有工作項目類型和專案的欄位：

changefield：修改套用全集合的欄位屬性，包括：
- 和格式之間的PlainTextHTML
重要

當您升級 Azure DevOps Server 時， [描述 ] 欄位 [System.Description] 會自動從 PlainText 轉換為 HTML。視需要使用 changefield 命令來還原此動作。
- 工作項目查詢中顯示的易記名稱（可能與表單標籤）
- 數據倉儲整合的報告屬性
- 與 entra ID 或 Active Directory Microsoft身分識別同步處理
deletefield：從集合中移除未使用的欄位
listfields：檢視跨專案的欄位屬性和使用方式

提示

若要在內部部署 XML 環境中新增全域欄位，請修改全域工作流程檔案，並將其匯入至您的集合。
witadmin indexfield 命令已被取代。欄位索引會自動進行。

`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 安裝程式範本編輯器。

必要條件

任務	必要權限
列出欄位	檢視集合中項目的專案層級資訊許可權設定為 [允許 ]
刪除或重新命名字段	專案集合系統管理員安全組的成員
變更欄位屬性	專案集合系統管理員安全組的成員

如需詳細資訊，請參閱＜變更專案集合層級權限＞(機器翻譯)。

注意

即使您使用系統管理許可權登入，也必須開啟提升許可權的命令提示字元視窗，才能在執行 Windows Server 的伺服器上執行此函式。若要開啟提升許可權的 [命令提示字元] 視窗，請選擇 [啟動]，開啟 [命令提示字元 ] 快捷方式功能表，然後選擇 [ 以系統管理員身分執行]。

語法

使用下列命令語法模式，透過 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]

參數

參數	說明
`/collection`:`CollectionURL`	指定專案集合的 URI。例如：內部部署格式：`http://ServerName:Port/VirtualDirectoryName/CollectionName` 如果沒有使用虛擬目錄，請使用下列格式： `http://ServerName:Port/CollectionName`。
`/n:RefName` `/n:Name`	工作項目類型欄位的參考名稱。
`/name:NewName`	指定欄位的新名稱。
`/syncnamechanges`	指定使用工作專案欄位來儲存名稱和更新，因為Microsoft Entra ID、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`	在 [命令提示字元] 視窗中顯示命令的說明。

使用 Microsoft Entra ID 和 Active Directory 同步處理人員名稱

設定自訂人員名稱欄位，以在識別提供者中變更使用者名稱時自動更新。

啟用同步處理的時機

僅限自定義欄位：您必須針對用來指派人員名稱的任何自定義工作專案欄位手動啟用同步處理。

系統欄位：所有內建人員名稱欄位都會自動啟用同步處理：

System.AssignedTo
System.ChangedBy
System.CreatedBy

識別提供者支援

環境	識別提供者
Azure DevOps 服務	Microsoft Entra ID
Azure DevOps Server	Active Directory 或工作組

同步處理的運作方式

State	行為
啟用之前	欄位會顯示靜態文字字串
啟用之後	欄位會顯示識別提供者目前的用戶名稱
名稱變更時	具有自動更新的 `syncnamechanges=true` 欄位

組名限制

當您在 [字串] 字段上啟用 syncnamechanges 屬性時，它會接受有效的使用者名稱，但如果適用下列任一條件 ，則不允許組名 ：

VALIDUSER 在所有工作項目類型中指定的規則
VALIDUSER 為特定工作項目類型指定的規則
ALLOWEDVALUES 以 排除群組的篩選準則指定的規則

組態範圍

重要

您必須針對包含自訂欄位的每個專案集合中的每個欄位啟用同步處理。

如需詳細資訊，請參閱：

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

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

工作項目表單上顯示的名稱 。請參閱 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

重新命名字段

您可以變更工作專案欄位的易記名稱，以符合小組所使用的命名慣例。新名稱會套用至參考專案集合中所有專案中已變更欄位的所有工作項目類型。當您在工作項目查詢中定義篩選準則時，會顯示易記名稱。出現在工作項目表單上的名稱可能與為欄位定義的易記名稱不同。

重新命名工作專案欄位

輸入下列命令，將指派給 Microsoft.VSTS.Common.RankImportant Rank 的易記名稱重新命名。

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

在確認提示字元中，輸入，然後選取 y。等到您收到下列訊息：

欄位已重新命名。

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

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

最新的更新會從伺服器下載，其中包括您剛才對功能變數名稱所做的變更。等候數秒，重新整理完成。
選擇 [ 新增查詢 ] 以建立查詢。
在 [查詢編輯器] 中，選擇 [按下這裡新增子句 ] 連結以新增數據列、選取空白 的 Field 單元格，然後在單元格中輸入 Rank。出現在結果清單上方的下列訊息。此訊息表示找不到排名。

執行查詢以查看查詢結果。 TF51005：查詢會參考不存在的欄位。錯誤是由 <\<Rank>>所造成。
從 Field 儲存格中刪除 Rank 值，然後輸入Important Rank儲存格。
在 <> 數據格中選取，然後輸入 1Value 單元格。
在 [查詢] 工具列上，選擇 [執行]。
開啟結果中任何數據列的快捷方式功能表，然後選取 [ 數據行選項]。在 [ 可用的數據行 ] 清單中向下捲動。請注意， [排名 ] 字段已不存在，但 [ 重要排名 ] 字段已存在。
在 [可用的數據行] 方塊中選取 [重要排名]，然後選擇>按鈕（新增選取的數據行）。選擇確定。

請注意，Microsoft.VSTS.Common 的易記名稱。排名會從排名重新命名為整個查詢產生器和結果清單 的重要排名 。
關閉查詢。當系統提示您儲存查詢時，請選擇 [否 ]。
建立新的工作工作專案。選擇 [ 新增工作專案 ] 鏈接，然後選擇 [ 工作]。

此工作專案是從您變更和匯入的工作項目類型建立。
請注意，在 [ 狀態] 方塊中，已重新命名字段 Rank 的標籤並未變更。工作項目表單上的欄位卷標會限定於父專案，且與指定的全伺服器功能變數名稱無關。

注意

如需如何在工作專案窗體上變更欄位卷標的詳細資訊，請參閱控制 XML 元素參考。
關閉新的工作，並在系統提示您儲存工作項目時選擇 [否 ]。

將報表變更為欄位的值

下列命令會指定向維度報告 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

啟用同步處理

若要啟用人員命名字段的同步處理，請輸入下列命令，以取代此處所示自變數的數據：

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

隨即出現下列確認提示：

這會變更 Azure DevOps Server 上欄位 {0} 的屬性。您要繼續嗎？
輸入 0 以確認您想要變更欄位，或 1 取消要求。

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

欄位已更新。

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

刪除欄位

刪除欄位之前，請先確認欄位未使用中。如果欄位正在使用中，您必須先從使用該欄位的工作項目類型中移除該欄位，再將其從專案集合中刪除。下列命令會從 AdventureWorks.Field 刪除欄位：

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

確認欄位未使用中

輸入下列命令，並指定工作專案欄位的參考名稱，例如 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

如果 [ 使用 ] 欄位指出欄位正在使用中，則必須從每個列出的專案的工作項目類型中刪除它。例如， 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 以完成此步驟。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-17