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

  • 项目

Azure DevOps Server 2020 |Azure DevOps Server 2019 |TFS 2018

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

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

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

注意

功能可用性： 只能从本地 TFS 中练习某些功能，但如下所示。

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

所需的权限

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

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

添加工作项字段的方法

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

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

  • 创建项目。 将创建在工作项类型或全局工作流的定义中定义的所有字段，以及为选定的过程模板定义的所有字段。 核心系统字段会自动为为项目定义的每个工作项类型定义。 有关这些字段的列表，请参阅 “工作项”字段索引。

  • 导入 WIT 定义。 工作项类型定义中定义的所有新字段都将添加到该集合中。 有关详细信息，请参阅 所有 WITD XML 元素参考。

  • 导入全局工作流定义。 全局工作流中定义的所有新字段都将添加到该集合中。 若要维护一组由多种类型的工作项共享的工作项字段，可以定义全局工作流。 有关详细信息，请参阅 自定义全局工作流。

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

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

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

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

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

Summary of field attributes and field rules

编辑 WIT 定义文件

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

提示

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

或者，可以使用 TFS 团队Project管理器（可从GitHub获取的开源客户端）。

提示

使用 witadmin，可以 导入和导出定义文件。 可以使用的其他工具包括进程编辑器 (要求已安装版本Visual Studio) 。 从Visual Studio市场安装 TFS 进程模板编辑器。 可以使用此版本的进程编辑器修改旧样式的工作项窗体。 不能使用它来编辑与 新 Web 窗体关联的表单。

或者，可以使用 TFS 团队Project管理器（可从GitHub获取的开源客户端）。

必须将要用来跟踪数据的所有字段添加到 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 代码。

自定义字段和选取列表
Custom pick list

<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 组的客户）才能修改“堆栈级别”字段。

<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， forand not field rule attributes
对字符串字段强制实施模式匹配。 MATCH
基于其他字段中的值来有条件地应用规则。 WHEN、 WHENNOT、 WHENCHANGED 和 WHENNOTCHANGED

系统字段的名称以“System” (前缀开头，例如，System.ID) ，其名称都以可以应用于它们的规则进行限制。 例如，不能将用于跟踪创建、更改或关闭工作项或系统使用的日期时间字段的空字段复制或设置为空字段。

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

添加自定义字段

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

  1. 根据所使用的进程模型导出 WIT 定义文件。

  2. 找到以 FIELDS. 开头的 XML 文件的节。

  3. 添加指定要 FIELD 添加的自定义字段名称的元素。 必须指定以下必需属性：友好 name、 refname (引用名称) 和 type。 有关详细信息，请参阅 FIELD (定义) 元素参考。

    以下代码指定自定义字段 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 有关详细信息，请参阅 命名限制和约定。

  4. 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 元素参考。

  5. 根据所使用的进程模型导入 WIT 定义文件。

  6. 打开 Web 门户或团队资源管理器以查看更改。 如果客户端已打开，请刷新页面。

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

    New field in form

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

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

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

  2. 在和FORMLayout部分中，找到要修改的字段的定义。 本示例修改 “标题 ”字段的标签：

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

  3. 更改字段的标签，以便处理此特定项目的葡萄牙分支机构可以在处理工作项表单时读取 标题 字段的名称。 在“标题”字段中包含标题的葡萄牙语一词 Titulo。

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

  4. 导入修改后的 WIT 定义。

添加自定义控件

使用 对象模型跟踪工作项，可以编程方式创建、更改和查找 bug、任务和其他 WIT。 还可以创建你自己的自定义控件，以便将功能添加到工作项窗体。

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

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

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

更改现有字段的特性

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

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

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

Attribute 说明
数据类型 指定字段接受的数据类型。 一般情况下，一旦定义字段数据类型便无法更改。 只能为 HTML 或 PlainText 类型的字段切换字段数据类型。
友好名称 友好名称显示在工作项查询的下拉菜单中，并且必须在项目集合中定义的所有字段中唯一。 友好名称可能与工作项窗体上显示的格式标签不同。
报告特性 可以更改字段在报表中的显示名称、报表引用名称和报告类型。 可以本地化报告友好名称。

报告类型确定字段的数据是被写入关系仓库数据库、同时被写入关系仓库数据库和 OLAP 多维数据集，还是在处理 OLAP 多维数据集时生成预先计算的值的和。

有关默认可报告字段的完整列表，请参阅 可报告字段参考。 有关可报告属性的详细信息，请参阅 “工作项”字段和属性，“可报告属性”。
同步 可以使用 Active Directory 启用或禁用人员名称字段的同步。

更改字段的索引属性

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

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

删除字段

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

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

  2. 确认此字段未在使用中。 例如：

    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

  3. 删除此字段。 例如：

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

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

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

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

其他相关主题或资源：

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

多个 WIT 包含提供由自动化过程生成的信息的字段，这些过程与 Team Foundation Build、Microsoft 测试管理器和 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 多维数据集中查找字段，因为这些字段按逻辑分组到各个文件夹中。 若要了解详细信息，请参阅 “添加或修改工作项”字段以支持报告。