FIELD(定义)元素

使用 FIELD(定义)元素,可以定义工作项字段和指定应用于它的规则和条件。分配给字段的特性,用于确定字段在工作项表单中的显示方式以及是否可用于包含在报表中。您可以管理团队项目集合的字段分配集。因此,分配给在一种工作项类型中定义的字段的特性必须与集合中的所有团队项目的所有工作项类型相匹配。此外,所有集合中的所有可报告字段导出到数据仓库数据库中。

说明说明

有关您用于定义在状态更改或工作流转换期间的字段的规则和条件的 FIELD(工作流)元素的信息,请参阅 FIELD(工作流)元素

可以您使用 witadmin 命令工具来更改对集合的现有字段进行的特性分配。有关更多信息,请参见管理工作项字段 [witadmin]

架构层次结构

WITD

   WORKITEMTYPE

      FIELDS

            FIELD

<xs:element name="FIELD" type="FieldDefinition" maxOccurs="unbounded"/>

<FIELD name="fieldDisplayName" refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID" syncnamechanges ="true | false" reportable="Dimension | Detail | Measure" formula="sum" reportingname="ReportingDisplayName" reportingrefname="ReportingReferenceName" >
   <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>

特性和元素

以下几节描述了特性、子元素和父元素。

特性

特性

描述

name

必需。工作项查询的下拉菜单中显示的字段的友好名称。友好名称必须对在团队项目中定义的所有字段都唯一。此外,友好名称可能与工作项窗体中的字段旁边显示标签不同。有关更多信息,请参见Control XML 元素引用

特性类型为 typelib:FieldName。最小长度:1;最大长度:128。

模式值:^[^\.\[\]]+$

模式值示例:指派给

refname

必需。具有唯一性的标签,用于标识在团队项目集合中定义的所有其他字段中的字段。

有关友好名称和引用名称的其他要求和限制,请参见工作项跟踪对象的命名约定

特性类型为 typelib:ReferenceFieldName。最小长度:1;最大长度:70。

模式值:^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

模式值示例:公司.问题类型

type

必需。指定字段接受的数据类型。

说明说明
对于具有相同 reportingrefname 的不同项目集合,必须为其中的字段分配相同的 type 值。如果这些值不同,则在处理数据仓库时会可能发生冲突。有关更多信息,请参见解决数据仓库中发生的架构冲突

下表列出了此特性的有效值。

值用法
DateTime 根据协调世界时 (UTC) 时刻指定日期。
Double 指定浮点值。
GUID 指定将包含一个唯一标识符的字段。
History
支持查看讨论线索和跟踪其他历史记录信息。
说明说明
System.History 字段是使用此数据类型的唯一字段。不能使用此数据类型定义自定义字段。
HTML 支持捕获 RTF 格式数据并用于更长的文本描述(如工作项描述)的功能。
Integer 指定 32 位有符号整数值。
PlainText 支持输入可包含超过 255 个 Unicode 字符的文本字符串。
String 支持输入最多可包含 255 个 Unicode 字符的文本字符串。String 字段用于标签或者其他最长为一行的短文本字符串。
TreePath
指定用于在分层结构或树结构中显示条目的字段,例如显示产品的区域和迭代路径所需的字段。若要定义子节点,请参见 创建和修改区域和迭代
说明说明
只有 System.AreaPath 和 System.IterationPath 字段使用此数据类型。不能使用此数据类型定义自定义字段。

syncnamechanges

可选。指定是否将工作项字段用来存储要随着 Active Directory 或一个工作组中所做的更改进行更新的名称。此选项只在 type="String" 时才有效。特性类型为 xs:boolean。

指定 true 启用数据字段同步,指定 false 禁用数据字段同步。

reportable

可选。指定字段中的数据是否可用于包含在报表中。具有默认值 None 的字段既不导出到关系型数据仓库中,也不针对 SQL Server Analysis Services 多维数据集进行处理。有关可报告字段的更多信息,请参见添加和修改工作项字段以支持报告

说明说明
对于具有相同 reportingrefname 值的不同项目集合,必须为其中的字段分配相同的 reportable 值。如果这些值不同,则在处理数据仓库时会可能发生冲突。有关更多信息,请参见解决数据仓库中发生的架构冲突

下表列出了此特性的有效值。

Value 用法
Detail 可以为类型为 DateTime、Double、Integer 或 String 的字段指定。该字段中的数据会移至关系型数据仓库数据库的“工作项”和“当前工作项”表中,但不会移动到 Analysis Services 多维数据集中。此类型非常适合无限制的文本字段,因为您可以在报告中使用这些字段,而不会使多维数据集变大。
Dimension 可以为类型为 DateTime、Double、Integer 或 String 的字段指定。此字段中的数据将作为工作项维度的特性进入到关系仓库数据库和 Analysis Services 多维数据集,以便可以使用这些数据来筛选报告。将此类型用于包含有效值列表的字段。dimension 类型的一个典型示例是“工作项类型”。
Measure measure 类型仅用于 Integer 和 Double 字段。Measure 是报告中的数值型的值。当处理 Analysis Services 多维数据集时,会在 reportable 特性设置为测量的字段上预先计算数据。例如,“工作项”和“当前工作项”度量值组包含以下字段的累计数据:初始估计、剩余小时数和已完成小时数。指定度量值时,必须指定 formula 特性。
None 当您不希望将字段用于包含在报表中时,指定 None。这是默认分配。

formula

可选。measure 可报告类型的聚合类型。唯一有效的值为 sum,其会返回设置上所有值的和。

reportingname

可选。指定在报表中显示的名称。如果您未指定值,则将使用分配给 name 特性的值。

说明说明
对于具有相同 reportingrefname 的不同项目集合,必须为其中的字段分配相同的 reportingname 值。如果这些值不同,则在处理数据仓库时会可能发生冲突。有关更多信息,请参见解决数据仓库中发生的架构冲突

特性类型为 typelib:FieldName。最小长度:1;最大长度:128。

模式值:^[^\.\[\]]+$

模式值示例:指派给

reportingrefname

可选。指定在处理可报告字段时使用的引用名称。如果您未指定值,则将使用分配给 refname 特性的值。

可以使用此特性来合并或分离被处理到数据仓库中的字段。若要合并两个引用名称不同且在不同项目集合中定义的字段,需要为二者分配相同的 reportingrefname。若要分离两个具有相同的引用名称但在不同的项目集合中定义的字段,请为每个字段分配一个不同的 reportingrefname。

您应尽可能合并字段以最大程度地减少仓库中的字段数,并遵循 1024 个可报告字段的最大限制。您可以生成带合并字段的跨组报表。

特性类型为 typelib:ReferenceFieldName。最小长度:1;最大长度:70。

模式值:^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

模式值示例:公司.问题类型

子元素

元素

描述

ALLOWEDVALUES

可选。为此字段定义一个允许值的列表。允许的值指工作项窗体上以及查询生成器中的字段列表中可供选择的值。必须从这些值中选择一个。

ALLOWEXISTINGVALUE

可选。将字段定义为允许使用现有值。此元素允许使用已存在的字段值,即使这些值无效也是如此。所有新的字段值都必须有效。

CANNOTLOSEVALUE

可选。将字段定义为不能丢失值。此元素保留当前的字段值,无法将其清除或留空。

COPY

可选。指定另外一个字段,该字段包含将要复制到当前字段中的值。

DEFAULT

可选。为此字段定义一个默认值。

EMPTY

可选。将此字段定义为空。

FROZEN

可选。将此字段定义为冻结。提交更改后,不能将冻结的字段更改为任何非空值。但是,您可以手动清除此字段,保存工作项,然后指定其他值。

HELPTEXT

可选。定义工具提示中为此字段显示的文本。

MATCH

可选。为此字段定义一个模式,字段值必须与其匹配。

NOTSAMEAS

可选。指定另外一个字段,该字段的值不能与当前字段的值相同。

PROHIBITEDVALUES

可选。为此字段定义一个禁止值的列表。

READONLY

可选。将此字段定义为只读。

REQUIRED

可选。将此字段定义为必需字段。

SERVERDEFAULT

可选。指定将为此字段提供值的服务器组件。

SUGGESTEDVALUES

可选。为此字段定义一个建议值的列表。建议的值指工作项窗体上以及查询生成器中的字段列表中可供选择的值。您可以输入列表中可用值以外的其他值。

VALIDUSER

可选。指定允许值列表必须仅包含系统中的有效用户。

WHEN

可选。指定在另一个字段具有特定值时要应用于当前字段的一个或多个规则。

WHENCHANGED

可选。当特定字段的值发生更改时,将一个或多个规则应用于当前字段。

WHENNOT

可选。当另一个字段没有特定值时,将一个或多个规则应用于当前字段。

WHENNOTCHANGED

可选。当特定字段的值不发生更改时,将一个或多个规则应用于当前字段。

父元素

元素

描述

FIELDS

必需。包含工作项类型字段定义。

备注

FIELD(定义)是 FIELDS(定义)必需的子元素。

minOccurs="1"

可以在同一个团队项目集合中定义不超过 1024 个工作项字段,可以在所有团队项目集合中将不超过 1024 个字段设置为可报告。有关更多信息,请参见添加和修改工作项字段以支持报告

说明说明

向不同工作项类型中添加现有字段时,将使用可报告特性的当前值。

有关字段友好名称和引用名称的其他要求和限制,请参见工作项跟踪对象的命名约定。有关如何标记字段进行报告的信息,请参见添加和修改工作项字段以支持报告

不能定义以前缀 System. 开头的自定义字段。可以通过使用 Microsoft. 前缀定义一个字段,但是,强烈反对这种做法,因为它可能妨碍 Team Foundation Server 功能。

有关字段工作项跟踪对象的概述,请参见使用工作项字段

有关为 Microsoft Solutions Framework (MSF) for Agile Software Development v5.0 过程模板定义的所有系统字段和预定义字段的概述,请参见工作项字段参考 (Visual Studio ALM)

不能对字段引用名称进行重命名。可以使用 witadmin 命令行工具列出字段、重新指定字段友好名称和更改字段特性。有关更多信息,请参见管理工作项字段 [witadmin]

有关如何跨团队项目集合使用字段的信息,请参见解决数据仓库中发生的架构冲突添加和修改工作项字段以支持报告

示例

<FIELD name="Activity" refname="Microsoft.VSTS.Common.Activity" type="String" reportable="dimension">
   <HELPTEXT>Type of work involved</HELPTEXT>
   <SUGGESTEDVALUES>
      <LISTITEM value="Development"/>
      <LISTITEM value="Testing"/>
      <LISTITEM value="Requirements"/>
      <LISTITEM value="Design"/>
      <LISTITEM value="Deployment"/>
      <LISTITEM value="Documentation"/>
   </SUGGESTEDVALUES>
</FIELD>

请参见

参考

管理工作项字段 [witadmin]

概念

工作项跟踪对象的命名约定

工作项字段参考 (Visual Studio ALM)

自定义项目跟踪数据、窗体、工作流及其他对象

使用工作项字段

其他资源

指向工作项类型的 XML 元素定义的索引