管理工作项字段

2025-10-08

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

重要

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

witadmin 命令行工具提供了用于管理项目集合中工作项字段的强大功能。无论是需要重命名字段、调整数据类型还是配置与标识提供者的同步，这些命令都提供对工作跟踪体验的精细控制。

可以使用 witadmin 字段命令执行哪些作

使用以下 witadmin 命令管理集合中所有工作项类型和项目的字段：

changefield：修改应用集合范围的字段属性，包括：
- 数据类型转换PlainText和HTML格式
重要

升级 Azure DevOps Server 时， “说明 ”字段（System.Description）会自动转换为 PlainTextHTML。如果需要， changefield 请使用该命令还原此命令。
- 工作项查询中显示的友好名称（可能与表单标签不同）
- 数据仓库集成的报告属性
- 使用 Microsoft Entra ID 或 Active Directory 进行标识同步
deletefield：从集合中删除未使用的字段
listfields：跨项目查看字段属性和使用情况

提示

若要在本地 XML 环境中添加全局字段，请修改全局工作流文件并将其导入到集合。
witadmin indexfield 命令已弃用。字段索引自动发生。

`witadmin`运行命令行工具

若要运行 witadmin 命令行工具，请打开安装 Visual Studio 的命令提示符窗口。 witadmin命令行工具随任何版本的 Visual Studio 一起安装。可以通过安装 Visual Studio Community 或 Visual Studio Team Explorer 的免费版本来访问此工具。

注意

若要连接到 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 Team Explorer 2017 。

有关默认进程模板中定义的字段的概述，请参阅 “工作项”字段索引。

提示

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

先决条件

任务	所需的权限
列出字段	查看项目级信息权限设置为 “允许集合中的项目”
删除或重命名字段	项目集合管理员安全组的成员
更改字段属性	项目集合管理员安全组的成员

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

注意

即使使用管理权限登录，也必须打开提升的命令提示符窗口，在运行 Windows Server 的服务器上执行此函数。若要打开提升的命令提示符窗口，请选择“ 开始”，打开 命令提示符 快捷菜单，然后选择“ 以管理员身份运行”。

语法

使用以下命令语法模式通过 witadmin 工具管理工作项字段：

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]

参数

参数	描述
`/collection`:`CollectionURL`	指定项目集合的 URI。例如：本地格式：`http://ServerName:Port/VirtualDirectoryName/CollectionName` 如果未使用虚拟目录，请使用以下格式： `http://ServerName:Port/CollectionName`
`/n:RefName` `/n:Name`	工作项类型字段的引用名称。
`/name:NewName`	指定字段的新名称。
`/syncnamechanges`	指定使用工作项字段来存储名称和更新，因为Microsoft Entra ID、Active Directory 或工作组中的更改。仅当为 `typename` 指定字符串数据类型的字段时，此选项才有效。指定 `true` 为数据字段启用同步。指定 `false` 为禁用数据字段的同步。
`/reportingname:ReportingName`	指定要用于报告的数据仓库中的字段的名称。
`/reportingrefname:ReportingRefName`	指定要用于报告的数据仓库中字段的引用名称。
`/reportingtype:Type`	指定如何在仓库中使用字段进行报告。以下为有效值： - `dimension:` 用于 Integer、String 或 DateTime 字段。 - `detail:` 用于 Integer、Double、String 或 DateTime 字段。 - `measure:` 用于整数和双精度字段。默认聚合类型为 sum。可以使用公式参数指定另一种聚合类型。 - `none:` 用于禁用字段的可报告性。有关详细信息，请参阅 “关于工作项”字段和属性。
`/reportingformula:Formula`	指定在将字段报告为 a `measure`时使用的聚合公式。唯一支持的公式是 `sum`。
`/type:HTML` \| `PlainText`	指定将字段的内容从`PlainText`中或从`HTML`中转换到 `HTMLPlainText` 。只能为类型分配为 `PlainText` 或 `HTML`。请参阅 FIELD （Definition）元素引用。
`/unused`	列出项目集合中定义的任何项目未使用的所有字段。
`/noprompt`	禁用确认提示。
`/?` 或 `help`	在命令提示符窗口中显示有关命令的帮助。

将人员姓名与 Microsoft Entra ID 和 Active Directory 同步

配置自定义人员名称字段，以在标识提供者中更改用户名时自动更新。

何时启用同步

仅自定义字段：必须为用于分配人员姓名的任何自定义工作项字段手动启用同步。

系统字段：所有内置人员名称字段都自动启用同步：

System.AssignedTo
System.ChangedBy
System.CreatedBy

标识提供者支持

环境	身份提供者
Azure DevOps Services	Microsoft Entra ID
Azure DevOps Server	Active Directory 或工作组

同步的工作原理

国家	行为
启用之前	字段显示静态文本字符串
启用后	字段显示标识提供者的当前用户名
名称更改时	具有自动更新的 `syncnamechanges=true` 字段

组名称限制

在 String 字段中启用 syncnamechanges 该属性时，它接受有效的用户名，但如果满足以下任一条件， 则不允许组名称 ：

VALIDUSER 在所有工作项类型中指定的规则
VALIDUSER 为特定工作项类型指定的规则
ALLOWEDVALUES 使用排除组的筛选条件指定的规则

配置范围

重要

必须为每个包含自定义字段的项目集合中的每个字段启用同步。

有关详细信息，请参见:

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

通过更改显示字段的工作项类型定义来更改为字段定义的以下属性或值：

在工作项窗体上显示的名称 。请参阅 WebLayout 和 Control 元素或 Control XML 元素引用。
帮助文本。请参阅规则和规则评估。
在选取列表或下拉菜单中允许的值 或项。请参阅 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 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 参数指示每个项目的名称和使用字段的工作项类型。有关字段属性的详细信息，请参阅工作项字段的索引。

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

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

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

重命名字段

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

重命名工作项字段

输入以下命令，重命名分配给Microsoft.VSTS.Common.Rank重要排名的友好名称。

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

在确认提示符下，输入 y 并选择 ENTER。等到收到以下消息：

字段已重命名。

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

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

从服务器下载最新的更新，其中包括刚刚对字段名称所做的更改。等待几秒钟，刷新完成。
选择“ 新建查询 ”以创建查询。
在查询编辑器中，选择 “单击此处”添加子句 链接以添加行，选择空白字段单元格，然后在单元格中输入 Rank。结果列表上方显示的以下消息。此消息指示找不到排名。

运行查询以查看查询结果。 TF51005：查询引用不存在的字段。错误是由 <\<Rank>>.
从“字段”单元格中删除值“排名”，然后输入Important Rank到单元格中。
在<>“运算符”单元格中选择，然后输入1“值”单元格。
在“查询”工具栏上，选择“运行”。
打开结果中任意行的快捷菜单，然后选择“ 列选项”。在 “可用列” 列表中向下滚动。请注意， “排名 ”字段不再存在，但 “重要排名 ”字段存在。
在“可用列”框中选择“重要排名”，然后选择>按钮（添加所选列）。选择 “确定” 。

请注意，Microsoft.VSTS.Common 的友好名称。排名从排名重命名为 重要排名 ，整个查询生成器和结果列表。
关闭查询。当系统提示保存查询时，请选择 “否 ”。
创建新的任务工作项。 选择“新建工作项”链接，然后选择“任务”。

此工作项是从已更改和导入的工作项类型创建的。
请注意，在 “状态 ”框中，重命名字段 “排名 ”的标签未更改。工作项窗体上的字段标签范围限定为父项目，独立于指定的服务器范围字段名称。

注意

有关如何更改工作项窗体上的字段标签的详细信息，请参阅 Control XML 元素参考。
关闭新任务，并在系统提示保存工作项时选择 “否 ”。

将报表更改为字段的值

以下命令指定向维度报告 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

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

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

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

输入以下命令，验证分配给字段的数据类型，例如 MyCompany.CustomerName，是否要同步：

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

启用同步

若要为人员命名字段启用同步，请键入以下命令，替换此处所示的参数的数据：

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

将显示以下确认提示：

这将更改 Azure DevOps Server 上字段 {0} 的属性。是否继续?
输入 0 以确认要更改字段，或 1 取消请求。

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

字段已更新。

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

删除字段

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

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

验证字段未使用

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

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

在为字段显示的信息中，验证“未使用”的值，如下例所示。

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

如果“使用”字段指示该字段正在使用中，则必须从列出的每个项目的工作项类型中删除该字段。例如，该 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 来修改工作项类型的定义。请参阅导入、导出和管理工作项类型、 FIELD （定义）元素引用和控件。

从项目集合中删除字段

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

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

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

反馈

此页面是否有帮助？