管理工作项字段 [witadmin]

  • 项目

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

  • changefield：更改字段的一个或多个特性。 当更改以下属性之一时，应针对团队项目集合中的所有工作项类型和团队项目进行更改：

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

      重要

      当您将 Team Foundation Server 从早期版本升级到当前版本后，将自动把“说明” (System.Description) 字段的类型分配从 PlainText 转换到 HTML。使用 changefield 命令，您可以还原此字段的内容来显示纯文本。

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

    • 出现在报告中时包含字段名称的报告特性、报告引用名称和报告类型。

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

  • deletefield：删除指定的字段。

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

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

若要运行 witadmin 命令行工具，请打开已安装 Visual Studio 或 团队资源管理器 的“命令提示”窗口，然后输入：

cd %programfiles%\Microsoft Visual Studio 11.0\Common7\IDE

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

有关 Team Foundation Server 中附带默认进程模板内定义的字段的概述，请参见 工作项字段参考 (Visual Studio ALM)。

备注

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

要求

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

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

有关更多信息，请参见Team Foundation Server 权限和Team Foundation Server 默认组、权限和角色。

备注

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

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]

参数

Parameter

描述

/collection:CollectionURL

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

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

http://服务器名称:端口/集合名称

/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 和 Double 字段。 默认的聚合类型为 sum。 可以使用 formula 参数指定其他的聚合类型。

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

有关更多信息，请参见使用工作项字段。

/reportingformula:Formula

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

/type:HTML | PlainText

指定将字段的内容从 PlainText 转换为 HTML，或从 HTML 转换为 PlainText。 您可以只为其类型分配是 PlainText 或 HTML 的字段指定此选项。 请参见 FIELD（定义）元素。

/unused

列出团队项目集合中所定义的团队项目未能使用的所有字段。

/noprompt

禁用提示进行确认。

/? or help

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

备注

Dd236909.collapse_all(zh-cn,VS.110).gif索引字段

查询索引从已根据启用索引的字段创建。 当运行包含索引字段的查询时，此索引可提高响应时间性能。

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

Dd236909.collapse_all(zh-cn,VS.110).gif与 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 规则，并且该规则包含已排除组的筛选条件

有关更多信息，请参见All FIELD XML 元素引用。

Dd236909.collapse_all(zh-cn,VS.110).gif每个工作项类型中可更改的属性

您可以通过更改出现某字段的工作项类型定义更改为该字段定义的以下属性或值：

示例

除非另外指定，否则下面的值适用于每个示例：

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

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

  • 默认编码：UTF-8

Dd236909.collapse_all(zh-cn,VS.110).gif列出字段

使用 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

Dd236909.collapse_all(zh-cn,VS.110).gif重命名字段

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

重命名工作项字段

  1. 输入以下命令，将分配给 Microsoft.VSTS.Common.Rank 的友好名称重命名为 Important 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. 在查询编辑器中，选择**“单击此处可添加一条子句”链接以添加一行，选择空白“字段”**单元格，在该单元格中，键入“Rank”。 显示在结果列表上方的以下消息。 该消息指示无法找到“Rank”。

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

  4. 从**“字段”**单元格中删除“Rank”值，然后在该单元格中键入“Important Rank”。

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

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

  7. 打开结果中任意一行的快捷菜单，并选择**“列选项”。 在“可用列”列表中向下滚动。 可以看到，“Rank”字段已不存在，但存在“Important Rank”**字段。

  8. 选择**“可用列”框中的“Important Rank”，然后选择“>”按钮（添加所选列）。 选择“确定”**。

    可以看到，在查询生成器和结果列表中，Microsoft.VSTS.Common.Rank 的友好名称都已从“Rank”重命名为“Important Rank”。

  9. 关闭该查询。 提示您保存查询时，请选择**“否”**。

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

    此工作项是从您已更改并导入的工作项类型创建的。

  11. 注意，在**“状态”框中，重命名的字段“Rank”**的标签并未更改。 这是因为工作项窗体上的字段标签针对的是父级团队项目，与刚才指定的服务器范围的字段名称无关。

    备注

    有关如何更改工作项窗体上的字段标签的更多信息，请参见更改字段的标签。

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

Dd236909.collapse_all(zh-cn,VS.110).gif更改字段的“报告为值”

下面的命令将报告 DateTime 字段 AdventureWorks.CreatedOn 类型的能力指定为 dimension。 此字段的数据进入该仓库和 Analysis Services 数据库，以使其可用于筛选报告。

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

下面的命令将报告 Double 字段 AdventureWorks.Field 类型的能力指定为 measure。 所有的 measure 均由 sum 聚合。

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

Dd236909.collapse_all(zh-cn,VS.110).gif启用自定义人名字段同步

下面的命令为在 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.

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

Dd236909.collapse_all(zh-cn,VS.110).gif删除字段

在删除字段之前，请验证未使用的字段。 如果字段正在使用，则必须先从使用该字段的工作项类型中将其删除，再从团队项目集合中将其删除。 下面的命令从 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 字段指示它正由以下四个项目的 Bug 和“代码缺陷”工作项类型使用：Arroyo、Desert、Palm 和 Springs。

    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，完成此步骤。

请参见

概念

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

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

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

Visual Studio ALM 的可报告字段参考

其他资源

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