列出工作專案欄位和屬性

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

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

• 處理 > 欄位網頁
• 工作專案欄位總管

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

必要條件

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

清單或檢閱欄位

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

工具	繼承	裝載的 XML	內部部署 XML
入口網站：列出繼承和自定義定義的欄位	✔️	✔️1
工作專案欄位總管	✔️	✔️	✔️
witadmin listfields 命令行工具	✔️	✔️	✔️

注意

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

欄位數據類型和名稱

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

欄位會由下列三個屬性定義：

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

如需每個欄位屬性的詳細描述，以及如何列出它們，請參閱 本文稍後的欄位屬性 和 清單欄位屬性 。 如需工作專案類型 （WIT） 和工作專案的概觀，請參閱 使用使用者劇本、問題、Bug、功能和 Epic 追蹤工作。

什麼是欄位？ 功能變數名稱的使用方式？

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

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

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

欄位名稱

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

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

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

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

系統與預先定義的欄位

工作專案功能變數名稱可唯一識別 Azure DevOps 中的每個字段。 請確定您的功能變數名稱符合下列指導方針：

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

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

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

自訂欄位

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

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

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

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

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

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

如何判斷欄位數據類型？

您可以開啟 [處理>欄位] 頁面，以檢視為組織定義的欄位資料類型。

檢閱欄位清單

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

1. 選取 Azure DevOps 標誌以開啟 Projects。 然後選擇 [ 組織設定]。

   

2. 選取 [ 處理]。

   

3. 選取欄位。

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

   

   注意

   如果您沒有看到 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） 工具檢視它們。

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

屬性

屬性類型

說明

---

REST：
WIFE： AllowedValues

collection

取得包含picklist值之欄位的有效值集合。 您可以藉由指定選擇清單或全域清單（內部部署）來變更此專案。
可以變更？=是

REST： canSortBy
妻子： CanSortBy

boolean

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

REST： 描述
WIFE： HelpText

字串

指定欄位的描述，該欄位也會定義當您將滑鼠停留在工作專案窗體內的欄位時所出現的說明文字。
可以變更？=是

REST：
妻子： 標識碼

整數

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

REST：
妻子： IsCloneable

boolean

指出當使用者選擇複製工作專案時，是否複製欄位所定義的值。 例如， 會複製 [標題]、 [卷標] 和 [描述 ] 字段，但 不會複製 [標識符 ] 和 [歷程記錄 ] 字段。
可以變更？=否

REST：
妻子： IsComputed

boolean

指出這個欄位所設定的值是否由系統計算 （True） 或不是 （False）。 計算欄位的範例是系統所設定的欄位，例如標識碼、修訂日期、變更日期和外部連結計數。
可以變更？=否

REST：
妻子： IsCoreField

boolean

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

REST：
妻子： IsEditable

boolean

指出使用者是否可以修改此欄位 （True） 或否 （False）。 不可編輯欄位的範例是系統所設定的欄位，例如標識碼、修訂、建立者及變更者欄位
可以變更？=否

REST： isIdentity
妻子： IsIdentity

boolean

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

REST：
妻子： IsIndexed¹

boolean

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

REST：
妻子： IsLongText

boolean

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

REST：isPicklist² WIFE：

布林值

指出欄位是否與挑選清單相關聯。 選取 Azure DevOps 和 Picklist （String） 或 Picklist （Integer） 類型的自定義欄位時，此值會設定為 True 。 對於定義挑選清單的繼承欄位，此值會設定為 False 。
可以變更？=否

REST： isPicklistSuggested² WIFE：

布林值

指出欄位是否允許使用者輸入自己的選擇清單值。 選取 Azure DevOps、Picklist （String） 或 Picklist （Integer） 類型的自定義欄位時，此值會設定為 True，並核取 [允許使用者設定自己的值] 複選框。
可以變更？=是

REST： isQueryable
WIFE： IsQueryable

boolean

指出欄位是否顯示在您可以新增以篩選工作項目查詢 （True） 或 [False] 的欄位集合內。 大部分欄位都是可查詢的。
可以變更？=否

REST：
妻子： IsReportable ³

boolean

指出報表屬性是否已定義或設定為 None 以外的任何專案。 內部部署環境可以變更此屬性。
可以變更？=是

REST：
妻子： IsUsedInGlobalWorkflow

boolean

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

REST：
妻子： IsUserNameField

boolean

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

REST： 名稱
妻子： 名稱

字串

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

REST： picklistId
WIFE： HelpText

GUID

如果欄位是挑選清單，則為相關聯挑選清單的標識碼，否則為 null。 當為 Azure DevOps 和 Picklist （String） 或 Picklist （Integer） 類型定義自定義欄位時，會指派唯一 GUID 值。
可以變更？=否

REST：
WIFE： ProhibitedValues

collection

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

REST： readOnly
老婆：

布林值

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

REST： referenceName
WIFE： ReferenceName

字串

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

REST：
WIFE： ReportingAttributes³

根據 您是否希望欄位包含在報表中，指定 [詳細數據]、 [維度] 或 [量值]。 此屬性的值以外的欄位數據會匯出至數據倉儲，而且可以包含在 SQL 報表中。
可以變更？=僅限內部部署

REST：
WIFE： ReportingName³

字串

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

REST：
WIFE： ReportingReferenceName³

字串

指定數據匯出至關係型數據倉儲時所使用的欄位不同的參考名稱。 如果您未指定值，則會使用欄位參考名稱。
可以變更？=僅限內部部署

REST： supportedOperations
老婆：

set

參考此欄位時有效的查詢運算元集合。 如需以數據類型為基礎的支持作業快速參考，請參閱 查詢每個數據類型支援的快速參考、運算符和巨集。
可以變更？=否

REST：
WIFE： SupportsTextQuery

boolean

指出欄位是否支援文字查詢，例如 Contains Words、 Not Contains Words。
可以變更？=否

REST：
WIFE： SystemType

字串

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

REST： 類型
WIFE： FieldType

字串

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

REST： 使用量
WIFE： 使用方式

字串

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

注意

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

列出欄位屬性

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

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

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

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

**Returned data:**

> [!div class="tabbedCodeSnippets"]
> ```JSON
> {
> "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"
> }
> ```

新增和修改欄位

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

相關文章

• 請參閱查詢快速參考 ，快速了解查詢語法和使用方式。
• 探索 [工作專案] 欄位索引 ，以檢視所有可用的工作專案欄位。
• 新增和管理繼承程式的欄位，以根據您的繼承程式 需求自定義欄位。
• 存取 Azure Boards 分析 的元數據參考，以瞭解分析元數據和報告功能。