Manage link types

  • Artikel

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

Important

For the On-premises XML process model, you can use witadmin to list, import, export, and modify a process for a project. For the Inherited and Hosted XML process models, you can only use witadmin to list and export process information. For an overview of process models and what is supported, see Customize your work tracking experience.

Similar to work item types, you can define and modify custom link types. However, you can't make any changes to system-defined link types. Before you add a new link type to your project collection, review the link types available for your use. See Manage dependencies, link work items.

You manage the link types defined for a project collection by using the following witadmin commands:

  • deactivatelinktype: Deactivates the specified link type. Users will no longer be able to create links of this type. Existing links of this type will continue to function correctly.
  • deletelinktype: Permanently removes the specified link type from the database. All links defined with this link type are also removed.
  • exportlinktype: Exports the definitions of link types. You can export the definition of a single link type or all link types defined for the server.
  • importlinktype: Imports the definitions of link types from an XML file. If a link type with the same reference name already exists, it will be updated to match the imported link type. If the link type does not already exist, a new link type will be created.
  • listlinktypes: Lists the available set of link types on a server.
  • reactivatelinktype: Reactivates the specified link type, and optionally assigns it a new name.

How to run the witadmin command-line tool

To run the witadmin command-line tool, open a Command Prompt window where Visual Studio is installed. The witadmin command-line tool installs with any version of Visual Studio. You can access this tool by installing the free version of Visual Studio Community or Visual Studio Team Explorer.

Note

If you are connecting to an on-premises server, you must use the same or later version of Visual Studio or Team Explorer as Azure DevOps Server. For example, if you connect to a TFS 2017 instance, you must connect from Visual Studio 2017 or Team Explorer 2017. There is no Team Explorer 2015 version.

Visual Studio 2017 or Team Explorer 2017 client:

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

or, TeamExplorer, Professional or Enterprise in place of Community, depending on the version you've installed.

On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%. You can install Visual Studio Community (which provides access to Team Explorer) or Visual Studio Team Explorer 2017 for free.

Prerequisites

For the project collection where the link types are defined, you must have the following permissions set:

  • To list or export link types, you must have your View project-level information permission for a project in the collection set to Allow.
  • To delete, import, or reactive link types, you must be a member of the Project Collection Administrators security group or have your Manage work item link types permission set to Allow.

For more information, see Change project collection-level permissions.

Note

Even if you sign in 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, choose Start, open the Command Prompt shortcut menu, and then choose Run as Administrator. For more information, see the Microsoft Web site: User Access Control.

Syntax

witadmin deactivatelinktype /collection:CollectionURL /n:LinkName  
witadmin deletelinktype /collection:CollectionURL /n:LinkName [/noprompt]   
witadmin exportlinktype /collection:CollectionURL [/n:LinkName] [/f:FileName] [/e:Encoding]   
witadmin importlinktype /collection:CollectionURL /f:FileName [/e:Encoding] [/v]  
witadmin listlinktypes /collection:CollectionURL  
witadmin reactivatelinktype /collection:CollectionURL /n:LinkName

Parameters

Parameter Description
/collection:CollectionURL Specifies the URI of the project collection. For example:

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: LinkName The name or the reference name of the link type to deactivate or delete.
/f: FileName The XML file of link types. Required for import, optional for export. If you omit this parameter, the command output appears on the display.
/e: encoding The name of a .NET Framework 2.0 encoding format. The specified encoding will be used to export or import the XML data. For example, /e:utf-7 specifies Unicode (UTF-7) encoding. If you omit this parameter, witadmin attempts to detect the encoding, and if detection fails, witadmin uses UTF-8.
/v Validates the link type XML without importing it.
/noprompt Disables the prompt for confirmation.
/? or help Displays help about the command in the Command Prompt window.

Remarks

For the structure of the link type definition schema or information about how you can restrict the types of link relationships that team members can make, see LinksControlOptions.

Examples

Unless otherwise specified, the following values apply in each example:

  • URI for the project collection: http://AdventureWorksServer:8080/tfs/DefaultCollection
  • Server name: AdventureWorksServer
  • Input or output file name: myLinkTypes.xml
  • Link type name: mylinktype
  • Default encoding: UTF-8

The following command displays the custom link types defined for Team Foundation AdventureWorksServer.

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

The following example displays the definition of the link type in the Command Prompt window:

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

The following examples deactivate the link type, mylinktype, and then reactivate it:

witadmin deactivatelinktype /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:mylinktype  
witadmin activatelinktype /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:mylinktype

The following command exports the definition of all link types to the file, mylinktype.xml:

witadmin exportlinktype /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /f:mylinktype.xml

The following example imports the definition of the link types defined in the XML file:

witadmin importlinktype /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /f:mylinktype.xml