管理工作项字段
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
重要
对于本地 XML 进程模型，可以使用 witadmin 列出、导入、导出和修改项目的流程。 对于继承的和托管的 XML 进程模型，只能使用 witadmin 列出和导出进程信息。 有关流程模型和支持的概述，请参阅 “自定义工作跟踪体验”。
可以使用以下 witadmin 命令来管理为项目集合（本地 XML）定义的工作项类型定义的字段。 如果要添加全局字段（对本地 XML 有效），可以通过修改全局工作流文件并将其导入集合来执行此操作。
changefield：更改字段的一个或多个属性。 更改以下属性之一时，请更改项目集合中的所有工作项类型和项目：或字段的
PlainTextHTML数据类型。重要
将 Team Foundation Server 从早期版本升级到当前版本时，“说明”（System.Description）字段的类型分配将自动转换为
PlainTextHTML。changefield使用此命令，可以还原此字段的内容以显示纯文本。工作项查询中显示的友好名称 。 此名称可能与工作项窗体上显示的名称不同。
报告属性 ，包括报表中显示的字段名称、引用报表名称和报告类型。
与 Active Directory 同步 - 可以启用/禁用人员姓名字段的同步。
deletefield：删除指定的字段。listfields：列出所有字段或指定字段的属性。
注意
该 witadmin indexfield 命令已弃用 Azure DevOps Server 2019 及更高版本。 不再需要索引字段。
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 安装进程模板编辑器。
先决条件
- 若要列出字段，您必须对集合集中的项目具有“允许”的“查看项目级信息”权限。
- 若要删除或重命名字段或更改字段的属性，您必须是 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]
参数设置
| 参数 | 描述 |
|---|---|
/collection:CollectionURL |
指定项目集合的 URI。 例如： 本地格式： http://ServerName:Port/VirtualDirectoryName/CollectionName如果未使用虚拟目录，请使用以下格式： http://ServerName:Port/CollectionName |
/n:RefName/n:Name |
工作项类型字段的引用名称。 |
/index |
指定为指定字段启用或禁用索引。 指定 启用 索引并 禁用 索引编制。 |
/name:NewName |
指定字段的新名称。 |
/syncnamechanges |
指定使用工作项字段来存储名称，并在 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中转换到 PlainTextHTML 。 只能为类型分配为 PlainText 或 HTML。 请参阅 FIELD （Definition） 元素引用。 |
/unused |
列出项目集合中定义的任何项目未使用的所有字段。 |
/noprompt |
禁用确认提示。 |
/? 或 help |
在命令提示符窗口中显示有关命令的帮助。 |
将人员姓名与 Active Directory 同步
必须手动启用用于分配引用 Active Directory 的人员名称的任何自定义工作项字段的同步。 必须为包含自定义字段的每个项目集合启用每个字段的同步。
显示人员姓名的所有系统引用字段都设置为 true< syncnamechanges a0/>。 此类字段包括 System.AuthorizedAs、System.AssignedTo、System.ChangedBy 和 System.CreatedBy。 为在一个默认进程模板中定义的每个人名字段启用同步。 有关详细信息，请参阅 “工作分配”和“工作流”字段。
启用同步后，该字段不再显示静态字符串。 相反，该字段显示与用户帐户关联的名称。 在 Active Directory 或工作组中更改用户名时，设置为syncnamechangestrue自动显示新名称的字段。
将 syncnamechanges 属性分配给字符串字段时，该字段始终接受有效的用户名。 但是，如果满足以下任一条件 true，则字段不允许存储在 Team Foundation Server 或 Active Directory 中的组名称：
规则
VALIDUSER在所有工作项类型中指定为
VALIDUSER工作项类型指定规则为
ALLOWEDVALUES工作项类型指定规则，该规则具有排除组的筛选条件有关详细信息，请参阅 “所有 FIELD 元素”。
可以为每个工作项类型更改的属性
通过更改显示字段的工作项类型定义来更改为字段定义的以下属性或值：
- 在工作项窗体上显示的名称 。 请参阅 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: FalseUse 参数指示每个项目的名称和使用字段的工作项类型。 有关字段属性的详细信息，请参阅 工作项字段的索引。
列出项目集合中的所有字段
输入以下命令，列出为项目集合定义的所有字段。
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>> 引起。
从“字段”单元格中删除值“排名”，并在单元格中键入“重要排名”。
在<>“运算符”单元格中选择，然后在 Value 单元格中键入 1。
在“查询”工具栏上，选择“
运行”。打开结果中任意行的快捷菜单，然后选择“ 列选项”。 在 “可用列” 列表中向下滚动。 请注意， “排名 ”字段不再存在，但 “重要排名 ”字段存在。
在“可用列”框中选择“重要排名”，然后选择>按钮（添加所选列）。 选择 “确定” 。
请注意，在查询生成器和结果列表中，Microsoft.VSTS.Common.Rank 的友好名称已从 “排名 ”重命名为 “重要排名 ”。
关闭查询。 当系统提示保存查询时，请选择 “否 ”。
创建新的任务工作项。 选择“新建工作项”链接，然后选择“任务”。
此工作项是从已更改和导入的工作项类型创建的。
请注意，在 “状态 ”框中，重命名字段 的标签“排名”尚未更改。 这是因为工作项窗体上的字段标签的范围限定为父项目，并且独立于刚刚指定的服务器范围字段名称。
注意
有关如何更改工作项窗体上的字段标签的详细信息，请参阅 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将显示以下确认提示：
这将更改 Team Foundation Server 上字段 {0} 的属性。 是否继续?
键入 0 以确认要更改字段，或 键入 1 取消请求。
如果更改请求成功，将显示以下确认消息：
字段已更新。
如果更改请求失败，将显示一条错误消息。 可以发生的最常见错误是尝试更改系统引用字段，或尝试更改字符串以外的数据类型的字段。 不支持这些操作。
删除字段
在删除字段之前，请验证该字段是否未使用。 如果该字段正在使用中，必须先从工作项类型中删除该字段，然后才能从项目集合中删除该字段。 以下命令从 Collection1 中删除字段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 以完成此步骤。