添加或修改字段以跟踪工作

项目
04/04/2024

Azure DevOps Server 2022 - Azure DevOps Server 2019

项目包含 100 个或多个数据字段，具体取决于用于创建项目的过程，例如敏捷、基本、Scrum 或 CMMI。每个工作项都与工作项类型 (WIT) 相关联，可以跟踪的数据对应于分配给 WIT 的字段。通过修改工作项中的数据字段来更新工作项的数据。

注意

对于 Azure DevOps Services 或使用继承的进程模型的项目集合，请参阅向工作项类型添加自定义字段。

可以修改现有字段或添加自定义字段以支持跟踪其他数据要求。例如，可以在下拉菜单中自定义选取列表，或添加规则来指定默认值或限制可能需要的值。

并非所有选取列表都以相同的方式定义。某些列表通过用户界面、WIT 的工作流或向项目添加用户帐户来定义，如下表所示。

WIT 定义	命令行更改（本地 XML 进程）
- 自定义选取列表 - 向字段添加规则 - 添加自定义字段 - 更改窗体上的字段标签 - 添加自定义控件	- 列出字段 - 更改字段属性 - 删除字段 - 为字段编制索引

先决条件

若要列出字段，您必须对集合集中的项目具有“允许”的“查看项目级信息”权限。
若要添加或自定义字段，您必须是项目管理员组的成员，或者将 “编辑项目级信息”权限 设置为“允许”。
若要删除或重命名字段或更改字段的属性，您必须是 Team Foundation Administrators 安全组或 Project Collection Administrators 安全组的成员。

若要以管理员身份添加，请更改项目集合级权限。

添加工作项字段的方法

使用工作项字段跟踪工作项类型的数据，并定义查询的筛选条件以及生成报表。除要跟踪的系统字段之外，任何数据元素都必须定义为工作项字段。可以在工作项类型或全局工作流的定义中定义工作项字段。

为项目集合维护工作项字段。执行以下任务之一时，添加字段：

创建项目。在工作项类型或全局工作流的定义中定义的所有字段，以及为所选进程模板定义的所有字段。核心系统字段会自动为为项目定义的每个工作项类型定义。有关这些字段的列表，请参阅 “工作项”字段索引。
导入 WIT 定义。在定义中为工作项类型定义的所有新字段都会添加到集合中。有关详细信息，请参阅所有 WITD XML 元素参考。
导入全局工作流定义。全局工作流中定义的所有新字段都会添加到集合中。如果要维护多种类型的工作项共享的工作项字段集，请定义全局工作流。有关详细信息，请参阅自定义全局工作流。

所有 WIT 和所有项目的全局工作流中定义的所有字段构成了集合中定义的完整字段集。可以更改、重命名和删除现有字段的属性。但是，在进行此类更改时会产生某些费用，特别是针对本地服务器和报告。

若要添加或自定义集合的字段，请修改 WIT 定义的 XML 内容。通过 WIT 定义的 FIELDS 部分内的 FIELD 元素定义每个字段。有关这些文件的结构和位置的信息，请参阅 “所有 FIELD XML 元素”参考。

添加字段、应用规则或更改属性

若要添加自定义域、添加字段规则或更改工作项窗体上字段的标签，请修改使用该字段的工作项类型（WIT）或类型。遵循与进程模型匹配的自定义序列。

若要更改字段属性或重命名字段，请使用 witadmin 命令行工具。否则，若要修改字段，可以添加或修改与 WIT 定义中的字段关联的规则。

字段属性和字段规则的摘要

编辑 WIT 定义文件

若要添加规则或添加自定义字段，请导出、编辑，然后导入 WIT 定义文件。

提示

使用 witadmin，可以导入和导出定义文件。可以使用的其他工具包括进程编辑器 (要求你已安装 Visual Studio) 版本。从 Visual Studio Marketplace 安装进程模板编辑器。

要用于跟踪数据的任何字段都必须添加到 WIT 定义文件中。对于所有系统字段（引用名称以 System 开头的字段）都是如此。所有系统字段都为所有 WIT 定义定义，无论是否在 WIT 定义中包含它们。有关每个字段的详细信息，请参阅 “工作项”字段索引。

添加复选框或布尔字段

使用以下语法在 WIT 定义的 FIELDS 节中添加布尔字段。

<FIELD name="Triage" refname="Fabrikam.Triage" type="Boolean" >
   <DEFAULT from="value" value="False" />
   <HELPTEXT>Triage work item</HELPTEXT>
</FIELD>

然后在 FORM 节中添加以下语法，使字段显示在窗体上。

<Control Label="Triage" Type="FieldControl" FieldName="Fabrikam.Triage" />

该字段将显示为窗体上的复选框。

自定义选取列表

选取列表是在工作项窗体的下拉菜单和 查询编辑器中的“值 ”列中显示的枚举值。用于自定义选取列表的方法因字段而异。

若要修改工作项窗体中大多数字符串或整数字段的选取列表，请编辑 WIT 定义。例如，若要添加自定义解析字段和选取列表，请指定如下所示的 XML 代码。

自定义字段和选取列表
自定义选取列表

<FIELD name="Resolution" refname="MyCompany.Resolution" type="String">    
<ALLOWEDVALUES>
<LISTITEM value="By Design" />
<LISTITEM value="Duplicate" />
<LISTITEM value="External" />
<LISTITEM value="Fixed" />
<LISTITEM value="Not Repro" />
<LISTITEM value="Postponed" />
<LISTITEM value="Won't Fix" />
</ALLOWEDVALUES>
</FIELD>

规则支持组合列表、限制列表应用的人员，以及设置工作项窗体上列表显示时的条件。规则控制是展开通讯组列表以显示其单个成员，还是使用可选的 expanditems 和 filteritems 属性筛选列表。使用全局列表将更新跨 WIT 或项目共享的列表所需的工作降到最低。

在多个 WIT 或多个项目中使用列表时，将其作为全局列表进行维护会最大程度地减少维护要求。此外，如果需要使列表部分在 WIT 或项目中显示为不同，则可以为选取列表的一部分定义全局列表。请参阅“ 定义选取列表 ”和 “定义全局列表”。

向字段添加规则

若要添加自定义域或向字段添加规则，请编辑 WIT 定义。可以限制应用于特定用户或组的规则。大多数规则都支持关注规则的用途和不适用于的属性。

例如，通过以下代码片段，可以强制实施规则，即只有管理团队的成员（客户定义的 TFS 组）可以在创建工作项后修改 Stack Rank 字段。

<FIELD name="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">  
   <FROZEN not="[project]\Management Team" />  
   <HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
</FIELD>

应用规则来完成以下操作：

若要完成此操作，请执行以下操作：	使用此 XML 元素：
指定工具提示。	HELPTEXT
限定字段可以具有的值。	CANNOTLOSEVALUE、 EMPTY、 FROZEN、 NOTSAMEAS、 READONLY 和 REQUIRED
复制值或指定默认值。	COPY、 DEFAULT 和 SERVERDEFAULT
限制可以修改字段的人员。	VALIDUSER， for and not field rule attributes
对字符串字段强制实施模式匹配。	MATCH
根据其他字段中的值有条件地应用规则。	WHEN、 WHENNOT、 WHENCHANGED 和 WHENNOTCHANGED

系统字段的名称以“系统”前缀（例如，System.ID）开头，其名称在可以应用于它们的规则方面受到限制。例如，不能复制或设置为空字段，用于跟踪创建、更改或关闭工作项的人员或系统使用的日期时间字段。

有关应用字段规则和限制的详细信息，请参阅规则和规则评估。

添加自定义字段

若要添加自定义字段，请编辑 WIT 定义以在 FIELDS 节中添加 FIELD 元素，并在 FORM 节中添加 Control 元素。

根据所使用的进程模型导出 WIT 定义文件。
找到以 . 开头 FIELDS的 XML 文件的节。
FIELD添加指定要添加的自定义字段名称的元素。必须指定以下必需属性：友好 name属性、 refname （引用名称）和 type。有关详细信息，请参阅 FIELD （Definition）元素参考。

以下代码指定自定义字段 Requestor，其中包含允许值的引用名称和 FabrikamFiber.MyTeam.Requestor 选取列表，默认值为 Customer。
```
<FIELD name="Requestor" refname="FabrikamFiber.MyTeam.Requestor" type="String" reportable="Dimension">
   <ALLOWEDVALUES>
      <LISTITEM value="Customer" />
      <LISTITEM value="Executive Management" />
      <LISTITEM value="Other" />
      <LISTITEM value="Support" />
      <LISTITEM value="Team" />
      <LISTITEM value="Technicians" />
      <DEFAULTVALUE value="Customer" />
    </ALLOWEDVALUES>
</FIELD>
```
提示

无论如何在 XML 定义文件中输入元素，列表中的元素始终以字母数字顺序显示。引用名称，或者 refname，是字段的编程名称。所有其他规则都应引用。refname 有关详细信息，请参阅命名限制和约定。

Control添加节中的FORM元素，以便自定义字段显示在希望显示的元素组中的窗体上。

例如，以下代码片段将请求者字段添加到工作项窗体的“原因”字段下方。

<Column PercentWidth="50">
   <Group Label="Status">
      <Column PercentWidth="100">
         <Control FieldName="System.AssignedTo" Type="FieldControl" Label="Assi&amp;gned To:" LabelPosition="Left" />
         <Control FieldName="System.State" Type="FieldControl" Label="&amp;State:" LabelPosition="Left" />
         <Control FieldName="System.Reason" Type="FieldControl" Label="Reason:" LabelPosition="Left" ReadOnly="True" />
         <Control FieldName="FabrikamFiber.MyTeam.Requestor" Type="FieldControl" Label="Requestor:" LabelPosition="Left" ReadOnly="True" />
      </Column>
   </Group>
</Column>

提示

工作跟踪的 FORM 架构定义将元素的所有子元素定义为 camel 大小写，所有其他元素都定义为大写。如果在验证类型定义文件时遇到错误，请检查元素的大小写结构。同时，根据 XML 语法规则，开始标记与结束标记的大小写结构还必须匹配。有关详细信息，请参阅 Control XML 元素参考。

根据所使用的进程模型导入 WIT 定义文件。
打开 Web 门户或团队资源管理器以查看更改。如果客户端已打开，请刷新页面。

下图显示了产品积压工作项的工作项窗体现在包含新字段。

更改工作项窗体上的字段标签

若要修改字段标签，请更改分配给 Control 元素 Label 属性的值。若要从工作项窗体中删除字段，请删除 Control 与该字段关联的元素。

根据进程模型导出 WIT 定义文件。

FORM在和Layout部分中，找到要修改的字段的定义。此示例修改标题字段的标签：

<Column PercentWidth="70">  
   <Control Type="FieldControl" FieldName="System.Title" Label="Title" LabelPosition="Left" />  
</Column>

更改字段的标签，以便处理此特定项目的葡萄牙分支机构可以在处理工作项表单时读取“标题”字段的名称。在“标题”字段中包括标题（Titulo）的葡萄牙语单词。
```
<Column PercentWidth="70">  
   <Control Type="FieldControl" FieldName="System.Title" Label="Title (Titulo):" LabelPosition="Left" />  
</Column>
```
导入修改后的 WIT 定义。

添加自定义控件

使用 REST API 跟踪工作项，可以编程方式创建、更改和查找 bug、任务和其他 WIT。还可以创建自己的自定义控件，用于向工作项窗体添加功能。

或者，可以添加可通过 Visual Studio Marketplace 提供的自定义控件。例如：

通过显示复选框列表，支持字段的多个值的输入的多值控件
支持添加颜色以选取列表项的颜色选取列表控件
工作项表单一键式操作，该操作为组扩展提供了一组可自定义的规则，这些规则支持一键式操作。

若要向新的 Web 窗体添加自定义控件，请参阅 WebLayout 和 Control 元素。

更改现有字段的属性

使用 witadmin changefield 更改现有字段的属性。例如，以下命令将 MyCompany.Type 定义的友好名称更改为评估方法。

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.Type /name:"Evaluation Method"

下表汇总了可以使用 witadmin changefield 更改的属性。

属性	说明
Data type	指定字段接受的数据类型。一般情况下，定义字段数据类型后无法更改。只能为 HTML 或 PlainText 类型的字段切换字段数据类型。
友好名称	友好名称显示在工作项查询的下拉菜单中，并且它必须在项目集合中定义的所有字段中是唯一的。友好名称可能与工作项窗体上显示的窗体标签不同。
报告属性	可以在报表中显示的字段名称、报表引用名称和报告类型中更改字段的名称。可以本地化报告友好名称。报告类型确定字段的数据是写入关系仓库数据库，还是写入关系仓库数据库和 OLAP 多维数据集，或者在处理 OLAP 多维数据集时生成预先计算的值总和。有关默认可报告字段的完整列表，请参阅可报告字段参考。有关可报告属性的详细信息，请参阅“工作项”字段和属性，“ 可报告属性”。
同步	可以使用 Active Directory 启用或禁用人员名称字段的同步。

更改字段的索引属性

可以为字段启用索引编制，以便在对字段进行筛选时改善查询响应时间。默认情况下，将为以下字段编制索引：“指派给”、 “创建日期”、“更改者”、“状态”、“原因”、“区域 ID”、“迭代 ID”和“工作项类型”。

若要启用或禁用字段的索引编制，请使用 witadmin indexfield 命令。

删除字段

从特定类型的工作项中删除字段时，该字段不会从集合或数据库服务器中删除，即使该字段不再被任何 WIT 引用。若要删除字段，请执行以下步骤。

FIELD从所有 WIT 定义和引用它的任何全局工作流中删除定义。

验证该字段是否未使用。例如：

witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomContact

Field: MyCompany.CustomContact
Name: Custom Contact
Type: String
Reportable As: dimension
Use: Not In Use
Indexed: False

删除字段。例如：

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomContact

如果已删除的字段可报告，并且项目使用 SQL Server Reporting Services，请重新生成数据仓库以清除旧字段及其值。

有关详细信息，请参阅 “管理工作项”字段。

测试、生成和版本控制字段

多个工作项类型包含字段，这些字段提供由与 Team Foundation Build、Microsoft Test Manager 和 Team Foundation 版本控制集成的自动化流程生成的信息。若要将其中一个字段添加到自定义 WIT，请根据本主题前面概述的步骤编辑 WIT 定义。

例如，可以添加“生成”字段中出现的“查找输入”和“集成”字段，这些字段显示在 bug 的类型定义中。这些字段将 Bug 与发现或修复这些 Bug 的生成关联。可以使用以下代码片段将这些字段添加到工作项类型定义。

<FIELD name="Found In" refname="Microsoft.VSTS.Build.FoundIn" type="String" reportable="dimension">
    <HELPTEXT>Product build number (revision) in which this item was found</HELPTEXT>
</FIELD>
<FIELD name="Integration Build" refname="Microsoft.VSTS.Build.IntegrationBuild" type="String" reportable="dimension">
    <HELPTEXT>Product build number this bug was fixed in</HELPTEXT>
</FIELD>

有关详细信息，请参阅基于生成和测试集成字段的查询。

字段名称和报告

可以添加字段或更改现有字段的属性以支持报告。添加或更改字段时，应系统地命名字段，以便可以在 Analysis Services 多维数据集中找到字段，因为字段在逻辑上分组到文件夹中。有关详细信息，请参阅 “添加或修改工作项”字段以支持报告。

本文介绍了如何添加和自定义托管 XML 和本地 XML 进程模型的字段。有关添加和自定义托管 XML 和本地 XML 进程模型的工作项类型的信息，请参阅 “添加或修改工作项类型”。有关继承进程模型，请参阅 “自定义进程”。

其他相关主题或资源：

通过

添加或修改字段以跟踪工作

先决条件

添加工作项字段的方法

添加字段、应用规则或更改属性

编辑 WIT 定义文件

添加复选框或布尔字段

自定义选取列表

向字段添加规则

添加自定义字段

更改工作项窗体上的字段标签

添加自定义控件

更改现有字段的属性

更改字段的索引属性

删除字段

测试、生成和版本控制字段

字段名称和报告

反馈

其他资源

通过

添加或修改字段以跟踪工作

先决条件

添加工作项字段的方法

添加字段、应用规则或更改属性

编辑 WIT 定义文件

添加复选框或布尔字段

自定义选取列表

向字段添加规则

添加自定义字段

更改工作项窗体上的字段标签

添加自定义控件

更改现有字段的属性

更改字段的索引属性

删除字段

测试、生成和版本控制字段

字段名称和报告

相关文章

反馈

其他资源