Use TFSDeleteProject to delete a project on Azure DevOps on-premises

Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019

You can remove a project from Azure DevOps Server when the project is no longer required by using TFSDeleteProject.

In addition, if there are components that remain undeleted after an unsuccessful project creation, you can use TFSDeleteProject to remove them.

To delete a project from Azure DevOps Services using the admin console, see Delete a project.

Warning

TFSDeleteProject permanently destroys the project, after which it cannot be recovered. You should backup all important project data before using TFSDeleteProject.

To access the TFSDeleteProject command-line tool, open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:

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

On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%.

Prerequisites

To use the TFSDeleteProject command, you must be a member of the Team Foundation Administrators security group or the Project Administrators security group.

For more information, see Set administrator permissions for Azure DevOps Server.

TFSDeleteproject [/q] [/force] [/excludewss] /collection:URL TeamProjectName

Option

Description

/q

Optional. Use the quiet mode. Do not prompt the user for confirmation.

/force

Optional. Specifies that the deletion process should continue even if some components cannot be deleted.

/excludewss

Optional. Specifies to not delete the SharePoint site that is associated with the project. Specify this option to maintain the existing site so that other projects can continue using it.

/collection:URL

Required. Specifies the URI of the project collection. You must use the following format for the URI: http://ServerName:Port/VirtualDirectoryName/CollectionName.

If you do not specify a virtual directory, you must use the following format for the URI: http://ServerName:Port/CollectionName.

TeamProjectName

Required. The name of the project. If the name includes spaces, enclose it in quotations marks.

Remarks

When you create a project, Azure DevOps Server creates data objects on the server that hosts Azure DevOps Server, and may create data objects on the server that hosts SharePoint Products, and the server that hosts SQL Server Reporting Services.

When you remove a project, the reports are automatically removed from SQL Server Reporting Services.

When you remove a project, you can choose whether or not to remove the objects that were created to support the SharePoint site.

However, an error can prevent Azure DevOps Server from creating or deleting all the objects. To troubleshoot these problems, the following sections provide background information, links to other resources, and specific steps that help you determine the cause of the problem, fix the problem, and when necessary delete data objects that remain after running TFSDeleteProject.

TFSDeleteProject process

When you use the TFSDeleteProject command-line tool, it first deletes project data and then project Web sites.

Phase 1: TFSDeleteProject deletes project data

In the first phase, TFSDeleteProject automatically performs the following steps to remove project data:

  1. TFSDeleteProject creates an inventory of all the components that are candidates for deletion.

    This includes components that integrate with Test Manager, Team Foundation Build, and Team Foundation version control.

  2. TFSDeleteProject deletes the component that displays the project node in Team Explorer.

  3. TFSDeleteProject flags the version control information for deletion, but does not immediately delete this information.

    The information includes all version control branches in the specified project, but no other branches outside of the project.

    • If a parent branch and a child branch are both in the project, TFSDeleteProject flags both for deletion.
    • If parent and child branches are in different projects, TFSDeleteProject flags only the specified branch.
    • If another project is a branch from the specified project, TFSDeleteProject flags only the specified project. When the specified project is deleted, the branch project becomes an orphan.
  4. TFSDeleteProject immediately deletes build data, including information and core data, build definitions, build agents, and test results associated with the project. The tool does not delete build drop locations.

    You do not need to delete the build drop location of an old project before creating a project that uses the same build drop location.

    If the specified project contains a large amount of build data, the deletion might not finish within the timeout period.

    To work around this problem, see Increase the Time-Out Period, and then run TFSDeleteProject again.

  5. TFSDeleteProject immediately deletes work items and work item fields that belong to the specified project, and it deletes all non-shared metadata.

    If the specified project contains a large amount of work item data, the deletion might not finish within the timeout period.

    To solve this problem, see Increase the Time-Out Period, and then run TFSDeleteProject again.

Phase 2: TFSDeleteProject deletes project web sites

In the second phase, TFSDeleteProject deletes the following data:

Important

These steps can take a long time to complete, and during that time they can degrade server performance.

  • TFSDeleteProject Uses the Reporting Services APIs to delete reports on the server that hosts Reporting Services.
  • TFSDeleteProject Deletes the project portal Web site from the server that hosts SharePoint Products.

This step occurs only if the project owns the site and site deletion is not excluded in the command line. (Consider that multiple projects may point to a single site, but only one of them can be the owner where reports/dashboards are by default using this project).

Note

Prior to deleting a project, you can confirm that Reporting Services and SharePoint Products are using the correct project URLs by verifying the portal settings. For more information, see Add a Project Portal.

If TFSDeleteProject successfully deletes all of the above data elements, it returns the message Done.

To verify this result, see Verify Project Components Are Deleted.

If one or more components are not removed, you can rerun TFSProjectDelete by using the /force option to continue the deletion process even if it is unable to delete all data elements.

With this option TFSDeleteProject, skips a component that it cannot delete, returns an error message, deletes the next component, and leaves the project metadata and security settings intact.

Data that may remain undeleted

The following data might remain in the deployment after TFSDeleteProject successfully completes:

  • Project data in the cube.

    Project data remains in the cube until the cube is rebuilt, at which time the warehouse controller service removes all of the historic build data that has been deleted from the Azure DevOps databases.

  • Build drop files and folders.

    Build binaries, build log files, and log files containing test results are published during the build process.

    The locations for these files are not deleted. If you want to remove these files, you must remove them manually.

  • Work item tracking metadata that is shared.

    TFSDeleteProject does not delete any metadata for work item tracking that is shared between projects.

  • Version control shelvesets containing shared code.

    Version control shelvesets are not deleted if there is code in the shelveset from multiple projects.

Verify project deletion

You can verify the success of a project deletion by confirming that the project node no longer appears in Team Explorer and that its project portal Web site and reports folders no longer exist.

  1. Open Team Explorer and verify that the project does not appear as a project node.

  2. Open Internet Explorer and type the URL of the project portal Web site. Verify that the site no longer exists.

  3. In Internet Explorer, in the Address box, type the URL of the Reporting Services Web site using one of the following URL formats:

    • http://ReportingServices/Reports
    • http://ReportingServices/Reports_TFSInstance
  4. In Report Manager, choose Show Details.

  5. Verify that the folder for the deleted project no longer appears.

    Choose the root folder TfsReports, and then choose the folder named for the project collection.

    There should no longer be a folder with the name of the deleted project.

  6. If either the reports or the Web site remain, see the next procedure.

Remove remaining components after partial project deletion

If the project portal Web site and reports folder remain after you delete a project, remove the site and folder manually.

  1. Log on to the server that hosts Reporting Services for the project that you deleted.

  2. Open Internet Explorer, and in the Address box type the URL of the Reporting Services Web site using one of the following URL formats:

    • http://localhost/Reports
    • http://localhost/Reports_TFSInstance
  3. In Report Manager, choose Show Details.

  4. Choose the root folder TfsReports, and then choose the folder named for the project collection.

  5. Select the check box for the project that was deleted.

  6. Choose Delete.

  7. Choose OK to confirm that you want to delete the reports folder for the project.

  8. To remove the project portal Web site of a deleted project, see the following page on the Microsoft Web site:

Create, Edit, and Delete Windows SharePoint Services Sites.

Increase the time-out period

By default, each Web service call that the TFSDeleteProject command issues to delete a component must complete within 10 minutes. If there are six calls, then the process could take up to an hour. If you want to delete a project that is associated with a large amount of data, you can temporarily increase this time-out period.

Note

When you increase the time-out period, the change affects all Web service calls. In general, you want to keep the time-out period to within 10 minutes to prevent Web service calls from degrading server performance and causing users to be locked out from using the user interface for long periods of time. Therefore, after the project is successfully deleted, you should change the time-out period back to 10 minutes.

Prerequisites

To complete these procedures, you must be a Windows Administrator on the application-tier server.

Important

Improperly modifying your computer's registry can cause your computer to become unstable. If you are not familiar with the registry, you should not add or remove entries, or modify it in any way.

  1. Log on to the application-tier server.

  2. Choose Start, Run, type regedit, and then choose OK.

  3. In the browser pane, expand HKEY_ LOCAL_MACHINE:

    • If the server runs a 32-bit operating system, expand: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\11.0\TeamFoundation\RequestSettings.
    • If the server runs a 64-bit operating system, expand: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432\Microsoft\VisualStudio\11.0\TeamFoundation\RequestSettings.
  4. If the TeamFoundation\RequestSettings key does not exist, follow these steps to create it:

    1. Open the context menu for TeamFoundation, point to New, and choose Key.
    2. Name the key RequestSettings.
    3. Open the context menu for RequestSettings, point to New, and choose DWORD Value.
    4. Name the new value DefaultTimeout.
  5. Open the context menu for DefaultTimeout and choose Modify.

  6. In Value Data, type the time-out period in milliseconds, and then choose Decimal.

    For example, to increase the time-out period to 30 minutes, type 1800000. To change the time-out period back to 10 minutes, type 600000.

  7. Choose OK.

  8. On the File menu, choose Exit.

Example

The following command removes all components associated with the project StoreFront on the Azure DevOps Server AdventureWorks1 server in project collection Collection1 and from Team Explorer.

TFSDeleteProject /force /collection:http://AdventureWorks1:8080/tfs/Collection1 StoreFront