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

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

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

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

工作项字段用于跟踪信息。 字段是为集合定义的,并在为该集合定义的所有项目中共享。 若要查看为集合定义的所有字段,可以使用 工作项字段资源管理器 工具,这是 Visual Studio 的插件。

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

先决条件

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

列出或审阅字段

若要列出或查看字段,可以根据所使用的进程模型(继承、托管 XML 或本地 XML)使用以下工具之一。 有关默认进程中定义的字段的索引,请参阅 工作项字段索引

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

注意

  1. 仅支持敏捷、CMMI、Scrum) (默认进程。

字段数据类型和名称

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

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

  • 数据类型:指定可输入到字段中的数据类型,例如布尔值、Double、Integer、HTML 和 String。 有关每种数据类型的说明,请参阅 查询字段、运算符和宏
  • 友好名称:指定分配给字段的名称,以及你在查询子句中为 Field 选择的名称。 此名称可能与工作项窗体上显示的名称不同。
  • 引用名称:指定在创建 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 命令列出字段属性。 有关详细信息,请参阅本文后面的 工作项字段资源管理器列表字段属性

可以通过 “工作项”字段索引查找数据类型。 或者,可以打开“工作项字段资源管理器”以查看定义的字段及其属性分配,或使用 witadmin listfields 命令列出字段属性。 有关详细信息,请参阅本文后面的 工作项字段资源管理器列表字段属性

“处理>字段”网页

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

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

    “选择组织设置”的屏幕截图。

  2. 然后选择“ 处理”。

    “选择进程”的屏幕截图。

    注意

    如果未看到 “进程”,则使用的是 TFS-2018 或更早版本。 不支持 “进程 ”页。 必须使用 本地 XML 进程模型支持的功能。

  3. 然后,选择 “字段”。

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

    创建所选继承进程的副本的屏幕截图。

    注意

    如果未看到 “字段”,则集合使用本地 XML 进程。 该过程不支持“字段”页。

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

工作项字段资源管理器

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

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

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

字段属性

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

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

Attribute

属性类型

说明


REST:
WIFE: AllowedValues

collection

获取包含选择列表值的字段的有效值的集合。 可以通过指定选择列表或全局列表 (本地) 来更改此设置。
可以更改?=是

REST: canSortBy
妻子: CanSortBy

boolean

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

REST: 说明
WIFE: HelpText

字符串

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

REST:
妻子: ID

整数

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

REST:
妻子: IsCloneable

boolean

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

REST:
妻子: IsComputed

boolean

指示此字段设置的值是否由系统计算 (True) ,或者不 (False) 。 计算字段的示例包括系统设置的字段,例如 ID修改日期更改日期外部链接计数
可以更改?=否

REST:
妻子: IsCoreField

boolean

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

REST:
妻子: IsEditable

boolean

指示用户是否可以修改此字段 (true) 或不 (False) 。 不可编辑字段的示例是系统设置的字段,例如 IDRevisionCreated ByChanged By 字段
可以更改?=否

REST: isIdentity
妻子: IsIdentity

boolean

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

REST:
妻子: IsIndexed1

boolean

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

REST:
妻子: IsLongText

boolean

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

REST: isPicklist2 妻子:

boolean

指示字段是否与选择列表相关联。 如果为 Azure DevOps 和 Picklist 定义了自定义字段,则该值设置为 True , (字符串) 或选择列表 (选择了整数) 类型。 对于定义选择列表的继承字段,该值设置为 False
可以更改?=否

REST: isPicklistSuggested2 妻子:

boolean

指示字段是否允许用户为选择列表输入自己的值。 如果为 Azure DevOps 定义了自定义字段、选择列表 (字符串) 或选中“选择列表 (整数) 类型”,并且选中了“允许用户设置自己的值”复选框,则该值设置为 True
可以更改?=是

REST: isQueryable
WIFE: IsQueryable

boolean

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

REST:
妻子: IsReportable 3

boolean

指示是定义可报告属性还是设置为除 None 以外的任何属性。 对于本地环境,可以更改此属性。
可以更改?=是

REST:
WIFE: IsUsedInGlobalWorkflow

boolean

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

REST:
妻子: IsUserNameField

boolean

指示字段是否用于显示 Identity 字段。
可以更改?=否

REST: name
妻子: 姓名

字符串

分配给字段的友好名称。 不能为 Azure DevOps 更改友好名称,但可以使用 witadmin changefield 命令为本地更改。
只能更改?=只能更改本地

REST: picklistId
WIFE: HelpText

GUID

如果字段是一个选择列表,则为关联的选择列表的标识符,否则为 null。 为 Azure DevOps 和 Picklist 定义自定义字段时,将分配唯一 GUID 值, (字符串) 或选择列表 (整数) 类型。
可以更改?=否

REST:
WIFE: ProhibitedValues

collection

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

REST: readOnly
妻子:

boolean

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

REST: referenceName
WIFE: ReferenceName

字符串

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

REST:
WIFE: ReportingAttributes3

指定 “详细信息”、“ 维度”或“ 度量值”,具体取决于是否以及希望字段包含在报表中的方式。 对于此属性,其 值为 None 以外的 字段的数据将导出到数据仓库,并且可以包含在 SQL 报表中。
只能更改?=只能更改本地

REST:
WIFE: ReportingName3

字符串

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

REST:
WIFE: ReportingReferenceName3

string

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

REST: supportedOperations
妻子:

set

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

REST:
WIFE: SupportsTextQuery

boolean

指示字段是否支持文本查询,如 包含字词不包含单词
可以更改?=否

REST:
WIFE: SystemType

string

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

REST: 类型
WIFE: FieldType

字符串

指定字段的数据类型,如 布尔值、 DateTimeIntegerString 等。 有关完整列表和说明,请参阅 查询字段、运算符和宏
可以更改?=否

REST: 使用情况
妻子: 用法

字符串

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

注意

  1. 对于本地部署,可以为字段启用索引,以便在筛选字段时缩短查询响应时间。 有关详细信息,请参阅本文后面的 索引字段
  2. isPicklistisPicklistSuggested 属性仅分配给为继承进程定义的自定义字段。 Azure DevOps Server 2019 及更高版本支持继承的进程模型。 若要了解详细信息,请参阅 继承的进程模型
  3. 所有报告属性仅对项目配置为支持SQL Server报告和SQL Server Analysis Services的本地部署有效。

可报告特性

所有报告属性仅对项目配置为支持SQL Server报告和SQL Server Analysis Services的本地部署有效。 有关详细信息,请参阅 将报表添加到项目

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

有关默认定义了可报告属性的字段的列表,请参阅 可报告字段引用

索引字段

可以使用 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 参数指示每个项目的名称以及使用该字段的工作项类型。

项目集成和项目字段映射

您可以更改工作跟踪字段映射到 Project 中的字段的方式,也可以更改特定字段的发布方式。 请参阅 [Microsoft 项目字段映射文件] (/previous-versions/azure/devops/reference/xml/customize-project-field-mapping-file。

添加和修改字段

若要将字段添加到流程,请将它们添加到一个或多个工作项类型。 若要了解详细信息,请参阅 自定义继承过程

可以添加或修改 WIT 中包含的字段,也可以添加自定义 WIT。 若要了解更多信息,请参阅以下文章:

可以使用 witadmin 命令行工具更改除系统字段以外的任何字段的字段名称、索引和报表属性。 有关详细信息,请参阅 管理工作项 fields-witadmin

若要向项目添加字段,请将其添加到一个或多个工作项类型。 请参阅 添加或修改字段以跟踪工作

可以使用 witadmin 命令行工具更改除系统字段以外的任何字段的字段名称、索引和报表属性。 有关详细信息,请参阅 管理工作项 fields-witadmin