TFS Planning - Part 4 - Migration from VSS

Introduction

Microsoft provides a command line tool for migrating Visual SourceSafe databases to TFS. Before we begin the migration, it is better to analyze the VSS databases and gather some general information like Database Name, Database Size, Owner, user list and applications that reside in the databases. I am attaching a template for gathering this information in the resources section of this post.

Solution

Install Visual SourceSafe 2005 on the TFS 2008 server. Make a copy of the SourceSafe databases that need to be converted and place them on the TFS Server. It is risky to run the migration on the original databases. It is better to make a copy and then run the migration on the copy of the VSS databases. The process involves three steps namely copy, analyze and migrate. We need to run the migration utility in analysis mode and then cleanup our VSS databases based on the output of the analysis and then run the utility again in migration mode to do the actual migration.

Preparation

You will need to create three directories to organize your migration process. There will be a vssDatabases directory where all the databases that need to be migrated will reside. There will be a vssMigrate directory where the actual migration reports and output will be generated. I recommed putting the vssMigrate directory underneath visual studio directory where the migration executables are located. The third directory you will need is called TFS_Scripts and you can put this any where. I am putting this directory on my c: drive just to keep it separate from other directories but you can put it in another place if you like.

Solution Details

1. Install Visual Source Safe 2005 on the TFS 2008 Server
2. Create a new folder called c:\vssDatabases and put all source safe databases in there.
3. Create a new folder called …\Microsoft Visual Studio 8\Common7\IDE\vssMigrate. This is going to store all the migration reports and log files which will show if our migration completed successfully.
4. Create a new folder called c:\TFS_Scripts and put all your migration xml scripts in there. Later in this post we will see how to create these xml files.
5. Create a Settings.xml file which will contain migration analysis instructions.
6. Prepare the VSS databases for migration by running Analyze.exe to fix errors inside VSS databases. This should clean up the databases and make them ready for conversion. Run vssConverter.exe in analysis mode.
7. Create a MigrationSettings.xml file which contains the actual migration instructions.
8. Run vssConverter.exe in migration mode.

Sample command line instructions:-

-- Preparation work
mkdir c:\vssDatabases
copy DatabaseName c:\vssDatabases
cd c:\Program Files\Microsoft Visual Studio 8\Common7\IDE
mkdir vssMigrate
mkdir c:\TFS_Scripts

-- Simple instructions
cd C\Program Files\Microsoft Visual SourceSafe
analyze.exe -F -V3 -DB c:\vssDatabases\DatabaseName\data
analyze.exe -F -V3 -DB c:\vssDatabases\DatabaseName\data
analyze.exe -FP -V3 -DB c:\vssDatabases\DatabaseName\data

cd c:\Program Files\Microsoft Visual Studio 8\Common7\IDE
vssConverter Analyze vssMigrate\DatabaseName\Settings.xml
vssConverter Migrate vssMigrate\HistoricalDSS\MigrationSettings.xml

-- Instructions for use in a batch script
echo Step 1 - Run VSS Analysis
cd c:\Program Files\Microsoft Visual SourceSafe
analyze.exe -DB c:\vssDatabases\DatabaseName\data
analyze.exe -F -V3 -D c:\vssDatabases\DatabaseName\data
analyze.exe -DB c:\vssDatabases\DatabaseName\data

echo Step 2 - Run TFS Migration Analysis script
cd c:\Microsoft Visual Studio 8\Common7\IDE
VSSConverter Analyze c:\TFS_Scripts\Settings_DatabaseName.xml

echo Step 3 - Run TFS Migration
cd c:\Program Files\Microsoft Visual Studio 8\Common7\IDE
VSSConverter Migrate c:\TFS_Scripts\Migration_Settings_DatabaseName.xml

What does a Settings.xml file look like?

<?xml version='1.0' encoding='utf-8'?>
<SourceControlConverter>
<ConverterSpecificSetting>
<Source name='VSS'>
<VSSDatabase name='c:\vssDatabases\DatabaseName'></VSSDatabase>
</Source>
<ProjectMap>
<Project Source='$/'></Project>
</ProjectMap>
</ConverterSpecificSetting>
<Settings>
<Output file='Analysis.xml'></Output>
</Settings>
</SourceControlConverter>

What does a MigrationSettings.xml file look like?

<?xml version='1.0' encoding='utf-8'?>
<SourceControlConverter>
<ConverterSpecificSetting>
<Source name='VSS'>
<VSSDatabase name='c:\vssDatabases\DatabaseName'></VSSDatabase>
<UserMap name='D:\TFS_Scripts\Usermap.xml'></UserMap>
<SQL Server='gtnahouappv97' />
</Source>
<ProjectMap>
<Project Source='$/' Destination='$/tfsProjectName'></Project>
</ProjectMap>
</ConverterSpecificSetting>
<Settingsv
<TeamFoundationServer name='tfsServerName' port='8080' protocol='http'></TeamFoundationServer>
<Output file='Migration_Analysis.xml'></Output>
</Settings>
</SourceControlConverter>

Note:

The MigrationSettings.xml file can be used to control what projects need to be migrated. You can control if you would like to migrate everything or just a few projects. The $/ means migrate all projects. There is also a command line argument to set the migration date so that all changes beyond that date are migrated. If you ran the migration once and had some problems then you will need to use tfsDestroy command to destroy the source control project in TFS and then create a new TFS source control project using Team Explorer and then you can run

What does a UserMap.xml file look like?

<?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='grominger' To='domain\grominger' />
  <UserMap From='gcharles' To='' />
  <UserMap From='fred' To='' />
</UserMappings>

Note:

This UserMap.xml file is automatically created by the VSS Converter automatically. You can create this file yourself also if you would like to control the user mapping or modify the security on the TFS side. For example, <UserMap From='Jane' To='MyDomain\Janep'></UserMap> This mapping causes all actions logged by VSS user “Jane” to be changed to Team Foundation user “ MyDomain\Janep ” during the migration so you can change version tracking history. Leaving the To field blank will keep the original credentials as they are. If a user line is removed then that user will not be added to the TFS security database.

Resources:

• Migration Planning [Excel Format]

Navigation:

• Part 3