Managing Work Item Fields
You can manage the work item type fields that are defined for a team project collection by using the following witadmin commands:
deletefield: Deletes the specified field.
listfields: Lists the attributes for all fields or a specified field.
indexfield: Turns indexing on or off for the specified field. When you enable indexing for a field, you may increase the performance of finding work items whose queries specify that field. If you add a custom field that you use in many of your work item queries, you may want to enable indexing for that field.
changefield: Changes one or more attributes of a field, such as the friendly field name, attributes for data warehouse reporting, or the ability to synchronize a field that contains person names. When synchronization is enabled, the field is updated as updates are made to Active Directory or a workgroup. For information about how to use fields for reporting, see Working with Work Item Fields.
Důležité
When you upgrade from an earlier version to the current version, all built-in fields the syncnamechanges attribute is set to true for all String fields that contain person names. However, you must manually assign the attribute to any custom fields that you use to store person names and that you want to have synchronized. For more information, see Updating Custom Person-Name Fields to Synchronize with Active Directory or Workgroups.
The witadmin command-line tool is located in Drive:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE on the client computer that runs Team Explorer.
For more information about fields, see Defining Work Item Fields.
Poznámka
You can create and modify work item fields by using Process Editor, a power tool for Visual Studio. This tool is not supported. For more information, see the following page on the Microsoft Web site: Team Foundation Server Power Tools April 2010.
Required Permissions
For the team project collection where the work item type fields are defined, you must have the following permissions set:
To list fields, you must be a member of the Readers group or have your View work items in this node permission set to Allow
To delete or rename fields or change the reporting characteristics of a field, you must be a member of the Team Foundation Administrators security group or the Project Administrators security group.
For more information, see Team Foundation Server Permissions and Team Foundation Server Default Groups, Permissions, and Roles.
Poznámka
Even if you log on with administrative permissions, you must open an elevated Command Prompt window to perform this function on a server that is running Windows Server 2008. To open an elevated Command Prompt window, click Start, right-click Command Prompt, and then click Run as Administrator. For more information, see the Microsoft Web site: User Access Control.
witadmin deletefield /collection:CollectionURL /n:RefName [/noprompt]
witadmin listfields /collection:CollectionURL /n:RefName [/unused]
witadmin indexfield /collection:CollectionURL /n:Name /index:on|off
witadmin changefield /collection:CollectionURL /n:RefName [/name:NewName] [/syncnamechanges:true | false] [/reportingname:ReportingName] [/reportingrefname:ReportingRefName] [/reportingtype:Type] [/reportingformula:Formula] [/noprompt]
Parameters
Parameter |
Description |
|---|---|
/collection:CollectionURL |
Specifies the URI of the team project collection. The format for the URI is the following: http://ServerName:Port/VirtualDirectoryName/CollectionName If no virtual directory is used, then the format for the URI is the following: http://ServerName:Port/CollectionName |
/n:RefName /n:Name |
The reference name of a work item type field. |
/index |
Specifies to enable or disable indexing for the specified field. Specify on to enable indexing and off to disable indexing. |
/name:NewName |
Specifies the new name for the field. |
/syncnamechanges |
Specifies to use the work item field to store names and to update as changes are made in Active Directory or a workgroup. This option is valid only when a field with the data type of String is specified for the typename. Specify true to enable synchronization for the data field, specify false to disable synchronization for the data field. |
/reportingname:ReportingName |
Specifies the name of the field in the data warehouse to be used for reporting. |
/reportingrefname:ReportingRefName |
Specifies the reference name of the field in the data warehouse to be used for reporting. |
/reportingtype:Type |
Specifies how the field is used in the warehouse for reporting. The following values are valid:
For more information, see Working with Work Item Fields. |
/reportingformula:Formula |
Specifies the aggregation formula to be used when the field is reported as a measure. The only supported formula is sum. |
/unused |
Lists all fields that are not used by any team project defined in the team project collection. |
/noprompt |
Disables prompt for confirmation. |
/? or help |
Displays help about the command in the Command Prompt window. |
Remarks
When you assign the syncnamechanges attribute to a String field, the field always accepts valid user names. However, the field does not allow group names that are stored in Team Foundation Server or in Active Directory if any one of the following conditions is true:
The VALIDUSER rule is specified across all work item types
The VALIDUSER rule is specified for a work item type
The ALLOWEDVALUES rule is specified for a work item type, and that rule has a filter criteria that excludes groups
For more information, see All FIELD XML Elements Reference.
For a summary of the system fields that are indexed, see Using System Fields and Fields Defined by the MSF Process Templates.
Examples
Unless otherwise specified, the following values apply in each example:
URI for the team project collection: http://AdventureWorksServer:8080/AWTeam/Collection1
Work item field name: AdventureWorks.Field
Default encoding: UTF-8
List Fields
The following command displays information about each field defined for Collection1 on the AdventureWorksServer server:
witadmin listfields /collection:http://AdventureWorksServer:8080/AWTeam/Collection1
The following command displays the field information for the specified field AdventureWorks.Field used by Collection1:
witadmin listfields /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field
The following command displays all fields that Collection1 is not using:
witadmin listfields /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /unused
Rename a Field
The following command changes the friendly name of the referenced field AdventureWorks.Field to NewFieldName for Collection1:
witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field /name:NewFieldName
Change the Report As Value for a Field
The following command specifies the ability to report the type of the DateTime field AdventureWorks.CreatedOn to dimension. This field's data enters the warehouse and Analysis Services databases so that it can be used to filter reports.
witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.CreatedOn /reportingtype:dimension
The following command specifies the ability to report the type of the Double field AdventureWorks.Field to measure. All measures are aggregated by sum.
witadmin reportfield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field /reportingtype:measure
Enable Synchronization of a Custom Name Field
The following command enables synchronization for the work item field AW.CustomerName defined for Collection1 on the AdventureWorksServer.
witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AW.CustomerName /syncnamechanges:true
Delete a Field
The following command deletes the field AdventureWorks.Field from Collection1:
witadmin deletefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field
See Also
Tasks
List Work Item Fields and View Attributes Assigned to Fields
Concepts
Resolving Schema Conflicts That Are Occurring in the Data Warehouse
Adding and Modifying Work Item Fields to Support Reporting
Using System Fields and Fields Defined by the MSF Process Templates