TFS Is Back : Migrate from VSS to TFS 2010

With Team Foundation Server 2010, Microsoft still did not provide a fully automated tool for migration from Visual SourceSafe.

In fact, the MSDN guide on migration from Visual SourceSafe is about 14 screens long on my monitor and does not cover in much detail some related actions such as backing up and restoring single projects from a SourceSafe database or creating a new Team Project, only providing links to other MSDN guides and articles.

We have a huge Visual SourceSafe database here which, quite frankly, may fall over any time due to sheer size or the fact that it has not been analysed for a few years. There is no way it is going to be converted to TFS fully, as it holds heaps of stuff that just does not belong there. So each developer will probably move projects he or she is responsible for.

Below is my take on a complete instruction for migrating a project from Visual SourceSafe to TFS 2010, using Visual Studio 2010, that I prepared for other developers.

1. Before you begin

1.1. Machine configuration

• Install Visual Studio on the machine that will perform the migration
• Install Visual SourceSafe 2005
• Install the update that is associated with article 950185 in Microsoft Knowledge Base
• Make sure you know the SourceSafe database admin password

1.2. Permissions

• Know the Admin password to the Visual SourceSafe database
• Be an Administrator of your PC
• Be a member of TFS Server Administrators or Collection Administrators

2. Backup and restore SourceSafe project

2.1. Backup SourceSafe project

2.1.1. Use the command line tool

For this example, the \\Server\VSS\database\VSS-DB SourceSafe database and $/MyRoot/MyProject projects were used.

The backup and restore tools, ssarc and ssrestor are located in the SourceSafe folder, usually C:\Program Files\Microsoft Visual SourceSafe. From the command prompt, navigate to that folder and run the command

ssarc -d- -i -yadmin,password -s\\Server\VSS\database\VSS-DB CodeProject.ssa "$/MyRoot/MyProject" (replace password with SourceSafe admin password, and specify the desired SourceSafe database location and backup database name).

If the warning "For reliability and performance reasons using the analyze, archive and restore utilities over network is not recommended. Do you want to continue? (Y/N)", select Y.

The command will create a backup database CodeProject.ssa in the Visual SourceSafe folder.

2.1.2. Use the Visual SourceSafe Administration UI

• Run Start → Programs → Microsoft Visual SourceSafe → Microsoft Visual SourceSafe Administration
• Select Archive → Archive Projects from menu
• Select a project to back up
• Select "Next"
• Select "Save Data to File", point to the location of the file
• Select "Next"
• Select "Archive all of the data"
• Select "Finish"
• The message box "Archive/restore successfully completed" will appear

2.2. Create an empty local SourceSafe database

• Create a folder for a new SourceSafe database (i.e. "D:\VSSTFSTransfer")
• Start Visual SourceSafe 2005
• Select File → Open SourceSafe database
• Choose "Add"
• "Add SourceSafe Database" wizard will start
• Select "Next"
• Select "Create a New Database"
• Select "Next"
• Browse to the folder you created, select it and select "Next"
• Specify the name for the database (can use default) and select "Next"
• Leave default Team Version Control model and select "Next"
• Choose "Finish"
• Close Visual SourceSafe 2005

2.3. Restore a project to an empty SourceSafe database

2.3.1. Use the command line tool

From the command prompt, navigate to Visual SourceSafe folder and run the command

ssrestor "-p$/MyRoot/MyProject" -sD:\VSSTFSTransfer -yadmin,password CodeProject.ssa "$/MyRoot/MyProject"

The command will restore the project into the SourceSafe database located in D:\VSSTFSTransfer.

Open the database with Visual SourceSafe to verify files were restored.

2.3.2. Use the Visual SourceSafe Administration UI

• Run Start → Programs → Microsoft Visual SourceSafe → Microsoft Visual SourceSafe Administration
• Select Archive → Restore Projects
• Point to the location where the backup database was saved
• Select "Next"
• Click "OK" on the warning
• Select the project to restore
• Select "Next"
• Leave the default choice "Restore to the project the item was archived from"
• Select "Finish"
• Click "OK" on the warning
• The message box "Archive/restore successfully completed" will show

3. Create a new Team Project

In Visual Studio 2010 open the "Team Explorer" tab. If you are not connected to the server, select "Connect to Team Project". If the server is not in the list, select "Servers". On "Add/Remove Team Foundation Server" select "Add". Fill in the TFS credentials.

On the "Connect to Team Project" screen choose the collection and project(s) to connect to and select "Connect".

In the "Team Explorer" tab, right-click the TFS server and select "New Team Project". Specify the name of the project and select "Next". Choose the process template and select "Next". Specify source control settings ("Create an empty source control folder" for a conversion project) and select "Finish". Visual Studio will create a new Team Project.

4. Analyse SourceSafe database

Before migrating the data, Visual SourceSafe Converter tool should be used to analyse any issues with the data.

4.1.1. Create a settings file

A settings file to use for the example above:

<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
 <ConverterSpecificSetting>
  <Source name="VSS">
   <VSSDatabase name="D:\VSSTFSTransfer"></VSSDatabase>
   <UserMap name="D:\VSSTFSTransfer\UserMap.xml"></UserMap>
  </Source>
  <ProjectMap>
   <Project Source="$/MyRoot/MyProject/"></Project>
  </ProjectMap>
 </ConverterSpecificSetting>
 <Settings>
   <Output file="D:\VSSTFSTransfer\Analysis.xml"></Output>
 </Settings>
</SourceControlConverter>

VSSDatabase is the path to the SourceSafe database to be converted.

UserMap is the path to the user map file to be created

ProjectMap lists all the projects to be converted. To convert the whole SourceSafe database, use the following:

<ProjectMap>
 <Project From="$/"></Project>
</ProjectMap>

Output file is the result of the analysis report.

4.1.2. Analyse the data

The VSSConverter utility is located in the Visual Studio 2010 Common folder, usually C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE

Save the settings file as settings.xml and run VSSConverter in the analysis mode, specifying the path to the settings file, i.e.

VSSConverter Analyze D:\VSSTFSTransfer\settings.xml

Enter the SourceSafe database password. If the process completes successfully, the Analysis.xml and UserMap.xml will be created in the D:\VSSTFSTransfer folder. Review and resolve issues found by the Analyze feature, if applicable.

4.1.3. Create a migration settings file

Modify the UserMap.xml. Here is the sample user map which is the output from the previous step:

<?xml version="1.0" encoding="utf-8"?>
<UserMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <UserMap From="Admin" To="" />
  <UserMap From="abc123" To="" />
  <UserMap From="def456" To="" />
  <UserMap From="ghi789" To="" />
</UserMappings>

For correct history migration, provide the "To" users in the user map. These are the valid Team Foundation Server users. Example:

<?xml version="1.0" encoding="utf-8"?>
<UserMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <UserMap From="Admin" To="MYDOMAIN\administrator" />
  <UserMap From="abc123" To="MYDOMAIN\abc123" />
  <UserMap From="def456" To="MYDOMAIN\def456" />
  <UserMap From="ghi789" To="MYDOMAIN\ghi789" />
</UserMappings>

Modify the settings file for migration.

<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
 <ConverterSpecificSetting>
  <Source name="VSS">
   <VSSDatabase name="D:\VSSTFSTransfer"></VSSDatabase>
   <UserMap name="D:\VSSTFSTransfer\UserMap.xml"></UserMap>
  </Source>
  <ProjectMap>
   <Project Source="$/MyRoot/MyProject" Destination="$/MyProject"></Project>
  </ProjectMap>
 </ConverterSpecificSetting>
 <Settings>
  <TeamFoundationServer name="MYTFServer" port="8080" protocol="http" collection="tfs/MyCol"></TeamFoundationServer >
  <Output file="D:\VSSTFSTransfer\Migrate.xml"></Output>
 </Settings>
</SourceControlConverter>

The Project Destination is the project name in the TFS.

The TeamFoundationServer settings are set according to the TFS Setup as shown in the screenshot.

Specify a name for the migration file output.

5. Run the migration process

5.1. Run the process

Run the converter tool with the migrate attribute.

VSSConverter Migrate D:\VSSTFSTransfer\settings.xml

5.2. Analyse the output and resolve issues

Check the errors and warnings in the Migrate.xml which was created by the migration too.

6. If something went wrong

If you’re not happy with the results, you can always delete the project from TFS 2010. Use on your own risk! Check the parameters, make sure that the spelling is correct, make backups, check again and make a local backup of everything just in case.

TFSDeleteproject /force /collection:http://MYTFServer:8080/tfs/MyCol MyProject

Read the warning and decide. Press Y to continue. Press enter.

Now you can start from scratch.

7. References and further information

Migrate from Visual SourceSafe
Team Foundation Server Permissions
Configuring Users, Groups, and Permissions
VSSConverter Command-Line Utility for Source Control Migration
TFSDeleteProject: Deleting Team Projects by Evgeny. Also posted on my website