Azure Boards 中的工作项字段和属性

项目
04/16/2024

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

工作项字段用于跟踪信息。字段是为组织定义的，并在为该组织定义的所有项目中共享。可以使用两个工具之一来查看为组织定义的字段。这些工具同时适用于继承和托管 XML 流程模型。

流程>字段网页
工作项字段资源管理器

工作项字段用于跟踪信息。字段是为集合定义的，并在为该集合定义的所有项目中共享。可以使用两个工具之一来查看为集合定义的字段。

流程>字段网页：适用于继承的流程模型
工作项字段资源管理器：适用于继承和本地 XML 流程模型。

有关使用系统流程定义的每个字段的说明，请参阅工作项字段索引。

先决条件

若要查看为组织或集合定义的字段，你必须是“项目集合有效用户”应用程序组的成员，或者为组织或集合将“查看实例级信息”权限设置为“允许”。

列出或查看字段

若要列出或查看字段，可以使用以下工具之一，具体取决于所使用的流程模型（继承、托管 XML 或本地 XML）。有关默认流程中定义的字段的索引，请参阅工作项字段索引。

工具	继承	托管 XML	本地 XML
Web 门户：列出继承的字段和自定义的字段	✔️	✔️1
工作项字段资源管理器	✔️	✔️	✔️
witadmin listfields 命令行工具	✔️	✔️	✔️

注意

仅支持默认流程（敏捷、CMMI、Scrum）。

字段数据类型和名称

每个工作项类型指定为引用该类型的工作项定义的字段。每个字段都与许多属性相关联，其中许多属性由系统设置，无法更改。

每个字段由以下三个属性定义。

数据类型：指定可以输入到字段中的数据类型，例如布尔值、双精度、整数、HTML 和字符串。有关每种数据类型的说明，请参阅查询字段、运算符和宏。
友好名称：指定分配给字段并为查询子句中的字段选择的名称。此名称可能与工作项窗体上显示的名称不同。
引用名称：指定在创建 WIQL 查询或即兴工作项模板、使用 REST API 命令或定义 XML 工作项类型定义时使用的名称。定义后，无法更改引用名称。

有关每个字段属性的说明以及如何列出属性，请参阅本文后面的字段属性和列出字段属性。有关 WIT 和工作项的概述，请参阅使用用户情景、问题、bug、功能和史诗跟踪工作。

什么是字段？如何使用字段名称？

每个工作项类型都与 31 个系统字段和多个类型特定的字段相关联。使用工作项计划和跟踪项目。

每个字段都支持跟踪有关要执行的工作的一条信息。分配给字段的值存储在工作跟踪数据存储中，你可以创建查询来确定状态和趋势。

有关为核心系统流程（敏捷、基本、Scrum 和 CMMI 流程）定义的每个字段的说明和用法，请参阅工作项字段索引。

字段名

工作项字段名称唯一标识每个工作项字段。请确保字段名称符合以下准则：

字段名称在帐户/项目集合中必须是唯一的
字段名称必须是 128 个 Unicode 字符以内
字段名称不能包含任何前导或尾随空格，也不能包含两个或多个相连的空格
字段名称必须至少包含一个字母字符
字段名称不能包含以下字符：.,;'`:~\/\*|?"&%$!+=()[]{}<>。

由于自定义字段是为组织或集合定义的，因此添加到某个流程的自定义字段不能与添加到另一个流程的字段具有相同名称。

有关详细信息，请参阅命名限制和约定。

系统字段和预定义字段

所有系统定义字段的引用名称都以 System 开头，例如 System.AreaPath、System.AssignedTo，后面的部分仍然采用该模式。

默认流程所定义的预定义字段以 Microsoft.VSTS 开头，然后根据用法进一步进行区分。下面是通常用于计划用途，以及用于与 Office Project 集成、与 Team Foundation Build 集成和与测试用例管理 (TCM) 集成的预定义字段示例：

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 命令列出字段属性。有关详细信息，请参阅本文后面的工作项字段资源管理器和列表字段属性。

流程>字段网页

若要查看为组织或集合定义的字段列表，请打开“组织设置”>“流程”>“字段”。

选择 Azure DevOps 徽标以打开“项目”。然后选择“组织设置”。
然后，选择“流程”。

注意

如果未看到“流程”，则使用的是 TFS-2018 或更低版本。不支持 “进程 ”页。必须使用本地 XML 流程模型支持的功能。
然后，选择“字段”。

列出的字段对应于为组织或集合定义的所有字段。这包括所有自定义字段以及为系统流程定义的字段。

注意

如果未看到“字段”，则表示集合使用本地 XML 流程。该流程不支持“字段”页。

有关每个字段的说明和用法，以及每个字段的引用名称，可以从工作项字段索引中进行查找。还可以从工作项类型字段 - 列表 REST API中获取字段的引用名称。

工作项字段资源管理器

可以使用工作项字段资源管理器工具来查找字段属性的分配。

工作项字段资源管理器的屏幕截图。

若要访问工作项字段资源管理器，必须安装流程编辑器工具。根据已安装的 Visual Studio 版本，从以下扩展之一获取流程编辑器工具。

Visual Studio 2019 和 2022： 到目前为止，没有可用的特定进程模板编辑器扩展。但是，你仍然可以使用其他工具（如任何文本编辑器或 XML 编辑器）自定义进程模板。还可以使用 Azure DevOps Web 门户进行某些自定义，尤其是对于继承的进程。
Visual Studio 2017：TFS 流程模板编辑器。还可以使用此版本的流程编辑器来修改旧样式的工作项窗体。不能使用它来编辑与新 Web 窗体关联的窗体。
Visual Studio 2015：TFS Power Tools。

字段属性

每个工作项字段有许多不可更改和隐藏的属性。下表介绍了每个属性。属性具有不同的名称，具体取决于你是否通过字段 - 获取REST API 来获取属性，或通过工作项字段资源管理器 (WIFE) 工具来查看属性。

分配给字段的属性取决于所使用的平台和版本。例如，某些属性不支持继承流程。若要查找字段的引用名称，请参阅工作项字段索引。

Attribute

属性类型

说明

REST：
WIFE：AllowedValues

collection

获取包含选择列表值的字段的有效值集合。可以通过指定选择列表或全局列表来对此进行更改（本地）。
可以更改？=是

REST：canSortBy
WIFE：CanSortBy

boolean

指示是否可以使用此字段对查询结果进行排序。
可以更改？=否

REST：description
WIFE：HelpText

字符串

指定字段的说明，该字段还定义将鼠标悬停在工作项窗体中的字段上时显示的帮助文本。
可以更改？=是

REST：
WIFE：ID

Integer

指定字段的内部 ID。
可以更改？=否

REST：
WIFE：IsCloneable

boolean

指示当用户选择复制工作项时，是否复制为字段定义的值。例如，会复制“标题”、“标记”和“说明”字段，但不会复制“ID”和“历史记录”字段。
可以更改？=否

REST：
WIFE：IsComputed

boolean

指示此字段设置的值是 (True) 否 (False) 由系统计算。计算字段是系统设置字段的示例，例如“ID”、“修订日期”、“更改日期”和“外部链接计数”。
可以更改？=否

REST：
WIFE：IsCoreField

boolean

指示是否为所有工作项类型指定此字段。
可以更改？=否

REST：
WIFE：IsEditable

boolean

指示用户是 (True) 否 (False) 可以修改此字段。不可编辑字段是系统设置字段的示例，例如“ID”、“修订”、“创建者”和“更改者”字段
可以更改？=否

REST：isIdentity
WIFE：IsIdentity

boolean

指示此字段是否为标识字段。标识字段是用于存储用户标识的字符串字段。
可以更改？=否

REST：
WIFE：IsIndexed¹

boolean

指示是否为此字段编制索引以支持搜索。
可以更改？=否

REST：
WIFE：IsLongText

boolean

指示该字段可以包含超过 255 个字符，例如分配了“纯文本”、“HTML”或“历史记录”数据类型的字段。
可以更改？=否

REST：isPicklist² WIFE：

boolean

指示字段是否与选择列表相关联。为 Azure DevOps 定义了自定义字段并选择了选择列表（字符串）或选择列表（整数）类型时，该值设置为 True。对于定义选择列表的继承字段，该值设置为 False。
可以更改？=否

REST：isPicklistSuggested² WIFE：

boolean

指示字段是否允许用户为选择列表输入自己的值。为 Azure DevOps 定义了自定义字段，选择了选择列表（字符串）或选择列表（整数）类型，并且选中了“允许用户设置自己的值”复选框时，该值设置为 True。
可以更改？=是

REST：isQueryable
WIFE：IsQueryable

boolean

指示字段是 (True) 否 (False) 显示在可以添加以筛选工作项查询的字段集中。大多数字段都是可查询的。
可以更改？=否

REST：
WIFE：IsReportable ³

boolean

指示是定义可报告属性还是设置为除“无”以外的任何属性。对于本地环境，可以更改此属性。
可以更改？=是

REST：
WIFE：IsUsedInGlobalWorkflow

boolean

指示字段是否在全局工作流中定义。
可以更改？=否

REST：
WIFE：IsUserNameField

boolean

指示字段是否用于显示标识字段。
可以更改？=否

REST：name
WIFE：Name

字符串

分配给字段的友好名称。不能为 Azure DevOps 更改友好名称，但可以使用 witadmin changefield 命令为本地环境更改。
可以更改？=仅限本地

REST：picklistId
WIFE：HelpText

GUID

如果字段是一个选择列表，则为关联的选择列表的标识符，否则为 null。为 Azure DevOps 定义了自定义字段并选择了选择列表（字符串）或选择列表（整数）类型时，分配唯一的 GUID 值。
可以更改？=否

REST：
WIFE：ProhibitedValues

collection

获取指定此类值的字段的禁止值集合。只能为本地部署定义禁止的值。
可以更改？=仅限本地

REST：readOnly
WIFE：

boolean

指示字段是否设置为只读。对于 Azure DevOps Services，只能将自定义字段更改为只读。无法修改系统字段。
可以更改？=是

REST：referenceName
WIFE：ReferenceName

字符串

指定字段的引用名称。
可以更改？=否

REST：
WIFE：ReportingAttributes³

指定“详细信息”、“维度”或“度量值”，具体取决于你是否希望以及希望如何在报表中包含字段。具有此属性的值（“无”除外）的字段中的数据将导出到数据仓库，并且可以包含在 SQL 报表中。
可以更改？=仅限本地

REST：
WIFE：ReportingName³

字符串

指定数据出现在 SQL 报表中时字段的标签。如果未指定值，则使用字段的友好名称。
可以更改？=仅限本地

REST：
WIFE：ReportingReferenceName³

字符串

为将数据导出到关系数据仓库时使用的字段指定一个不同的引用名称。如果未指定值，则使用字段的引用名称。
可以更改？=仅限本地

REST：supportedOperations
WIFE：

set

引用此字段时有效的查询运算符集。有关基于数据类型的支持操作的快速参考，请参阅查询快速参考、运算符和每种数据类型支持的宏。
可以更改？=否

REST：
WIFE：SupportsTextQuery

boolean

指示字段是否支持文本查询，如“包含单词”、““不包含单词””。
可以更改？=否

REST：
WIFE：SystemType

字符串

指定字段的数据类型，引用系统名称，如 System.DateTime 或 System.String。
可以更改？=否

REST：type
WIFE：FieldType

字符串

指定字段的数据类型，如“布尔值”、“日期/时间”、“整数”、“字符串”等。有关完整列表和说明，请参阅查询字段、运算符和宏。
可以更改？=否

REST：usage
WIFE：Usage

字符串

指定字段是适用于工作项 (WorkItem) 还是工作项链接 (WorkItemLink) 对象。大多数字段的用法为 WorkItem。有关使用值的完整列表，请参阅获取字段、FieldUsage。
可以更改？=否

注意

对于本地部署，可以为字段启用索引编制，以缩短筛选字段时的查询响应时间。有关详细信息，请参阅本文后面的索引字段。
isPicklist 和 isPicklistSuggested 属性仅分配给为继承流程定义的自定义字段。 Azure DevOps Server 2019 及更高版本支持继承的流程模型。有关详细信息，请参阅继承的流程模型。
所有报告属性仅对项目配置为支持 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 命令来对工作项字段启用或禁用索引。为字段启用索引后，查找在查询中指定了该字段的工作项时可提高性能。默认情况下，将为以下字段编制索引：“指派给”、 “创建日期”、“更改者”、“状态”、“原因”、“区域 ID”、“迭代 ID”和“工作项类型”。

如果添加了在许多工作项查询中都使用的自定义字段，你可能要为该字段启用索引。有关详细信息，请参阅管理工作项字段 (witadmin)。

列出字段属性

可以使用字段 - 获取 REST API 列出分配给字段的属性。为“组织名称”输入组织名称。

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"
}

可以使用字段字段 - 获取 REST API 列出分配给字段的属性。为“组织名称”输入组织名称。若要开始使用 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。

通过

Azure Boards 中的工作项字段和属性

先决条件

列出或查看字段

字段数据类型和名称

什么是字段？如何使用字段名称？

字段名

系统字段和预定义字段

自定义字段

如何确定字段数据类型？

流程>字段网页

工作项字段资源管理器

字段属性

可报告特性

索引字段

列出字段属性

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

添加和修改字段

反馈

其他资源

通过

Azure Boards 中的工作项字段和属性

先决条件

列出或查看字段

字段数据类型和名称

什么是字段？ 如何使用字段名称？

字段名

系统字段和预定义字段

自定义字段

如何确定字段数据类型？

流程>字段网页

工作项字段资源管理器

字段属性

可报告特性

索引字段

列出字段属性

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

添加和修改字段

相关文章

反馈

其他资源

什么是字段？如何使用字段名称？

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