Using TFSDeleteProject to Delete Projects on Team Foundation Server

  • Article

Aaron Block

October 2008

Summary

This paper describes how to use TFSDeleteProject, a command-line utility, to permanently delete projects on Team Foundation Servers.

Applies to:

Microsoft Visual Studio Team System Team Foundation Server 2008

Introduction

Required Permissions

Use TFSDeleteProject with Caution

TFSDeleteProject Syntax and Parameters

Verifying that TFSDeleteProject worked correctly

Remaining Data

How TFSDeleteProject Works

Frequently Asked Questions (FAQ)

Conclusion

Introduction

TFSDeleteProject is a command-line utility that is used to permanently destroy a team project from Visual Studio Team System Team Foundation Server. You can find TFSDeleteProject at <drive>\Program Files\Visual Studio 9\Common7\IDE\.

Required Permissions

It is recommended that you have full Team Foundation Administrator permissions to use TFSDeleteProject. If you are not a full Team Foundation Administrator, you must be a member of the groups in the following list to use TFSDeleteProject. For more information, see How to: Set Team Foundation Server Administrator Permissions.

Membership Reasons

Project Administrators group

Required to start TFSDeleteProject.

Windows SharePoint Services Site Administrators group

-or-

SharePoint Administration group

Required to remove a Windows SharePoint System (WSS) site associated with a project.

SQL Server Reporting Services Content Manager group

-or-

Reporting Services System Administrators group

Required to remove the SQL Server Reporting Services (SSRS) reports.

Use TFSDeleteProject with Caution

TFSDeleteProject deletes the whole project; this process is not reversible. Before using TFSDeleteProject, make sure that all important data has been backed-up appropriately. For more information, see How to: Back Up a Team Foundation Server.

TFSDeleteProject Syntax and Parameters

The general command line for TFSDeleteProject is:

TFSDeleteproject [/q] [/force] [/server:servername] team project name

The parameters for TFSDeleteProject are as follows:

Argument Description

Team project name

The name of the project. Use quotation marks if there are spaces in the name.

servername

The server name. Use quotation marks if there are spaces in the name.
Option Description

/q

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

/server:servername

The name of the application-tier Team Foundation Server where the team project is located. This is required in multi-server environments.

/force

The program should continue even if some parts cannot be deleted.

For example, the following command destroys the team project StoreFront on the Team Foundation Server AdventureWorks1 and from Team Explorer.

> TFSDeleteProject /server:AdventureWorks1 StoreFront

For more information, see TFSDeleteProject.

Verifying that TFSDeleteProject worked correctly

There are four steps for verifying that TFSDeleteProject worked.

  1. Check Team Explorer to make sure that the project node is gone.

    • Directions: Open Team Explorer and make sure that the project is no longer in the tree.

  2. Check the history of the TFSVersionControl Administration Job.

    • Directions: See How do I start or view the history of the TFSVersionControl Administrator job? later in this article.

    Note

    For large projects, this job may take a long time to be completed. As a result, it is typically run at midnight, but can be forced to run sooner. For more information, see the section How do I start or view the history of the TFSVersionControl Administrator job? later in this article.

  3. Verify the WSS site is gone.

    • Directions: Navigate to the WSS site by opening Internet Explorer and move to the team project page, http://<server>/sites/teamprojectname, to make sure that no site exists.

  4. Verify the SSRS reports folder is gone.

    • Directions: On the computer that has SSRS installed, make sure that the folder that contains the SSRS reports is no longer present by opening Internet Explorer and move to the reports page at http://<server>/reports.

Resolving Failures

There are two primary reasons why TFSDeleteProject fails: insufficient permissions and time outs. Please notice that the TFSDeleteProject tool does not verify a user has the rights that they need to delete content in WSS or SSRS before it tries to delete. Thus, if the project node no longer appears in Team Explorer and either the WSS site or the SSRS reports remain, whatever remains must be deleted by hand (by a user who has sufficient permissions). For more information, see How to: Create, Edit, and Delete Windows SharePoint Services Sites.

To delete an SSRS Report

  1. Navigate to http://<server>/reports.

  2. Click Show Details in the upper-right.

  3. Put a check mark by the folder that has the team project name.

  4. Click the Delete button.

By default, the maximum duration of time TFSDeleteProject may execute for before timing-out is ten minutes. For team projects, it is possible that deleting the build and WIT data will take longer than ten minutes. Thus, to delete large projects, you may have to increase the time before TFSDeleteProject times-out. The directions for increasing the time-out time are given in this article in the section: How do I modify the DefaultTimeout value?.

Remaining Data

There are some areas where data may remain behind after you use TFSDeleteProject.

  • The TFS Warehouse is untouched. In order to remove the data from the warehouse, it must be rebuilt. (It is important to notice that, when the warehouse is rebuilt all the historic build data that has been trimmed from the system will be removed.) Rebuilding the warehouse is accomplished using the command SetupWarehouse. For more information, see SetupWarehouse.
  • The build drop locations (i.e., the location where the build binaries, build log files, and test results log files are published during the build process) are untouched. Removing the build drops must be done manually.
  • Any work item tracking metadata that is shared between projects will not be deleted.
  • The version control shelve set may not be deleted if there is code in the shelve set from multiple projects.

How TFSDeleteProject Works

In order to delete a project, TFSDeleteProject uses a two-phase process. In the first phase, TFSDeleteProject iterates through the core areas of a project that have an IProjectMaintenance interface declared in the TFS registration data (i.e., version control, build, work item tracking, and core TFS services). For each such area, TFSDeleteProject calls the DeleteProject function that is associated with the IProjectMaintenance interface. It is possible to find more detailed information about which the services support the IProjectMaintenance interface by calling the GetRegistrationEntries method. For more information, see IRegistration.GetRegistrationEntries Method.

More specifically, the first phase of TFSDeleteProject affects the components of a project the following manner:

  • Version Control
    Uses a two-phase delete process. First, all version control information associated with a project are flagged to be deleted. Next, at a later point in time (typically midnight), the TFSVersionControl Administration job is run on the SQL server to delete all the flagged data. Until this job is run, a user cannot create a project with the same name. In order to force the TFSVersionControl Administration job to run immediately, see How do I start or view the history of the TFSVersionControl Administrator job?.

    The second phase is not automatically executed because it may take a long time to complete, and when it is executing, it reduces the quality of service of current users when executing.

  • Build
    Deletes all test results, build data (including information and core data), build definitions, and build agents associated with the team project. The build drop locations are ignored. For team projects, it is possible that the build component will time-out. If this occurs, increase the time-out time and call TFSDeleteProject again. For more information, see the section How do I modify the DefaultTimeout value? in this article.
  • Work Item
    Deletes all work items and work item fields that belong to a project plus any metadata that is not shared. As with the build component, for team projects, it is possible that the WI component will time-out. If this occurs, increase the time-out time and call TFSDeleteProject again. For more information, see the section How do I modify the DefaultTimeout value? in this article.

In its second phase, TFSDeleteProject deletes the remaining areas (i.e., the SSRS reports and the WSS site) using their built-in interfaces. The URLs that TFSDeleteProject uses to locates the built-in interfaces for the SQL Server Reporting Services and the Windows SharePoint Services can be configured by the tfsadminutil ConfigureConnections command. For more information, see ConfigureConnections Command.

The distinction between each phase is important because there are different consequences depending on which phase TFSDeleteProject fails. If the first phase fails, the project node will remain in Team Explorer and you can retry the deletion process by invoking TFSDeleteProject again. If the first phase succeeds and the second phase fails, project node will disappear from Team Explorer even though the SSRS reports or the WSS site may remain. Thus, in this case, in order to completely remove this project, the remaining SSRS reports and WSS site must be deleted by hand instead of invoking TFSDeleteProject again. For more information, see Resolving Failures earlier in this article.

Frequently Asked Questions (FAQ)

How is version control branching handled under TFSDeleteProject?

Briefly, TFSDeleteProject deletes all version control branches in a given project, but no other branches outside a given project. More specifically, the behavior of TFSDeleteProject can be summarized by three different scenarios

  • Parent and child branch are in the same project. Both branches are deleted.
  • Parent and child branch are in different projects. Only the branch in the project deleted by TFSDeleteProject is deleted.
  • Project is created as a branch off of an exist project. Only the project deleted by TFSDeleteProject is deleted.

Notice that you can orphan a child branch if the parent branch is deleted.

Why can’t I create a team project with the same name immediately?

There are two reasons why this may be true. First, it is possible that either the WSS site or SSRS reports did not delete successfully, in which case an error message would appear. If this is the case, then delete the remaining WSS sites or SSRS reports by following the directions in section Resolving Failures.

Second, it is possible that version control data has been flagged for deletion but not actually deleted. There are two approaches for resolving this issue. First, wait until the TFSVersionControl Administration Job has run, typically at midnight. Second, you can force the TFSVersionControl Administration Job to run by following the steps in the section How do I start or view the history of the TFSVersionControl Administrator job?.

Whenever I start the TFSDeleteProject tool, it stops whenever it cannot delete a component; however, I would still like it to delete the remaining components. How do I do this?

If TFSDeleteProject continues to fail after multiple invocations, try calling TFSDeleteProject with the /force flag. This action will force TFSDeleteProject to continue deleting areas, even if one component cannot be deleted.

How do I start or view the history of the TFSVersionControl Administrator job?

To start or view the history of the TFSVersionControl Administrator job

  1. Open Microsoft SQL Server Management Studio.

  2. In the Connect to Server dialog box, select Database Engine as the Server type.

  3. In Server name, select the database where the version control files are located.

  4. Click Connect.

  5. In the Object Explorer pane, expand SQL Server Agent and then expand Jobs.

  6. Right-click TFSVersionControl Administration Job.

    • To start the job, click Start Job at Step and then click Start.
    • To view the history, click View History.

How do I modify the DefaultTimeout value?

It is important to notice that although the directions in this document will increase the time-out time for functions in TFSDeleteProject, it will also increase the time-out time for all TFS Web calls. The purpose of the time-out time is to prevent the UI from becoming locked forever. Therefore, after you delete a project, you should return the time-out time to its default value of 10 minutes.

Note

Always use caution when modifying registry keys.

To modify the DefaultTimeout value

  1. On the client computer, open Registry Editor.

    For example, on Windows Vista, click Start, type regedit in the Start Search text box, and then press ENTER.

  2. For 32-bit operating systems, move to the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\TeamFoundation\RequestSettings.

    -or-

    For 64-bit operating systems, move to the key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\9.0\TeamFoundation\RequestSettings.

  3. Right-click DefaultTimeout, click Modify, and then enter a new time in decimals. Registry values are measured in milliseconds.

To create and modify the RequestSettings and DefaultTimeout keys if they do not exist

  1. In Registry Editor:

    For 32-bit operating systems, move to the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\TeamFoundation\RequestSettings.

    -or-

    For 64-bit operating systems, move to the key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\9.0\TeamFoundation\RequestSettings.

  2. Right-click HKEY_LOCAL_MACHINE\SOFTWARE\...\TeamFoundation, click New and then click Key.

  3. Type RequestSettings.

  4. Right-click RequestSettings, click New and then click DWORD Value.

  5. Type DefaultTimeout.

  6. Right-click DefaultTimeout, click Modify, and then enter a new time in decimals. Registry values are measured in milliseconds.

Conclusion

This white paper has provided you with background information about how TFSDeleteProject works, and how to trouble-shoot issues you encounter, so that you can successfully delete projects on your Team Foundation Server.