Recently I had to migrate parts from a Microsoft Visual SourceSafe 2005 repository to a Microsoft Team Foundation Server 2010 repository. In this blog post I show what I had to do and what the pitfalls were.

The tool

To migrate a repository you have at least two possibilities: Migrate the latest snapshot or the whole history. Normally you prefer a migration of the whole history, so you don’t loose the gained advantage of an version control system.

To migrate a repository from Visual SourceSafe (VSS) with the complete history, there exists a tool, which comes with Visual Studio: vssconverter.exe. You find the tool in the following directory: C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE.

To migrate a repository or just a part of it from VSS to Team Foundation Server (TFS), you have to process two steps: Analyse and Migrate.

There is quite a good documentation about the process and the tool itself at the MSDN.

Analyse step

In the Analyse step the VSSConverter tool checks if there are any problems and creates an user mapping file.

To start the analyse step, you have to enter the following at the command line:

vssconverter.exe analyze analyzesettings.xml

The analyzesettings.xml file looks like the following:

<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
<ConverterSpecificSetting>
     <Source name="VSS">
          <VSSDatabase name="\\server\vss"/>
          <UserMap name="Usermap.xml"/>
     </Source>
     <ProjectMap>
          <Project Source="$/Project/Scripts/Func"/>
          <Project Source="$/Project/Scripts/Proc"/>
          <Project Source="$/Project/Scripts/Trig"/>
          <Project Source="$/Project/Scripts/View"/>
     </ProjectMap>
</ConverterSpecificSetting>
<Settings>
     <Output file="AnalysisReport.xml"/>
</Settings>
</SourceControlConverter>

The result of the execution of the command line are two files: Usermap.xml and the AnalysisReport.xml. You can open the AnalysisReport.xml to see if there are any problems. The Usermap.xml file you have to modify before you can continue with the next step.

In the user mapping file (Usermap.xml) you map the VSS users to the users you use with the TFS. This file looks like the following:

<?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="michael" To="DOMAIN\michael"/>
  <UserMap From="john" To="DOMAIN\john"/>
  <UserMap From="ADMIN" To="DOMAIN\michael"/>
</UserMappings>

I had some troubles here with the correct domain name. The problem result that the user mapping didn’t work during the migration and all history entries had me as user. So I had to destroy the migrated items in the TFS repository with the following command line statement:

tf.exe destroy $/Project/Main/Source/Data/Project/SQL

After that, I corrected the Usermap.xml file and started the migration step again.

Migration step

For the migration step you need a migration setting file. A such file looks like the following:

<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
<ConverterSpecificSetting>
     <Source name="VSS">
          <VSSDatabase name="\\server\vss"/>
          <UserMap name="Usermap.xml"/>
     </Source>
     <ProjectMap>
          <Project Source="$/Project/Scripts/Func" Destination="$/Project/Main/Source/Data/Project/SQL/Func"/>
          <Project Source="$/Project/Scripts/Proc" Destination="$/Project/Main/Source/Data/Project/SQL/Proc"/>
          <Project Source="$/Project/Scripts/Trig" Destination="$/Project/Main/Source/Data/Project/SQL/Trig"/>
          <Project Source="$/Project/Scripts/View" Destination="$/Project/Main/Source/Data/Project/SQL/View"/>
     </ProjectMap>
</ConverterSpecificSetting>
<Settings>
	 <TeamFoundationServer name="tfs" port="8080" protocol="http" collection="tfs/DefaultCollection"/>
     <Output file="MigrationReport.xml"/>
</Settings>
</SourceControlConverter>

This setting file looks quite similar to the analyse setting file. But in the ProjectMap section you have the destination attribute where you define the directory in the TFS repository where you want to migrate the VSS data.

In the Settings section there is an important entry TeamFoundationServer. For TFS 2010 you have to define the attribute collection. It wont work without this attribute.

You start the migration with the following command line statement:

vssconverter.exe migrate migratesettings.xml

As a result of this statement you will receive a MigrationReport.xml file, which you can watch in a browser if there were any problems. I recommend also to have a look in the VSSConverter.log file. There are some valuable additional information.