Remove work items permanently

TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

You can permanently remove one or more work items from the on-premises Team Foundation database for a team project collection by using the witadmin destroywi command. Work items whose state is set to Closed remain in the database and can be reactivated. Permanently removed work items are removed from the database and cannot be restored nor reactivated.

Each work item represents an object that is stored in the Team Foundation database and that is assigned a unique identifier, which is referred to as a work item ID. Work item IDs are unique within a project collection.

You can run witadmin destroywi against an on-premises TFS only.

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 TFS, you must use the same version of Visual Studio or Team Explorer as TFS. 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.

Visual Studio 2015 client:

cd %programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE

Visual Studio 2013 client:

cd %programfiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

Team Explorer 2013 client:

cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

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.

Requirements

Note

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, choose Start, open the shortcut menu for Command Prompt, and choose Run as Administrator. For more information, see the Microsoft Web site.

Syntax

witadmin destroywi /collection:CollectionURL /id:id [/noprompt]  

Parameters

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

On-premises TFS format: http://ServerName:Port/VirtualDirectoryName/CollectionName
If no virtual directory is used, then the format for the URI is the following: http://ServerName:Port/CollectionName.
/id:id The ID of a work item to destroy. To specify multiple work items, separate IDs using only commas, without whitespace.
/noprompt Disables the prompt for confirmation.
/? or help Displays help about the command in the Command Prompt window.

Permanently remove work items from the database

The following example deletes the work item 2003 from the database for Collection1 on the AdventureWorksServer server:

witadmin destroywi /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /id:2003  

The following example deletes the work items with IDs, 12, 15, and 23 from the database for Collection1 on the AdventureWorksServer server:

witadmin destroywi /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /id:12,15,23