列出工作專案欄位和屬性

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

工作專案欄位會追蹤 Azure DevOps 內的資訊。系統會在組織層級定義這些欄位，並在組織中的所有專案之間共用這些欄位。若要檢閱為組織定義的欄位，您可以使用下列兩個工具之一，同時適用於繼承和託管的 XML 進程模型：

處理 > 欄位網頁
工作項目欄位探索器

工作專案欄位會追蹤 Azure DevOps 內的資訊。系統會在集合層級定義這些欄位，並在該集合內的所有專案之間共用這些欄位。若要檢閱您集合所定義的欄位，請使用下列其中一個工具：

進程 > 欄位網頁：適用於繼承的進程模型。
工作專案欄位總管：適用於繼承和 內部部署 XML 進程模型。

如需使用系統程式所定義之每個欄位的描述，請參閱工作專案欄位索引。

為什麼工作專案欄位很重要

工作專案欄位可在 Azure DevOps 中提供數個重要函式：

資料追蹤：擷取並儲存有關工作專案的基本資訊
查詢功能：啟用強大的搜尋和過濾功能
報告：支持分析和儀表板創建
工作流程管理：驅動狀態轉換和業務規則
整合：與外部工具和系統連接

瞭解欄位屬性可協助您：

優化查詢：選擇正確的字段以實現高效搜索
計劃定制：了解限制和可能性
疑難排解問題：診斷欄位運作上遇到的問題
設計程式：建立有效的工作專案類型和工作流程

Prerequisites

Category	Requirements
Permissions	若要檢視組織或集合定義的欄位：專案集合有效使用者的成員應用程式群組或檢視實例層級資訊許可權設定為 [允許組織或集合]。

清單或檢視欄位

若要列出或檢閱欄位，請根據您的進程模型使用下列其中一個工具：繼承的、託管的 XML 或內部部署 XML。如需默認進程內定義的欄位索引，請參閱工作專案欄位索引。

Tool	Inheritance	託管 XML	內部部署 XML
入口網站：列出繼承和自定義定義的欄位	✔️	✔️1
工作項目欄位瀏覽器	✔️	✔️	✔️
witadmin listfields 命令行工具	✔️	✔️	✔️

Note

僅支援默認進程（Agile、CMMI、Scrum）。

欄位數據類型和名稱

每個工作項目類型都會指定該類型工作專案中包含的欄位。每個欄位都有多個屬性，其中許多屬性都是系統定義且不可變的。

三個關鍵屬性定義欄位：

資料類型：指出您可以在欄位中輸入的資料類型，例如布林值、雙精度、整數、HTML 或字串。如需每個數據類型的詳細描述，請參閱查詢欄位、運算元和巨集。
易記名稱：指派給字段的用戶易記名稱，用於在查詢子句中選取 Field 時使用。此名稱可能與工作項目表單上顯示的名稱不同。
參考名稱：建立 WIQL 查詢、工作專案範本、執行 REST API 命令或定義 XML 工作專案類型定義時所使用的識別碼。參考名稱是永久的，一旦設定就無法變更。

如需每個欄位屬性的詳細描述，以及如何列出它們，請參閱本文稍後的欄位屬性和清單欄位屬性。如需了解工作項目類型和工作項目的概觀，請參閱以使用者故事、問題、缺陷、功能及史詩進行追蹤。

什麼是領域？欄位名稱如何運作？

每個工作項目類型都包含 31 個系統欄位和數個特定類型欄位。工作項目可協助您規劃及追蹤專案。

每個欄位都會擷取要執行之工作的特定資訊。您指派給這些欄位的值會儲存在工作追蹤資料存放區中，讓您建立可判斷狀態和趨勢的查詢。

如需針對核心系統程式所定義之每個欄位的描述和使用方式，請參閱工作專案欄位索引：Agile、Basic、Scrum 和 CMMI 。

欄位命名需求

工作專案欄位名稱可唯一識別每個工作專案欄位。請確定您的功能變數名稱遵守下列指導方針：

唯一性：功能變數名稱在帳戶或專案集合內必須是唯一的。
長度：域名必須包含128個Unicode字元或更少。
間距：功能變數名稱不能有前置或尾端空格，或包含兩個或多個連續空格。
字段組成：字段名稱必須至少包含一個字母字符。
禁止的字元：欄位名稱不能包含下列字元：.,;':~/*|？&%$！+=（）[]{}<>`。

由於系統在組織或集合層級定義自訂欄位，因此您無法將具有相同名稱的自訂欄位新增至多個流程。

如需詳細資訊，請參閱命名限制和慣例。

系統與預先定義的欄位

系統會定義具有特定命名和結構需求的工作專案欄位，以確保一致性和功能：

唯一性：功能變數名稱在帳戶或專案集合內必須是唯一的。
長度：域名必須是128個Unicode字元或更少。
間距：欄位名稱不能有前置或尾端空格，也不能包含多個連續空格。
字段組成：字段名稱必須至少包含一個字母字符。
禁止的字元：欄位名稱不能包含下列字元：.,;':~/*|？&%$！+=（）[]{}<>`。

由於系統在組織或集合層級定義自訂欄位，因此您無法將具有相同名稱的自訂欄位新增至多個流程。

如需詳細資訊，請參閱命名限制和慣例。

自訂欄位

由於系統會在組織或專案集合層級定義自訂欄位，因此您無法將具有相同名稱的自訂欄位新增至多個程式。

新增自訂欄位時，請注意下列限制：

每個工作項目類型的最大欄位（WIT）： 64
每個進程的欄位上限： 512

欄位資料類型決定了您可以儲存在欄位中的資料類型和大小。每個欄位在專案集合內只能定義一個類型，鼓勵跨不同專案和工作項目類型使用通用欄位。

當您將自訂欄位新增至繼承的製程時，Azure DevOps 會指派一個參考名稱，前面加上Custom，後面接著不含空格的欄位名稱。例如，新增名為 DevOps Triage 的欄位會導致參考名稱 Custom.DevOpsTriage。參考名稱中不允許空格。

如需詳細資訊，請參閱命名限制和慣例。

如何判斷欄位數據類型？

您可以開啟「流程 > 欄位」頁面，以檢視為組織定義的欄位資料類型。

[組織設定]、[進程]、[字段] 頁面的螢幕快照。

當您的專案集合使用繼承程式模型來自定義工作追蹤時，您可以開啟 [處理>欄位] 頁面來檢視欄位的數據類型。

[集合設定]、[進程]、[字段] 頁面的螢幕快照。

如果您的專案集合使用 內部部署 XML 進程模型，您可以透過 [工作專案] 字段索引來判斷數據類型。或者，您可以：

開啟 [ 工作專案欄位總 管] 以檢閱已定義的欄位及其屬性。
使用 witadmin listfields 命令來列出字段屬性。

如需詳細資訊，請參閱工作專案欄位總管和欄位屬性清單，詳見本文稍後內容。

檢閱欄位清單

若要檢閱為組織或集合定義的欄位清單，請遵循下列步驟：

選取 Azure DevOps 標誌以開啟 Projects。然後選取 [組織設定]。
選擇處理。
選取欄位。

列出的欄位會對應至為組織或集合定義的所有欄位，其中包括所有自定義欄位，以及針對系統進程定義的欄位。

Note

如果您沒有看到 Fields，則您的集合會使用內部部署 XML 程式。該程式不支援 [欄位] 頁面。

如需每個欄位的描述、使用方式和參考名稱，請參閱工作專案欄位索引。此外，您可以使用 [ 工作項目類型] 字段 - 列出 REST API 來擷取字段參考名稱。

工作項目欄位瀏覽器

您可以使用 [工作專案欄位總管] 工具來查閱欄位屬性的工作分派。

工作項目欄位檢視器的螢幕快照。

若要存取工作專案欄位總管，請安裝程序編輯器工具。根據您的已安裝 Visual Studio 版本，從下列其中一個延伸模組取得進程編輯器工具。

Visual Studio 2019 和 2022： 從現在起，沒有可用的特定進程範本編輯器延伸模組。但是，您仍然可以使用其他工具自定義進程範本，例如任何文本編輯器或 XML 編輯器。您也可以使用 Azure DevOps 入口網站進行特定自定義，特別是針對繼承的進程。
Visual Studio 2017： TFS 進程範本編輯器。您也可以使用此版本的程式編輯器來修改舊樣式的工作項目表單。您無法使用它來編輯與新 Web 窗體相關聯的表單。
Visual Studio 2015： TFS Power Tools。

欄位屬性

每個工作專案欄位都有許多不可變更和隱藏的屬性。下表描述每個屬性。屬性有不同的名稱，取決於您是否透過 字段擷取它們 - 取得 REST API ，或透過工作專案欄位總管（WIFE）工具檢視它們。

指派給欄位的屬性取決於您使用的平台和版本。例如，繼承程式不支援某些屬性。若要查閱欄位的參考名稱，請參閱工作專案欄位索引。

Attribute

屬性類型

Description

REST:
妻子： 允許值

取得包含下拉選單值的欄位中有效值的集合。您可以藉由指定內部部署環境中的選擇清單或全域清單來更改此項目。
可以改變嗎？=是

REST： canSortBy
妻子： CanSortBy

boolean

指出您是否可以使用此欄位來排序查詢結果。
可以改變嗎？=否

REST：說明
妻子： HelpText

字串

指定欄位的描述，也定義了當您將滑鼠停留在工作項目表單中的欄位上時所顯示的說明文字。
可以改變嗎？=是

REST:
妻子： ID

Integer

指定欄位的內部識別碼。
可以改變嗎？=否

REST:
妻子： IsCloneable

boolean

指出當使用者選擇複製工作項目時，系統是否複製針對欄位定義的值。例如，系統會複製 [標題]、[ 標籤] 和 [描述] 欄位，但不會複製 [ID ] 和 [歷程記錄] 欄位。
可以改變嗎？=否

REST:
妻子： IsComputed

boolean

指出系統是否計算欄位設定的值（True）或不計算（False）。計算欄位的範例是系統設定的欄位，例如 ID、 修訂日期、 變更日期和 外部鏈結計數。
可以改變嗎？=否

REST:
妻子： IsCoreField

boolean

指出是否針對所有工作項目類型指定此欄位。
可以改變嗎？=否

REST:
妻子： IsEditable

boolean

指出使用者是否可以修改此欄位（True）或否（False）。不可編輯欄位的範例是系統設定的欄位，例如 ID、 Revision、 Created By 和 Changed By 欄位
可以改變嗎？=否

REST： 是身分
妻子： IsIdentity

boolean

指出此欄位是否為 [身分識別] 欄位。身分識別欄位是用來儲存使用者身分識別的字串字位。
可以改變嗎？=否

REST:
妻子： IsIndexed¹

boolean

指出此欄位是否已編製索引以支持搜尋。
可以改變嗎？=否

REST:
妻子： IsLongText

boolean

表示欄位可以包含超過 255 個字元，例如指派純文字、HTML 或歷程資料類型的欄位。
可以改變嗎？=否

REST：isPicklist² WIFE：

布林值

指出欄位是否與選項清單相關聯。當您定義 Azure DevOps 的自定義欄位，並選取 [選項清單（字串） ] 或 [選項清單（整數）類型] 時，系統會將值設定為 True 。系統會針對定義選項清單的繼承欄位，將值設定為 False 。
可以改變嗎？=否

REST： isPicklistSuggested² WIFE：

布林值

指出欄位是否允許使用者輸入自己的選擇清單值。當您定義 Azure DevOps 的自定義欄位時，系統會將值設定為 True ，選取 [選項清單（字串） ] 或 [選項清單（整數）類型]，然後核取 [允許使用者設定自己的值] 複選框。
可以改變嗎？=是

REST： isQueryable
妻子： IsQueryable

boolean

指出欄位是否顯示在您可以新增的欄位內，以篩選工作專案查詢（True），或不顯示（False）。大部分欄位都是可查詢的。
可以改變嗎？=否

REST:
妻子： IsReportable ³

boolean

指出可報告的屬性是否已定義或設定為除了None以外的任何值。您可以變更內部部署環境的此屬性。
可以改變嗎？=是

REST:
妻子： IsUsedInGlobalWorkflow

boolean

指出欄位是否定義於全域工作流程內。
可以改變嗎？=否

REST:
妻子： IsUserNameField

boolean

指出欄位是否用來顯示 [身分識別] 欄位。
可以改變嗎？=否

REST：名稱
妻子：姓名

字串

指派給欄位的友好名稱。您無法變更 Azure DevOps 的易記名稱，但可以使用 witadmin changefield 命令來變更內部部署版本的易記名稱。
可以變更？=僅限內部部署

REST： picklistId
妻子： HelpText

GUID

如果欄位是挑選清單，則為相關聯挑選清單的標識碼，否則為 null。當您定義 Azure DevOps 的自定義欄位，並選取 [選項清單（字串） ] 或 [選項清單（整數）類型] 時，系統會指派唯一的 GUID 值。
可以改變嗎？=否

REST:
妻子： ProhibitedValues

取得指定這類值之欄位的禁止值集合。您只能定義內部部署的禁止值。
可以變更？=僅限內部部署

REST：唯讀
WIFE:

布林值

指出欄位是否設定為唯讀。針對 Azure DevOps Services，只有自定義字段可以變更為只讀。系統欄位無法修改。
可以改變嗎？=是

REST： 參考名稱
妻子： 參考名稱

字串

指定欄位的參考名稱。
可以改變嗎？=否

REST:
妻子： 報告屬性³

根據您希望欄位如何包含在報表中來指定詳細數據、維度或量值。系統會將資料從此屬性值為 None 以外的欄位匯出至資料倉儲，並可將它們併入 SQL 報告中。
可以變更？=僅限內部部署

REST:
妻子： ReportingName³

字串

指定數據出現在 SQL 報表中時欄位的標籤。如果您未指定值，系統會使用欄位的易記名稱。
可以變更？=僅限內部部署

REST:
妻子： Reporting參考名稱³

字串

指定系統在將資料匯出至關聯式資料倉儲時所使用的欄位的不同參照名稱。如果您未指定值，系統會使用欄位參考名稱。
可以變更？=僅限內部部署

REST： 支援作業
WIFE:

set

參考此欄位時有效的查詢運算子集合。如需快速查閱各數據類型所支援的操作，請參閱查詢快速參考、運算符和每個數據類型的巨集支援。
可以改變嗎？=否

REST:
妻子： SupportsTextQuery

boolean

表示欄位是否支援文字查詢，例如 Contains Words、Does Not Contains Words。
可以改變嗎？=否

REST:
妻子： 系統類型

字串

指定欄位的數據類型，參考系統名稱，例如 System.DateTime 或 System.String。
可以改變嗎？=否

REST：類型
妻子： FieldType

字串

指定欄位的數據類型，例如布爾值、DateTime、Integer、String 等等。如需完整的清單和描述，請參閱查詢欄位、運算符和巨集。
可以改變嗎？=否

REST：用法
妻子：用法

字串

指定欄位是否要與工作專案（WorkItem）或工作項目連結（WorkItemLink）物件搭配使用。大部分欄位的使用方式為 WorkItem。如需使用值的完整清單，請參閱取得欄位、FieldUsage。
可以改變嗎？=否

Note

針對內部部署，您可以啟用字段的索引編製，以改善字段篩選時的查詢回應時間。如需詳細資訊，請參閱本文稍後的索引欄位。
系統只會將 isPicklist 和 isPicklistSuggested 屬性指派給為繼承程序定義的自訂欄位。繼承的程式模型支援 Azure DevOps Server 2020 和更新版本。如需詳細資訊，請參閱繼承的進程模型。
所有報告屬性僅適用於已設定支援 SQL Server Reporting 和 SQL Server Analysis Services 之項目的內部部署。

可報告屬性

所有報告屬性僅適用於內部部署，您可以在其中設定專案以支援 SQL Server 報告和 SQL Server Analysis Services。如需詳細資訊，請參閱將報表新增至專案。

如需每個可報告屬性的描述，請參閱新增或修改工作專案欄位以支持報告。

若要查看預設定義可報告屬性的欄位清單，請參閱可報告欄位參考。

索引欄位

使用 witadmin indexfield 命令來啟用或停用用於工作專案欄位的索引編制。啟用欄位的索引編製可以改善指定該欄位的查詢效能。依預設，系統會為下列欄位編製索引：

指派至
建立日期
變更者
State
Reason
區域識別碼
疊代識別碼
工作項目類型

如果您在工作項目查詢中經常新增使用的自定義欄位，請考慮啟用該欄位的索引編制。如需詳細資訊，請參閱管理工作專案欄位（witadmin）。

列出欄位屬性

您可以使用 Fields - Get REST API 列出指派給字段的屬性。以實際的組織名稱取代 OrganizationName 。

https://dev.azure.com/OrganizationName/_apis/wit/fields/FieldReferenceName

例如，若要列出反覆項目路徑的屬性，請使用組織的System.IterationPath參考名稱fabrikam：

https://dev.azure.com/fabrikam/_apis/wit/fields/System.IterationPath

傳回的資料：

{
"name": "Iteration Path",
"referenceName": "System.IterationPath",
"description": "The iteration within which this bug will be fixed",
"type": "treePath",
"usage": "workItem",
"readOnly": false,
"canSortBy": true,
"isQueryable": true,
"supportedOperations": [
{
"referenceName": "SupportedOperations.Under",
"name": "Under"
},
{
"referenceName": "SupportedOperations.NotUnder",
"name": "Not Under"
},
{
"referenceName": "SupportedOperations.Equals",
"name": "="
},
{
"referenceName": "SupportedOperations.NotEquals",
"name": "<>"
},
{
"referenceName": "SupportedOperations.In",
"name": "In"
},
{
"name": "Not In"
}
],
"isIdentity": false,
"isPicklist": false,
"isPicklistSuggested": false,
"url": "https://dev.azure.com/mseng/_apis/wit/fields/System.IterationPath"
}

您可以使用 Fields - Get REST API 列出指派給字段的屬性。請在 OrganizationName 中輸入您的組織名稱。若要開始使用 REST，請參閱 Azure DevOps Services REST API 參考

https://{ServerName:Port}/tfs/{Collection}/_apis/wit/fields/FieldReferenceName?api-version={version}

例如，我們在這裡列出「反覆項目路徑」的屬性，並為 fabrikam 伺服器指定其參考名稱 System.IterationPath。

https://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPath?api-version=4.1

傳回的資料：

{
"name": "Iteration Path",
"referenceName": "System.IterationPath",
"description": "The iteration within which this bug will be fixed",
"type": "treePath",
"usage": "workItem",
"readOnly": false,
"canSortBy": true,
"isQueryable": true,
"supportedOperations": [
{
"referenceName": "SupportedOperations.Under",
"name": "Under"
},
{
"referenceName": "SupportedOperations.NotUnder",
"name": "Not Under"
},
{
"referenceName": "SupportedOperations.Equals",
"name": "="
},
{
"referenceName": "SupportedOperations.NotEquals",
"name": "<>"
},
{
"referenceName": "SupportedOperations.In",
"name": "In"
},
{
"name": "Not In"
}
],
"isIdentity": false,
"isPicklist": false,
"isPicklistSuggested": false,
"url": "https://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPath?api-version=4.1"
}

使用 `witadmin` 命令行工具列出屬性

您可以使用witadmin listfields命令來列出指定的欄位屬性，例如資料類型、可報告的屬性及索引設定。

例如，您可以輸入下列命令來列出為指定字段定義的屬性，例如 Microsoft.VSTS.Common.Issue。

witadmin listfields /collection:http://fabrikam: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 參數會指出每個項目的名稱，以及使用欄位的工作項目類型。

使用欄位的最佳實務

使用工作專案欄位時，請考慮下列建議：

場地選擇與設計

選擇有意義的名稱：使用描述性欄位名稱，清楚地表明其用途
標準化命名：在整個組織中建立一致的命名約定
限制自定義字段：明智地添加自定義字段，避免用戶不知所措
考慮數據類型：為您存儲的信息選擇適當的數據類型

效能優化

使用索引欄位：對於內部部署，請考慮索引經常查詢的自訂欄位
避免繁重查詢：使用許多欄位篩選器時請注意查詢效能
優化選項列表：保持選項列表值的大小易於管理且組織良好

維護和治理

文檔字段使用： 維護解釋自定義字段的目的和用法的文件
定期審查：定期審查自定義字段以識別未使用或冗餘的字段
規劃變更：考慮欄位變更對現有工作專案和查詢的影響
測試修改：一律先在開發環境中測試欄位變更

新增和修改欄位

若要將欄位新增至進程，您可以將欄位新增至一或多個工作項目類型。如需詳細資訊，請參閱自定義繼承程式。

您可以新增或修改 WIT 中包含的欄位，或新增自訂 WIT。如需詳細資訊，請參閱

對於使用繼承程式模型的專案集合：自定義繼承程式。
對於使用內部部署 XML 進程模型的專案集合：自定義內部部署 XML 進程模型。

您可以使用 witadmin 命令行工具，來變更除了系統欄位以外的任何欄位的功能變數名稱、索引和報表屬性。如需詳細資訊，請參閱管理工作項目欄位-witadmin。

現場問題疑難排解

使用工作專案欄位時的常見問題和解決方案：

現場能見度問題

欄位未出現：檢查欄位是否已新增至工作專案類型版面配置
權限問題：確認您擁有檢視或編輯欄位的適當權限
流程差異：確保欄位存在於目前流程中

查詢和搜尋問題

欄位無法查詢：檢查 IsQueryable 欄位的屬性
效能問題：考慮為經常查詢的自訂欄位編製索引（內部部署）
運算子限制：確認欄位資料型別支援哪些運算子

資料輸入和驗證

無效值：檢查欄位是否有限制允許的值或驗證規則
唯讀欄位：驗證欄位的 IsEditable 屬性
格式要求：確保資料與預期的欄位資料類型相符

查詢快速參考，以快速了解查詢語法和使用方式。
工作專案欄位索引，以檢視所有可用的工作專案欄位。
新增和管理繼承程式的欄位，以根據您的繼承程式需求自定義欄位。
Azure Boards Analytics 的中繼資料參考，以了解分析中繼資料和報表功能。

查詢快速參考，以快速了解查詢語法和使用方式。
工作專案欄位索引，以檢視所有可用的工作專案欄位。
選擇專案集合的進程模型，以針對您的需求選取適當的進程模型。
根據專案的需求修改工作專案欄位。
使用 witadmin 管理工作專案字段，以執行進階字段管理工作。
Azure Boards Analytics 的中繼資料參考，幫助您理解分析中繼資料和報告功能。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-04

共用方式為

列出工作專案欄位和屬性

為什麼工作專案欄位很重要

Prerequisites

清單或檢視欄位

欄位數據類型和名稱

什麼是領域？ 欄位名稱如何運作？

欄位命名需求

系統與預先定義的欄位

自訂欄位

如何判斷欄位數據類型？

檢閱欄位清單

工作項目欄位瀏覽器

欄位屬性

可報告屬性

索引欄位

列出欄位屬性

使用 witadmin 命令行工具列出屬性

使用欄位的最佳實務

場地選擇與設計

效能優化

維護和治理

新增和修改欄位

現場問題疑難排解

現場能見度問題

查詢和搜尋問題

資料輸入和驗證

相關內容

意見反應

其他資源

什麼是領域？欄位名稱如何運作？

使用 `witadmin` 命令行工具列出屬性