定义和修改工作项字段

项目
06/09/2015

使用工作项字段可以跟踪工作项类型的数据、定义查询筛选条件以及生成报告。对于要跟踪、用于定义工作流或要显示在工作项类型窗体中的任何数据元素（Team Foundation Server (TFS) 中的核心系统数据字段除外），必须将其定义为工作项字段。可以在工作项类型或全局工作流的定义中定义工作项字段。

每个团队项目集合维护自己的工作项字段。执行下列任务之一时添加字段：

创建团队项目。将创建在工作项类型或全局工作流的定义中定义的所有字段，以及为选定的过程模板定义的所有字段。对于为团队项目定义的每种工作项类型，系统会自动为其定义核心系统字段。有关这些字段的列表，请参见Visual Studio ALM 的工作项字段参考。
导入工作项类型的定义。工作项类型定义中定义的所有新字段都将添加到该集合中。有关详细信息，请参阅所有 WITD XML 元素引用。
导入全局工作流定义。全局工作流中定义的所有新字段都将添加到该集合中。若要维护一组由多种类型的工作项共享的工作项字段，可以定义全局工作流。有关详细信息，请参阅自定义全局工作流。
将项目集合映射到 Project Web App (PWA) 的实例。安装 Project Server Team Foundation Server 扩展后，通过映射 Team Foundation 的各种组件来配置集成。映射集合时，将导入支持 Project Server 字段中一些字段的全局工作流定义。有关详细信息，请参阅已添加到 TFS 以支持数据同步的 Project Server 字段。

在所有团队项目的所有工作项类型和全局工作流中定义的所有字段构成了为该集合定义的完整字段集合。可以更改现有字段的特性，也可以重命名和删除现有字段。但是，进行这些更改时会产生一些费用。有关详细信息，请参阅自定义工作跟踪对象以支持团队的进程。

若要为集合添加字段或自定义字段，可以修改工作项类型或全局工作流的定义的 XML 内容。通过相应工作项类型或全局工作流定义的 FIELD 节中的 FIELDS 元素定义每个字段。有关该结构和这些文件位置的信息，请参见所有 WITD XML 元素引用和自定义全局工作流。

FIELD（定义）语法结构

每个 FIELD（定义）元素都有一个可选的友好名称和一个必选的引用名称。引用名称在该集合中必须是唯一的。有关详细信息，请参阅工作项跟踪对象的命名约定。

重要

使用 witadmin changefield 命令行工具可更改字段的友好名称。但是，如果重命名字段，则会影响该集合中所有团队项目的所有工作项类型。

按照工作项类型的定义文件中的下列 XML 语法定义字段。

<FIELD name="fieldDisplayName"
   refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID"
   syncnamechanges="true | false"
   reportingname="reportingDisplayName"
   reportingrefname="reportingReferenceName"
   reportable="Dimension | Detail | Measure" 
   formula="sum" >
   <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
   <ALLOWEXISTINGVALUE />
   <CANNOTLOSEVALUE />
   <COPY />
   <DEFAULT />
   <EMPTY />
   <FROZEN />
   <HELPTEXT> . . . </HELPTEXT>
   <MATCH />
   <NOTSAMEAS />
   <PROHIBITEDVALUES /> . . . </PROHIBITEDVALUES>
   <READONLY />
   <REQUIRED />
   <SERVERDEFAULT />
   <SUGGESTEDVALUES /> . . . </SUGGESTEDVALUES>
   <VALIDUSER />
   <WHEN>> . . . </WHEN>
   <WHENNOT> . . . </WHENNOT>
   <WHENCHANGED> . . . </WHENCHANGED>
   <WHENNOTCHANGED> . . . </WHENNOTCHANGED>
</FIELD>

有关详细信息，请参阅FIELD（定义）元素引用。

数据类型

字段的类型定义字段中可存储的数据的种类和大小。字段只能具有团队项目集合中定义的一种类型。此限制促使组织在项目和工作项类型中使用通用字段。

下面的列表显示了受支持的字段类型：

数据类型	描述
DateTime	根据协调世界时 (UTC) 时刻指定日期。通过使用 DateTime 或 FieldControl DateTimeControl 特性将 type 字段添加到工作项窗体中。
Double	指定浮点值。 Double 字段通常用在查询筛选器和结果列表中。通过使用 Double FieldControl 特性将 type 字段添加到工作项窗体中。
GUID	指定将包含一个唯一标识符的字段。您不能向工作项窗体中添加 GUID 字段。
History	支持查看讨论线索和跟踪其他历史记录信息。备注 System.History 字段是使用此数据类型的唯一字段。不能使用此数据类型定义自定义字段。使用支持多格式文本控件的 System.History WorkItemLogControl 特性将 type 字段添加到工作项窗体中。
HTML	支持捕获 RTF 格式数据和使用更长的文本描述（如工作项描述）的功能。 HTML 字段有别于 PlainText 字段，因为 HTML 字段强类型化为 HTML，以便以更丰富的形式显示信息。使用支持多格式文本控件的HTML HTMLControl 特性将 type 字段添加到工作项窗体中。
Integer	指定 32 位有符号整数值。 Integer 字段通常用在查询筛选器和结果列表中。通过使用 Integer FieldControl 特性将 type 字段添加到工作项窗体中。
PlainText	支持输入可包含超过 255 个 Unicode 字符的文本字符串。使用限于纯文本的 PlainText 类型特性或支持多格式文本控件的 FieldControl HTMLControl 特性将 type 字段添加到工作项窗体中。
String	支持输入最多可包含 255 个 Unicode 字符的文本字符串。 String 字段用于标签或者其他最长为一行的短文本字符串。 String 字段通常用在查询筛选器和结果列表中。通过使用 String FieldControl 特性将 type 字段添加到工作项窗体中。
TreePath	指定用于在分层结构或树结构中显示条目的字段，例如显示产品的区域和迭代路径的要求。备注只有 System.AreaPath 和 System.IterationPath 字段使用此数据类型。不能使用此数据类型定义自定义字段。使用 System.AreaPath 特性将 System.IterationPath 和 WorkItemClassificationControl type 字段添加到工作项窗体中。

可报告特性

某些字段值在报告时特别有用。通过使用工作项类型定义语言，您可以指定以下可选特性：

reportable. 将可报告特性设置为 None、Detail、Dimension 或 Measure，具体取决于您是否希望以及希望如何在报表中包含字段。具有此特性的值（None 除外）的字段中的数据将导出到数据仓库，并且可以包括在报告中。

向工作项类型中添加现有字段时，将使用 reportable 特性的当前值。向工作项类型中添加字段时，除非使用 reportable 特性显式指定报告，否则将禁用报告。
reportingname. 为在报表中显示数据时使用的字段分配一个不同的标签。如果未指定值，则将使用为 name 特性分配的友好名称。
reportingrefname. 为将数据导出到关系数据仓库时使用的字段分配一个不同的引用名称。如果您未指定值，则将使用分配给 refname 特性的值。

使用此特性合并或分离报表中包含的字段。若要合并两个具有不同的引用名称且在不同的项目集合中定义的字段，请为这两个字段分配同一 reportingrefname。若要分离两个具有相同的引用名称但在不同的项目集合中定义的字段，请为每个字段分配一个不同的 reportingrefname。

定义字段后，可以在命令提示符处使用 witadmin changefield 命令更改除 refname 特性之外的所有特性的值。

有关出于报告目的而标记字段的最佳做法的信息，请参见添加或修改工作项字段以支持报告。

可报告特性值

如下表所述，您可以向 reportable 特性分配以下值之一：none、dimension、detail 和 measure。

备注

可以在将字段用于工作项之后再为其指定 reportable 属性。设置 reportable 值之后，复制到仓库的工作项的新修订将包含该字段值。但是，对于仓库中的已有修订，则不会使用现有值回填。

特性值	描述
Detail	Detail 类型仅用于 Integer、Double、String 或 DateTime 字段。该字段中的数据会移动到关系仓库数据库的“工作项”和“当前工作项”表中，但不会移动到 SQL Server Analysis Services 多维数据集中。通过将此类型用于无限制的文本字段，您可以在报告中使用这些字段，而不会使多维数据集过大。
Dimension	仅将 Dimension 类型用于 Integer、String 或 DateTime 字段。此字段中的数据将作为工作项维度的特性进入到关系仓库数据库和 Analysis Services 多维数据集，以便可以使用这些数据来筛选报告。将此类型用于包含有效值列表的字段。 dimension 类型的一个典型示例是“工作项类型”。
Measure	Measure 类型仅用于 Integer 和 Double 字段。 Measure 是报告中的数值型的值。在 Analysis Services 多维数据集的处理过程中，设置为 Measure 的字段上的数据将预先计算。例如，“工作项”和“当前工作项”度量值组包含以下字段的累计数据：初始估计、剩余小时数和已完成小时数。有关度量值组的更多信息，请参见Visual Studio 的 Analysis Services 多维数据集中提供的透视和度量值组。指定 Measure 时，必须为 sum 特性指定 formula，以返回在查询中引用的每个度量值的总和。
None	当不希望在报告中包含字段时，请指定 None。此值为默认分配值。

演示如何指定报告的示例

详细信息示例

维度示例

度量值示例

索引字段

使用 witadmin indexfield 命令来对工作项字段启用或禁用索引。为字段启用索引后，查找在查询中指定了该字段的工作项时可提高性能。如果添加了在许多工作项查询中都使用的自定义字段，你可能要为该字段启用索引。有关详细信息，请参阅管理工作项字段 [witadmin]。

FIELD（定义）子元素

可为工作项字段指定许多可选子元素，例如：

帮助文本。定义为工作项窗体中的字段显示的工具提示或帮助信息 (HELPTEXT)。
字段限制。将字段指定为必选、只读、为空、已冻结或匹配特定模式（REQUIRED、READONLY、EMPTY、FROZEN、MATCH）。
字段值自动填充。为字段（DEFAULT、COPY、SERVERDEFAULT）指定一个值。
字段列表. 指定允许值、建议值或禁止值。 (ALLOWEDVALUES, SUGGESTEDVALUES, PROHIBITEDVALUES)
字段条件. 在其他字段已更改或未更改、其他字段具有或不具有特定值时或在其他条件下（WHEN、WHENNOT、WHENCHANGED、WHENNOTCHANGED、CANNOTLOSEVALUE、 NOTSAMEAS），对字段应用一个或多个规则。

有关详细信息，请参阅所有 FIELD XML 元素引用。

系统字段和预定义字段

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

TFS 提供的默认过程模板所定义的预定义字段以 Microsoft.VSTS 开头，然后根据用法进一步进行区分。下面是通常用于计划用途以及用于与 Microsoft Project 集成、与 Team Foundation Build 集成和与 Team Foundation 集成的预定义字段示例：

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

有关为 TFS 提供的默认过程模板定义的所有系统字段和预定义字段的概述，请参见Visual Studio ALM 的工作项字段参考。有关指定字段名称的更多信息，请参见工作项跟踪对象的命名约定。

隐藏的和不可更改的特性以及工作项字段资源管理器

除了可为工作项字段更改的特性外，每个字段还有多个不可更改和几乎隐藏的特性。可以使用工作项字段资源管理器工具来查找这些字段的分配。从过程编辑器增强工具访问“工作项字段资源管理器”工具。

工作项字段资源管理器

备注

过程编辑器增强工具提供了用于自定义 Team Foundation Server 过程模板的图形用户界面。可以使用此工具导入和导出工作项类型、修改过程模板的内容，并浏览为团队项目集合定义的字段集。有关详细信息，请参见 Microsoft 网站上的以下页面：Team Foundation Server 增强工具。

请参见