Azure Boards 中的工作專案欄位和屬性

  • 發行項

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

工作專案欄位用來追蹤資訊。 欄位會針對組織定義，並跨為該組織定義的所有項目共用。 您可以使用兩個工具之一來檢閱為組織定義的欄位。 這些工具適用於繼承和裝載的 XML 進程模型。

工作專案欄位用來追蹤資訊。 欄位會針對集合定義，並跨針對該集合定義的所有項目共用。 您可以使用兩個工具之一來檢閱為集合定義的欄位。

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

必要條件

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

清單或檢閱欄位

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

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

注意

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

欄位數據類型和名稱

每個工作項目類型都會指定為參考該類型之工作專案所定義的欄位。 每個欄位都與數個屬性相關聯，其中許多屬性都是由系統設定，而且無法變更。

每個欄位都是由下列三個屬性所定義。

  • 數據類型：指定可以輸入字段的數據類型，例如布爾值、Double、Integer、HTML 和 String。 如需每個數據類型的描述，請參閱 查詢欄位、運算元和宏。
  • 易記名稱：指定指派給字段的名稱，以及您在查詢子句中為 Field 選取的名稱。 此名稱可能與工作項目表單上顯示的名稱不同。
  • 參考名稱：指定您在建立WIQL查詢或即興工作專案範本、使用REST API命令或定義 XML 工作專案類型定義時所使用的名稱。 定義之後，就無法變更參考名稱。

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

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

每個 工作項目類型 都與 31 個系統欄位和數個更多類型特定欄位相關聯。 您可以使用工作項目來規劃和追蹤您的專案。

每個欄位都支持追蹤要執行之工作的相關信息。 您指派給欄位的值會儲存在工作追蹤資料存放區中，您可以建立查詢來判斷狀態和趨勢。

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

欄位名稱

工作專案功能變數名稱可唯一識別每個工作專案欄位。 請確定您的功能變數名稱落在這些指導方針中：

  • 功能變數名稱在帳戶/專案集合內必須是唯一的
  • 功能變數名稱必須是 128 個字元或更少 Unicode 字元
  • 功能變數名稱不能包含任何前置或尾端空格，也不能包含兩個或多個連續空格
  • 功能變數名稱必須至少包含一個字母字元
  • 功能變數名稱不能包含下列字元： .,;'`:~\/\*|?"&%$!+=()[]{}<>。

由於自定義欄位是針對組織或集合所定義的，因此您無法將自定義欄位新增至具有相同功能變數名稱的程式，而該欄位會新增至另一個進程。

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

系統與預先定義的欄位

所有系統定義的欄位都有以 System 開頭的參考名稱，例如 System.AreaPath、System.AssignedTo，然後繼續進行該模式。

默認程式所定義的預先定義欄位會從 Microsoft.VSTS 開始，然後根據其使用方式進一步不同。 一般使用的預先定義欄位範例，用於排程用途和與 Office Project 整合、與 Team Foundation Build 整合，以及與測試案例管理整合的範例如下：

  • Microsoft.VSTS.Common.Priority
  • Microsoft.VSTS.Scheduling.DueDate
  • Microsoft.VSTS.Build.FoundIn
  • Microsoft.VSTS.TCM.Steps

如需針對預設進程/進程範本定義的所有系統和預先定義欄位的概觀，請參閱 工作專案欄位索引。 如需指定功能變數名稱的詳細資訊，請參閱 命名限制。

自訂欄位

由於自定義欄位是針對組織或專案集合所定義，因此您無法將自定義欄位新增至具有相同功能變數名稱的程式，而該欄位與您新增至另一個進程相同。

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

  • 每個 WIT 最多可以定義 64 個字段
  • 每個進程最多可以定義 512 個字段

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

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

如何判斷欄位數據類型？

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

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

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

集合 設定、進程、欄位頁面的螢幕快照。

如果使用內部部署 XML 進程模型，您可以透過 [工作專案] 字段索引來查閱數據類型。 或者，您可以開啟 [工作專案字段總管] 來檢閱定義的欄位及其屬性指派，或使用 witadmin listfields 命令來列出字段屬性。 如需詳細資訊，請參閱 本文稍後的工作專案欄位總管 和 清單欄位屬性 。

處理>欄位網頁

若要檢閱為組織或集合定義的欄位清單，請開啟 [組織設定>處理>字段]。

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

    選擇組織設定的螢幕快照。

  2. 然後選擇 [ 處理]。

    [選擇程式] 的螢幕快照。

    注意

    如果您沒有看到 Process，則您正在從 TFS-2018 或更早版本工作。 不支援 [ 處理 ] 頁面。 您必須使用內部 部署 XML 進程模型支援的功能。

  3. 然後選擇 [ 欄位]。

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

    建立所選繼承程序的複本螢幕快照。

    注意

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

    如需每個欄位的描述和使用方式，以及每個欄位的 參考名稱，您可以從 [工作專案] 欄位索引中查閱它。 您也可以從 [工作項目類型] 字段 - 清單 REST API 取得欄位的參考名稱。

工作專案欄位總管

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

工作專案欄位總管的螢幕快照。

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

欄位屬性

每個工作專案欄位有許多不可變更和隱藏的屬性。 下表描述每個屬性。 如果您透過 [欄位 - 取得REST API] 或透過工作專案欄位總管 （WIFE） 工具檢視屬性，則屬性有不同的名稱。

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

屬性

屬性類型

說明

REST：
WIFE： AllowedValues

collection

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

REST： canSortBy
妻子： CanSortBy

boolean

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

REST： 描述
WIFE： HelpText

string

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

REST：
妻子： 標識碼

整數

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

REST：
妻子： IsCloneable

boolean

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

REST：
妻子： IsComputed

boolean

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

REST：
妻子： IsCoreField

boolean

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

REST：
妻子： IsEditable

boolean

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

REST： isIdentity
妻子： IsIdentity

boolean

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

REST：
妻子： IsIndexed1

boolean

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

REST：
妻子： IsLongText

boolean

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

REST：isPicklist2 WIFE：

boolean

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

REST： isPicklistSuggested2 WIFE：

boolean

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

REST： isQueryable
WIFE： IsQueryable

boolean

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

REST：
妻子： IsReportable 3

boolean

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

REST：
妻子： IsUsedInGlobalWorkflow

boolean

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

REST：
妻子： IsUserNameField

boolean

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

REST： 名稱
妻子： 名稱

string

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

REST： picklistId
WIFE： HelpText

GUID

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

REST：
WIFE： ProhibitedValues

collection

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

REST： readOnly
妻子：

boolean

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

REST： referenceName
WIFE： ReferenceName

string

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

REST：
WIFE： ReportingAttributes3

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

REST：
WIFE： ReportingName3

string

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

REST：
WIFE： ReportingReferenceName3

string

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

REST： supportedOperations
妻子：

set

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

REST：
WIFE： SupportsTextQuery

boolean

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

REST：
WIFE： SystemType

string

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

REST： 類型
WIFE： FieldType

string

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

REST： 使用量
WIFE： 使用方式

string

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

注意

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

可報告的屬性

所有報告屬性僅適用於已設定支援 SQL Server Reporting 和 SQL Server Analysis Services 之項目的內部部署。 如需詳細資訊，請參閱 將報表新增至專案。

如需每個可報告屬性的描述，請參閱 [新增或修改支持報告的工作專案字段]（（/previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting）。

如需預設定義可報告屬性的欄位清單，請參閱 可報告欄位參考 。

索引欄位

您可以使用 witadmin indexfield 命令來啟用或停用工作專案欄位的索引編制。 當您啟用欄位的索引編製時，可能會增加尋找查詢指定該欄位的工作專案效能。 根據預設，下列欄位會編製索引：指派給、建立日期、變更者、狀態、原因、區域標識碼、反覆專案標識碼和工作項目類型。

如果您新增許多工作項目查詢中使用的自定義欄位，您可能想要啟用該欄位的索引編制。 如需詳細資訊，請參閱 管理工作專案字段 （witadmin）。

列出欄位屬性

您可以使用 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

傳回的資料：

{
"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。 如需詳細資訊，請參閱

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