管理工作项字段

Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019 |TFS 2018

重要

对于本地 XML 进程模型,可以使用 witadmin 列出、导入、导出和修改项目的流程。 对于“继承”和“托管的 XML”进程模型,只能使用 witadmin 列出和导出进程信息。 有关流程模型和支持的概述,请参阅 自定义工作跟踪体验

可以使用以下 witadmin 命令管理为项目集合定义的工作项类型定义的字段, (本地 XML) 。 如果要添加对本地 XML) (有效的全局字段,可以通过修改全局工作流文件并将其导入集合来执行此操作。

  • changefield:更改字段的一个或多个属性。 更改以下属性之一时,将针对项目集合中的所有工作项类型和项目更改该属性:
    • HTML 字段的PlainText数据类型

      重要

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

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

    • 报告属性, 其中包括字段在报表中显示的名称、引用报表名称和报告类型。

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

  • deletefield:删除指定的字段。
  • listfields:列出所有字段或指定字段的属性。

注意

命令witadmin indexfield已弃用 Azure DevOps Server 2019 及更高版本。 不再需要索引字段。

  • changefield:更改字段的一个或多个属性。 更改以下属性之一时,将针对项目集合中的所有工作项类型和项目更改该属性:
    • HTML 字段的PlainText数据类型

      重要

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

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

    • 报告属性, 其中包括字段在报表中显示的名称、引用报表名称和报告类型。

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

  • deletefield:删除指定的字段。
  • indexfield:打开或关闭指定字段的索引。 为字段启用索引后,查找在查询中指定了该字段的工作项时可提高性能。 如果添加了在许多工作项查询中都使用的自定义字段,你可能要为该字段启用索引。
  • listfields:列出所有字段或指定字段的属性。

如何运行 witadmin 命令行工具

若要运行 witadmin 命令行工具,请打开安装 Visual Studio 的命令提示符窗口。 命令行 witadmin 工具随任何版本的 Visual Studio 一起安装。 可以通过安装免费版本的 Visual Studio Community 或 Visual Studio 团队资源管理器来访问此工具。

注意

如果要连接到 Azure DevOps Services,建议使用最新版本的 Visual Studio 或 Visual Studio Community。

注意

如果要连接到本地服务器,建议使用与Azure DevOps Server相同或更高版本的 Visual Studio。 例如,如果连接到 Azure DevOps Server 2019,则从 Visual Studio 2019 版本连接到项目。

对于 Visual Studio 2022

%programfiles(x86)%\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

ProfessionalEnterprise 代替 Community,具体取决于已安装的版本。

对于 Visual Studio 2019

%programfiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

ProfessionalEnterprise 代替 Community,具体取决于已安装的版本。

对于 Visual Studio 2017

%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

TeamExplorerProfessional 代替 Enterprise,具体取决于已安装的版本。

在 32 位版本的 Windows 上,将 %programfiles (x86) % 替换为 %programfiles%。 可以安装Visual Studio Community (,它免费提供对团队资源管理器) 或 Visual Studio 团队资源管理器 2017 的访问权限

有关默认流程模板中定义的字段的概述,请参阅 工作项字段索引

提示

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

或者,可以使用 TFS 团队项目经理,这是 GitHub 提供的开源客户端。

提示

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

或者,可以使用 TFS 团队项目经理,这是 GitHub 提供的开源客户端。

先决条件

  • 若要列出字段,必须将集合集中项目的 “查看项目级信息 ”权限设置为 “允许”。
  • 若要删除或重命名字段或更改字段的属性,您必须是 Team Foundation Administrators 安全组或 Project Collection Administrators 安全组的成员。

有关详细信息,请参阅 更改项目集合级别权限

注意

即使使用管理权限登录,也必须打开提升的命令提示符窗口,才能在运行 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 listfields /collection:CollectionURL /n:RefName [/unused]  
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。 例如:

本地格式:http://ServerName:Port/VirtualDirectoryName/CollectionName
如果未使用虚拟目录,请使用以下格式: http://ServerName:Port/CollectionName
/n:RefName
/n:Name
工作项类型字段的引用名称。
/index 指定为特定的字段启用或禁用索引。 指定 on 以启用索引编制, 并指定 off 以禁用索引。
/name:NewName 指定字段的新名称。
/syncnamechanges 指定使用工作项字段来存储名称,并在 Active Directory 或某个工作组中做出更改后进行更新。 仅当为 指定数据类型为 String 的字段时, typename此选项才有效。

指定 true 以启用数据字段的同步,指定 false 以禁用数据字段的同步。
/reportingname:ReportingName 在将用于报告的数据仓库中,指定字段的名称。
/reportingrefname:ReportingRefName 在数据仓库中指定将用于报告的字段的引用名称。
/reportingtype:Type 指定如何在仓库中使用该字段以用于报告。 以下为有效值:

- dimension: 用于 Integer、String 或 DateTime 字段。
- detail: 用于 Integer、Double、String 或 DateTime 字段。
- measure: 用于“整数”和“双精度”字段。 默认的聚合类型是求和。 可以使用 公式 参数指定另一种聚合类型。
- none: 用于禁用字段的可报告性。

有关详细信息,请参阅 关于工作项字段和属性
/reportingformula:Formula 指定在字段报告为 measure时要使用的聚合公式。 唯一支持的公式是 sum
/type:HTML | PlainText 指定将 字段的内容从 PlainText 转换为 HTML 或 从 HTML 转换为 PlainText。 只能为类型分配为 PlainTextHTML的字段指定此选项。 请参阅 FIELD (定义) 元素引用
/unused 列出项目集合中定义的任何项目未使用的所有字段。
/noprompt 禁用请求确认的提示。
/?help 在“命令提示符”窗口中显示有关命令的帮助。

索引字段

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

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

将人名与 Active Directory 同步

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

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

在启用同步后,该字段不再显示静态字符串。 而是显示与用户帐户关联的名称。 在 Active Directory 或 Workgroup 中更改用户名时,设置为 truesyncnamechanges字段会自动显示新名称。

syncnamechanges 属性分配给 String 字段时,该字段始终接受有效的用户名。 但是,如果以下任一条件为 true,则 字段不允许存储在 Team Foundation Server 或 Active Directory 中的组名称:

  • 在所有 VALIDUSER 工作项类型中指定规则

  • VALIDUSER 工作项类型指定规则

  • 规则 ALLOWEDVALUES 是为工作项类型指定的,该规则具有排除组的筛选条件

    有关详细信息,请参阅 所有 FIELD 元素

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

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

示例

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

  • 项目集合的 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 参数指示每个项目的名称以及使用该字段的工作项类型。 有关字段属性的详细信息,请参阅 工作项字段的索引

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

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

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

    将显示命名项目集合的所有字段的字段信息。 请参阅 工作项字段的索引

列出未被使用的字段

  • 输入以下命令,列出任何工作项类型不再在项目集合中使用的字段。

    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 的友好名称重命名为 Important Rank

    witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Rank /name:"Important Rank"  
    
  2. 在确认提示符下键入 y ,然后按 Enter。 请等待,直到你收到以下消息:

    字段已重命名。

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

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

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

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

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

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

  4. Field 单元格中删除值 Rank,并在单元格中键入 Important Rank

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

  6. “查询 ”工具栏上,选择 “运行查询运行”。

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

  8. 在“可用列”框中选择“重要排名>,然后选择 () 添加所选列的按钮。 选择 “确定”

    请注意,Microsoft的友好名称。VSTS。在整个查询生成器和结果列表中,Common.Rank 已从 Rank 重命名为 Important 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 的同步。

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

  1. 验证分配给你想要通过输入以下命令同步的字段的数据类型(例如 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. 将出现以下确认提示:

    这将更改 Team Foundation Server 上字段 {0} 的属性。 是否继续?

  3. 键入 0 以确认要更改字段,键入 1 可取消请求。

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

    字段已更新。

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

删除字段

在删除字段之前,请验证该字段未在使用。 如果字段正在使用中,必须先从使用该字段的工作项类型中删除该字段,然后再将其从项目集合中删除。 以下命令将从 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 的值是否为“未使用中”,如以下示例所示。

    Field: MyCompany.MyProcess.MyField  
    Name: MyField  
    Type: String  
    Reportable As: dimension  
    Use: Not In Use  
    Indexed: False  
    
  2. 如果“ 使用 ”字段指示该字段正在使用中,则必须从列出的每个项目的每个工作项类型中删除该字段。 例如,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 元素来修改工作项类型的定义。 请参阅 导入、导出和管理工作项类型FIELD (定义) 元素引用Control

从项目集合中删除字段

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

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

在确认提示符处输入 y 以完成此步骤。

问题解答

问:在 TFS 升级后,我可以进行哪些自定义,并且仍使用配置功能向导更新我的项目?

答: 可以添加自定义字段、自定义选取列表,以及向字段添加规则。 配置功能向导将更新项目,你将获得最新功能的访问权限。

不建议更改字段特性。 若要了解可以安全进行哪些自定义以及应避免的自定义,请参阅 本地 XML 进程模型、维护和升级影响