通过

管理工作项字段 [witadmin]

  • 项目

你可以通过使用以下 witadmin 命令管理为团队项目集合定义的工作项类型字段：

  • changefield：更改字段的一个或多个特性。 更改以下某个特性时，你可以为团队项目集合内的所有工作项类型和团队项目更改它：

    • PlainText 或 HTML 字段的数据类型。

      重要

      当你将 Team Foundation Server 从早期版本升级至当前版本时，“说明”(System.Description) 字段的类型赋值将自动从 PlainText 转换为 HTML。使用 changefield 命令，你可以将此字段的内容还原为显示纯文本。

    • 在工作项查询中显示的友好名称。 此名称可能与工作项窗体上显示的名称不同。

    • 报告特性，包括字段在报告中的显示名称、报告引用名称和报告类型。

    • 与 Active Directory 同步 - 你可以启用/禁用人名字段的同步。

  • deletefield：删除指定的字段。

  • indexfield：为指定的字段打开或关闭索引。 为字段启用索引后，查找在查询中指定了该字段的工作项时可提高性能。 如果添加了在许多工作项查询中都使用的自定义字段，你可能要为该字段启用索引。

  • listfields：列出所有字段或指定字段的特性。

若要运行 witadmin 命令行工具，请在安装了 Visual Studio 或团队资源管理器的情况下打开命令提示符窗口，然后输入：

cd %programfiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

在 32 位版本的 Windows 上，将 %programfiles(x86)% 替换为 %programfiles%。

有关在随 Team Foundation Server 提供的默认过程模板中定义的字段的概述，请参见Visual Studio ALM 的工作项字段参考。

备注

进程编辑器是 Visual Studio 的一个增强工具，你可以使用该工具创建和修改工作项字段。此工具不受支持。有关更多信息，请参见 Microsoft 网站上的以下页面：Team Foundation Server 增强工具。

要求

  • 要列出字段，你必须将集合中团队项目的**“查看项目级信息”权限设置为“允许”**。

  • 要删除或重命名字段或更改字段的特性，你必须是**“Team Foundation 管理员”安全组或“项目集合管理员”**安全组的成员。

有关详细信息，请参阅Team Foundation Server 权限参考。

备注

即使你以管理权限登录，也必须打开提升的命令提示符窗口，以在运行 Windows Server 2008 的服务器上执行此功能。若要打开提升的命令提示符窗口，请选择“开始”，打开“命令提示符”快捷菜单，然后选择“以管理员身份运行”。有关详细信息，请参见 Microsoft 网站：用户访问控制。

witadmin changefield /collection:CollectionURL /n:RefName    [/name:NewName]     [/syncnamechanges:true | false]    [/reportingname:ReportingName]     [/reportingrefname:ReportingRefName]    [/reportingtype:Type]    [/reportingformula:Formula]    [/type:PlainText | HTML]    [/noprompt]

witadmin deletefield /collection:CollectionURL /n:RefName [/noprompt]

witadmin indexfield /collection:CollectionURL /n:Name /index:on|off 

witadmin listfields /collection:CollectionURL /n:RefName [/unused]

参数

参数

描述

/collection:CollectionURL

指定团队项目集合的 URI。 URI 的格式如下：http://ServerName:Port/VirtualDirectoryName/CollectionName

如果未使用虚拟目录，则 URI 将为以下格式：

http://ServerName:Port/CollectionName

/n:RefName

/n:Name

工作项类型字段的引用名称。

/index

指定为特定的字段启用或禁用索引。 指定 on 以启用索引，指定 off 以禁用索引。

/name:NewName

指定字段的新名称。

/syncnamechanges

指定使用工作项字段来存储名称，并在 Active Directory 或某个工作组中做出更改后进行更新。 仅当为 typename 指定了带字符串数据类型的字段时，此选项才有效。

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

/reportingname:ReportingName

在将用于报告的数据仓库中，指定字段的名称。

/reportingrefname:ReportingRefName

在数据仓库中指定将用于报告的字段的引用名称。

/reportingtype:Type

指定如何在仓库中使用该字段以用于报告。 以下为有效值：

  • dimension: 用于 Integer、String 或 DateTime 字段。

  • detail: 用于 Integer、Double、String 或 DateTime 字段。

  • measure: 用于 Integer 和 DateTime 字段。 默认的聚合类型是求和。 你可以使用 formula 参数指定其他聚合类型。

  • none: 用于禁用字段的可报告性。

有关详细信息，请参阅定义和修改工作项字段。

/reportingformula:Formula

指定在字段报告为 measure 时要使用的聚合公式。 唯一支持的公式为 sum。

/type:HTML | PlainText

指定将字段的内容从 PlainText 转换为 HTML 或从 HTML 转换为 PlainText。 你可以仅为类型赋值为 PlainText 或 HTML 的字段指定此选项。 请参阅FIELD（定义）元素引用。

/unused

列出未由团队项目集合中定义的任何团队项目使用的字段。

/noprompt

禁用请求确认的提示。

/? or help

在“命令提示符”窗口中显示有关命令的帮助。

备注

索引字段

查询索引是基于那些已启用索引的字段创建的。 当运行包含索引字段的查询时，此索引可缩短响应时间。

默认情况下，将为以下字段编制索引：“指派给”、 “创建日期”、“更改者”、“状态”、“原因”、“区域 ID”、“迭代 ID”和“工作项类型”。 如果存在你的团队在查询中常用的其他字段，你可以将它们添加到查询索引。

将人名与 Active Directory 同步

你必须手动启用任何用于指定引用 Active Directory 的人名的自定义工作项字段的同步。 你必须为包含自定义字段的每个团队项目集合的每个字段启用同步。

显示人名的所有系统引用字段均已将特性 syncnamechanges 设置为 true。这些字段包括 System.AuthorizedAs、System.AssignedTo、System.ChangedBy 和 System.CreatedBy。已为在某个默认过程模板中定义的所有人名字段启用同步。 有关详细信息，请参阅工作分配和工作流字段引用。

在启用同步后，该字段不再显示静态字符串。 而是显示与用户帐户关联的名称。 当你在 Active Directory 或工作组中更改用户名称时，syncnamechanges 设置为 true 的字段将自动显示新名称。

当你将 syncnamechanges 特性分配给字符串字段时，该字段将始终接受有效的用户名。 但是，如果以下任一条件为 true，该字段不允许存储在 Team Foundation Server 或 Active Directory 中的组名称：

  • VALIDUSER 规则是跨所有工作项类型指定的

  • VALIDUSER 规则是针对某个工作项类型指定的

  • ALLOWEDVALUES 规则是针对某个工作项类型指定的，并且该规则具有排除组的筛选条件

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

你可以为每个工作项类型更改的特性

你可以通过更改字段在其中显示的工作项类型定义，更改为字段定义的特性或值：

示例

除非另外指定，否则在每个示例中应用下面的值：

  • 团队项目集合的 URI：http://AdventureWorksServer:8080/tfs/DefaultCollection

  • 工作项字段名称：AdventureWorks.Field

  • 默认编码：UTF-8

列表字段

使用 witadmin listfields 查看正在使用的字段集，并选择一个来添加到工作项类型。 此外，你可以列出为特定字段定义的特性赋值并确定由团队项目使用的字段。

查看工作项字段的特性

  • 输入以下命令以列出为特定字段定义的特性，例如 Microsoft.VSTS.Common.Issue。

    witadmin listfields /collection:http://AdventureWorksServer: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 参数指示每个项目的名称和使用字段的工作项类型。 有关字段特性的详细信息，请参见Visual Studio ALM 的工作项字段参考。

列出团队项目集合中的所有字段

  • 输入以下命令以列出为团队项目集合定义的所有字段。

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection

    将显示命名项目集合的所有字段的字段信息。 请参阅Visual Studio ALM 的工作项字段参考。

列出未被使用的字段

  • 输入以下命令来列出团队项目中不再由任何工作项类型使用的字段。

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /unused

    为每个未被使用的字段显示的字段和特性信息，如本示例所示。

    Field: Microsoft.VSTS.CMMI.TaskType
Name: Task Type
Type: String
Reportable As: dimension
Use: Not In Use
Indexed: False

Field: Microsoft.VSTSUE.Common.Flag
Name: Flag
Type: String
Reportable As: dimension
Use: Not In Use
Indexed: False

Field: Microsoft.VSTSUE.Common.Progress
Name: Progress
Type: String
Reportable As: dimension
Use: Not In Use
Indexed: False

重命名字段

你可以更改工作项字段的友好名称以符合团队使用的命名约定。 请注意，新名称将应用于引用项目集合中所有团队项目的已更改字段的所有工作项类型。 在你定义工作项查询中的筛选条件时，将显示友好名称。 工作项窗体上显示的名称可能不同于为该字段定义的友好名称。

重命名工作项字段

  1. 输入以下命令来将分配给 Microsoft.VSTS.Common.Rank 的友好名称重命名为“重要级别”。

    witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Rank /name:"Important Rank"

  2. 在确认提示下，键入 y，然后按 Enter。 请等待，直到你收到以下消息：

    Field renamed.

验证导入到单个项目的更改

  1. 在 团队资源管理器 中，选择 刷新“刷新”。

    将从服务器下载最新更新，包括你刚刚对字段名称进行的更改。 请等待几秒钟，以便完成刷新。

  2. 选择**“新建查询”**来创建查询。

  3. 在查询编辑器中，选择**“单击此处以添加子句”链接来添加行，选择空白“字段”**单元格，然后在该单元格中键入“级别”。 下面的消息显示在结果列表的上方。 此消息指示无法找到“级别”。

    运行查询以查看查询结果。 TF51005：查询引用的字段不存在。 该错误是由 <<Rank>> 引起的。

  4. 从**“字段”**单元格删除值“级别”，然后在该单元格中键入“重要级别”。

  5. 选择**“运算符”单元格中的“<>”，然后在“值”**单元格中键入 1。

  6. 在**“查询”工具栏上，选择 运行查询（团队资源管理器）“运行”**。

  7. 打开结果中任意行的快捷菜单，然后选择**“列选项”。 在“可用列”列表中向下滚动。 请注意“级别”字段不再存在，但是“重要级别”**字段存在。

  8. 在**“可用列”框中选择“重要级别”，然后选择“>”按钮（添加选定的列）。 选择“确定”**。

    请注意，在所有的查询生成器和结果列表中，Microsoft.VSTS.Common.Rank 的友好名称已从“级别”重命名为“重要级别”。

  9. 关闭查询。 在提示你保存查询时，选择**“否”**。

  10. 创建新的任务工作项。 选择**“新工作项”链接，然后选择“任务”**。

    此工作项是从你更改和导入的工作项类型创建的。

  11. 请注意，在**“状态”框中，重命名字段的标签“级别”**没有更改。 这是因为工作项窗体上的字段标签的范围限于父团队项目，并且独立于刚刚指定的服务器范围字段名称。

    备注

    有关如何更改工作项窗体上的字段标签的详细信息，请参见Control XML 元素引用。

  12. 关闭新任务并在提示你保存工作项时选择**“否”**。

将报告作为字段的值进行更改

以下命令指定将 DateTime 字段的类型 AdventureWorks.CreatedOn 报告给维度的功能。 此字段的数据将输入仓库和 Analysis Services 数据库，以便用于筛选报告。

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.CreatedOn /reportingtype:dimension

以下命令指定将 Double 字段的类型 AdventureWorks.Field 报告给度量的功能。 所有度量将通过求和进行聚合。

witadmin reportfield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field /reportingtype:measure

启用自定义人名字段的同步

以下命令将启用为 AdventureWorksServer 上的 Collection1 定义的工作项字段 AW.CustomerName 的同步。

验证你想要转换的字段的数据类型

  • 验证分配给你想要通过输入以下命令同步的字段的数据类型（例如 MyCompany.CustomerName）：

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

启用同步

  1. 要启用人名字段的同步，请键入以下命令，并用你的数据替换此处显示的参数：

    witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName /syncnamechanges:true

  2. 将出现以下确认提示：

    This will change properties for field {0} on the Team Foundation Server. Do you want to continue?

  3. 键入 0 确认你想要更改字段，或键入 1 取消请求。

    如果更改请求成功，将出现以下确认消息：

    The field was updated.

    如果更改请求失败，将出现一条错误消息。 最容易犯的常见错误是尝试更改系统引用字段，或尝试更改除字符串之外的数据类型字段。 这些操作不受支持。

删除字段

在删除字段之前，请验证该字段未在使用。 如果该字段正在使用，你必须先从使用它的工作项类型中移除该字段，然后再从团队项目集合中删除它。 以下命令将从 Collection1 删除字段 AdventureWorks.Field：

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field

确认字段未在使用

  1. 输入以下命令，指定工作项字段的引用名称，例如 MyCompany.MyProcess.MyField。

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

    在为字段显示的信息中，验证 Use 的值为“Not In Use”，如本例中所示。

    Field: MyCompany.MyProcess.MyField
Name: MyField
Type: String
Reportable As: dimension
Use: Not In Use
Indexed: False

  2. 如果 Use 字段指示该字段正在使用，则你必须从列出的每个团队项目的每个工作项类型中删除它。 例如，Microsoft.VSTS.TCM.SystemInfo 字段指示它正在由四个项目（Arroyo、Desert、Palm 和 Springs）的工作项类型 Bug 和 Code Defect 使用。

    Field: Microsoft.VSTS.TCM.SystemInfo
Name: System Info
Type: Html
Reportable As: None
Use: Arroyo (Bug), Desert (Bug), Palm (Bug), Springs (Bug, Code Defect)
Indexed: False

    在你删除此字段之前，你必须从定义它的每个团队项目所列出的各个工作项类型中删除它。 若要移除字段，你可以通过删除包含字段引用名称的 FIELD 和 Control 元素修改工作项类型的定义。 请参见导入、导出和管理工作项类型 [witadmin]、FIELD（定义）元素引用和Control XML 元素引用。

从团队项目集合删除字段

  • 输入以下字段来删除 MyCompany.MyProcess.MyField 字段，然后选择 Enter。

    witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:RefName

    在确认提示下，输入 y 来完成此步骤。

问题解答

问：在 TFS 升级后，我可以进行哪些自定义并继续使用“配置功能”向导更新我的团队项目？

**答：**你可以添加自定义字段、自定义选取列表并将规则添加到字段。 配置功能向导将更新你的团队项目，并且你将获取对最新功能的访问权限。

不建议更改字段特性。 要了解你可以安全地进行和避免哪些自定义，请参见自定义工作跟踪体验：在你进行自定义之前，了解维护和升级的影响。

请参见

概念

解决数据仓库中发生的架构冲突

添加或修改工作项字段以支持报告

Visual Studio ALM 的工作项字段参考

Visual Studio ALM 的可报告字段引用

其他资源

witAdmin：自定义和管理用于跟踪工作的对象