列出工作项字段和属性

项目
11/23/2024

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

工作项字段用于跟踪 Azure DevOps 中的信息。这些字段在组织级别定义，并在组织中的所有项目中共享。若要查看为组织定义的字段，可以使用以下两种工具之一，可用于继承和托管的 XML 进程模型：

“处理 > 字段”网页
工作项字段资源管理器

工作项字段用于跟踪 Azure DevOps 中的信息。这些字段在集合级别定义，并在该集合中的所有项目中共享。若要查看为集合定义的字段，请使用以下工具之一：

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

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

先决条件

权限：若要查看为组织或集合定义的字段，请成为 Project Collection Valid Users 应用程序组的成员，或者将“查看实例级信息”权限设置为“允许组织或集合”。

列出或查看字段

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

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

注意

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

字段数据类型和名称

每个工作项类型指定该类型的工作项中包含的字段。每个字段都有多个属性，其中许多属性是系统定义的和不可变的。

字段由以下三个属性定义：

数据类型：指示可输入到字段中的数据类型，例如布尔值、Double、Integer、HTML 或 String。有关每种数据类型的详细说明，请参阅查询字段、运算符和宏。
友好名称：分配给字段的用户友好名称，用于在 查询子句中选择字段 。此名称可能与工作项窗体上显示的名称不同。
引用名称：创建 WIQL 查询、即兴工作项模板、执行 REST API 命令或定义 XML 工作项类型定义时使用的标识符。引用名称是永久性的，设置后无法更改。

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

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

每个工作项类型包括 31 个系统字段和多个特定于类型的字段。工作项用于规划和跟踪项目。

每个字段捕获要执行的工作的特定信息。分配给这些字段的值存储在工作跟踪数据存储中，使你能够创建用于确定状态和趋势的查询。

有关为核心系统进程（Agile、Basic、Scrum 和 CMMI）定义的每个字段的说明和用法，请参阅 “工作项”字段索引。

字段名

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

唯一性：字段名称在帐户或项目集合中必须是唯一的。
长度：字段名称必须包含 128 个 Unicode 字符或更少字符。
间距：字段名称不能有前导或尾随空格，或者包含两个或多个连续空格。
组合：字段名称必须至少包含一个字母字符。
禁止的字符：字段名称不能包含以下字符：： .,;'~/*|？”&%$！+=（）[]{}<>'。

由于自定义字段是在组织或集合级别定义的，因此不能将具有相同名称的自定义字段添加到多个进程。

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

系统字段和预定义字段

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

唯一性：字段名称在帐户或项目集合中必须是唯一的。
长度：字段名称必须为 128 个 Unicode 字符或更少。
间距：字段名称不能有前导空格或尾随空格，也不能包含多个连续空格。
组合：字段名称必须至少包含一个字母字符。
禁止的字符：字段名称不能包含以下字符：： .,;'~/*|？”&%$！+=（）[]{}<>'。

由于自定义字段是在组织或集合级别定义的，因此不能将具有相同名称的自定义字段添加到多个进程。

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

自定义字段

由于自定义字段是在组织或项目集合级别定义的，因此不能将具有相同名称的自定义字段添加到多个进程。

添加自定义字段时，请注意以下限制：

每个工作项类型的最大字段数（WIT）： 64
每个进程的最大字段数： 512

字段数据类型确定可存储在字段中的数据的类型和大小。每个字段只能在项目集合中定义一种类型，鼓励在不同项目和工作项类型之间使用通用字段。

将自定义字段添加到继承的过程时，Azure DevOps 将分配一个引用名称， 其前缀为 Custom ，后跟字段名称而不带空格。例如，在引用名称 Custom.DevOpsTriage 中添加名为 DevOps 会审 的字段会导致引用名称 Custom.DevOpsTriage。引用名称中不允许空格。

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

如何确定字段数据类型？

可以通过打开“流程”>“字段”页来查看为组织定义的字段的数据类型。

“组织设置”、“流程”、“字段”页的屏幕截图。

当项目集合使用继承过程模型自定义工作跟踪时，可以通过打开“进程>字段”页来查看字段的数据类型。

“集合设置”、“流程”、“字段”页的屏幕截图。

如果项目集合使用本地 XML 进程模型，则可以通过“工作项”字段索引来确定数据类型。此外，也可以：

打开“工作项字段资源管理器”以查看定义的字段及其属性。
使用 witadmin listfields 命令列出字段属性。

有关详细信息，请参阅本文后面的工作项字段资源管理器和列表字段属性。

查看字段列表

若要查看为组织或集合定义的字段列表，请执行以下步骤：

选择 Azure DevOps 徽标以打开 Projects。然后选择“组织设置”。
选择处理。
选择字段。

列出的字段对应于为组织或集合定义的所有字段，其中包括所有自定义字段和为系统进程定义的字段。

注意

如果未看到“字段”，则表示集合使用本地 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）工具查看它们。

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

属性

属性类型

说明

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：

布尔

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

REST：isPicklistSuggested² WIFE：

布尔

指示字段是否允许用户为选择列表输入自己的值。为 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：

布尔

指示字段是否设置为只读。对于 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 的本地部署有效。有关详细信息，请参阅将报告添加到项目。

有关每个可报告属性的说明，请参阅 “添加或修改工作项”字段以支持报告。

若要查看默认定义的可报告属性的字段列表，请参阅可报告字段引用。

索引字段

使用 witadmin indexfield 命令启用或禁用工作项字段的索引。为字段启用索引可以提高指定该字段的查询的性能。默认情况下，为以下字段编制索引：

分配给
创建日期
更改者
State
原因
地区 ID
迭代 ID
工作项类型

如果在工作项查询中经常添加使用的自定义字段，请考虑为该字段启用索引。有关详细信息，请参阅管理工作项字段 (witadmin)。

列出字段属性

可以使用“字段 - 获取 REST API”列出分配给字段的属性。将 OrganizationName 替换为实际的组织名称。

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

例如，若要列出迭代路径的属性，请使用组织的引用名称System.IterationPathfabrikam：

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

可以使用字段字段 - 获取 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 Analytics 的元数据参考，了解分析元数据和报告功能。

请参阅查询快速参考，快速了解查询语法和用法。
浏览“工作项”字段索引以查看所有可用的工作项字段。
选择项目集合的进程模型，以根据需要选择适当的进程模型。
根据项目的要求修改工作项字段。
使用 witadmin 管理工作项字段来执行高级字段管理任务。
访问 Azure Boards Analytics 的元数据参考，了解分析元数据和报告功能。

通过

列出工作项字段和属性

先决条件

列出或查看字段

字段数据类型和名称

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

字段名

系统字段和预定义字段

自定义字段

如何确定字段数据类型？

查看字段列表

工作项字段资源管理器

字段属性

可报告特性

索引字段

列出字段属性

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

添加和修改字段

反馈

其他资源

通过

列出工作项字段和属性

先决条件

列出或查看字段

字段数据类型和名称

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

字段名

系统字段和预定义字段

自定义字段

如何确定字段数据类型？

查看字段列表

工作项字段资源管理器

字段属性

可报告特性

索引字段

列出字段属性

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

添加和修改字段

相关文章

反馈

其他资源

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

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