This post describes a strategy for configuring a virtual machine image to use for conversion of source code from VSS to TFS. It uses a virtual machine image and developers that are ready to do a conversion launch an instance of the virtual machine with the migration prerequisites already installed. By simplifying and streamlining the process to a few steps and pre-configuring the necessary software on a virtual machine image that developers can use to do their own conversion, we have successfully worked with organizations to migrate hundreds of applications in a short amount of time.

If you are a small shop or one man team, you can follow the same steps to configure your development machine, rather than using a virtual machine, then just use your normal development machine to run the conversion.

1. Install Visual SourceSafe 2005.
   
   1. NOTE: This is required by the conversion tool, even if you are currently using VSS 6.
      
2. Install Visual Studio Team System 2010 Team Explorer.
   
   1. NOTE: This is required by the conversion tool to provide the components to allow the tool to communication with the 2010 Team Foundation Server. Even if you are using Visual Studio 2005 or 2008 and have already installed the Team Explorer 2005 or 2008, you still need to install Team Explorer 2010. It will not interfere with the other versions of Team Explorer.
      
3. Using Windows File Explorer, create a local folder called “VssToTfsMigration”, which will be the root folder for all your project migrations.
   
4. Copy the conversion tool to a more convenient location.
   
   1. The conversion tool is found in your C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE folder, after you install either Visual Studio 2010 or Team Explorer 2010.
      
   2. Copy VssConverter.exe and VssConverter.exe.config to the VssToTfsMigration folder you created above.
      
   3. NOTE: This is the converter that will perform the conversion for all your projects. To perform the conversion it will make use of the Visual SourceSafe 2005 that you installed above to read your VSS database, and it will make use of the Visual Studio Team System 2010 Team Explorer components that you installed above to move the source into TFS 2010.
      
5. If you do not have SQL Express installed, install it. SQL Express is installed by default with Visual Studio, so you probably already have it.
   

This completes the configuration of the virtual machine image. The next step is to send the image back to your infrastructure group who will clone it to create a few available instances if it.

Then your developers can follow instructions such as the ones below:

INSTRUCTIONS FOR DEVELOPERS TO MIGRATE USING THE VIRTUAL MACHINE

 

This topic explains how to prepare your environment for migration.

Note:

We have configured a dedicated virtual machine that you will use for migration. This machine has all the required migration prerequisites installed. You use the dedicated VM to perform the migration, then return to using your own VM Dev box for your development.

Follow the instructions below to prepare your migration environment.

1. If you need to migrate only partial history, archive the unwanted history in VSS. For more information, see How to: Migrate a Partial History Using Archives in Visual SourceSafe. If you’re unsure about what to do regarding your history, see the guidelines in Migration Tool Questions and Answers
   
2. Log on to one of the dedicated Migration VMs. There are 2 instances of this VM available. If one is busy, try the other one. The machines are at:
   

• 172.25.2.197
  
• 172.25.2.198
  

Don’t Forget:

Please don’t forget to log off after you’re finished, as these machines are used by everyone to migrate.

• Prepare the destination folder or project in Team Foundation Server. This is where you migrated source code will go to.
  
  • If you are doing a Trial Migration:
    
    • Launch Visual Studio 2010.
      

    Caution:
    

    Do not use the Visual Studio 2005 installation since it does not have the necessary add-ons to connect to Team Foundation Server.
    

    • Create an empty source control folder in the Sandbox project on the Dev Team Foundation Server. Give this folder an appropriate name for the project you’ll be putting there. This will be the target folder for your Trial Migration.
      

    Note:
    

    Strictly speaking, you don’t need to create this destination folder manually. In the migration procedure, if you specify this folder and it doesn’t exist, it will be created for you. However it’s advisable to create it manually to ensure that it’s unique because other teams are sharing the Sandbox project for their trial migration.
    

    Note:
    

    Unsure whether you need to do a trial migration? In many cases you can migrate straight to production. See Introduction to Code Migration with the Migration Tool for guidelines.
    

  • If you are doing a Production Migration:
    
    • Have the Team Foundation Server Administrator create a project for you in the production Team Foundation Server. See Obtaining a Team Foundation Server Project..
      
• Create a File Folder for the migration control files.
  

1. Locate the c:\VssToTfsMigration folder which has already been created for you on the Migration VM
   
2. Create a [MyProject] folder, where MyProject is the name of the project you’re migrating. For instance if your project is Contoso create the folder c:\VssToTfsMigration\Contoso.
   

• Obtain the admin password for the VSS database that you will migrate. You will need this to run the migration, even though the migration is read-only.
  

The migration process is controlled by two XML settings files you create with Notepad. This topic explains how to create the necessary files.

• Before starting, ensure you have completed the steps in Prepare Your Migration Environment.
  

Create a Settings File for Analysis

1. Open File Explorer, select the [MyProject] folder and click File, New, Text Document. Name the file AnalysisSettings.xml. Right click the file and click Edit.
   
2. Copy the text below into the new Notepad file:
   

   <?xml version=”1.0″ encoding=”utf-8″?>
   

   <SourceControlConverter>
   

   <ConverterSpecificSetting>
   

        <Source name=”VSS”>
   

             <VSSDatabase name=”\\Vss3\shared\Contoso\ContosoDotNet”></VSSDatabase>
   

             <UserMap name=”Usermap.xml”></UserMap>
   

        </Source>
   

        <ProjectMap>
   

             <Project Source=”$/ContosoDuplicateUtility”></Project>
   

        </ProjectMap>
   

   </ConverterSpecificSetting>
   

   <Settings>
   

        <Output file=”Analysis.xml”></Output>
   

   </Settings>
   

   </SourceControlConverter>
   

3. Modify the VSSDatabase name to point to the path to your VSS database.
   
4. In the <ProjectMap> section, specify the Visual SourceSafe folders to analyze.
   

Note:

You can specify multiple source folders in the <ProjectMap> section. For each folder you specify, all subfolders are automatically included. To specify multiple source folders, simply create multiple <Project Source…> lines.

1. Save the file.
   

Create a Settings File for Migration

1. In the same folder, create a file called MigrationSettings.xml.
   
2. Copy the text below into the new Notepad file:
   

    
    

<?xml version=”1.0″ encoding=”utf-8″?>

<SourceControlConverter>

<ConverterSpecificSetting>

     <Source name=”VSS”>

          <VSSDatabase name=”\\Vss3\shared\Contoso\ContosoDotNet”></VSSDatabase>

          <UserMap name=”Usermap.xml”></UserMap>

     </Source>

     <ProjectMap>

          <Project Source=”$/ContosoDuplicateUtility” Destination=”$/Sandbox/ContosoDuplicateUtility”></Project>

     </ProjectMap>

</ConverterSpecificSetting>

<Settings>

     <TeamFoundationServer name=”tfsdev2″ port=”8080″ protocol=”http” collection=”tfs/DefaultCollection”></TeamFoundationServer>

     <Output file=”Migration.xml”></Output>

</Settings>

</SourceControlConverter>

1. Modify the VSSDatabase name to point to the path to your VSS database.
   
2. Edit the ProjectMap section. As before, you can add multiple lines in this section, or just modify the single line that’s in the file. Each line maps a VSS folder to a destination in Team Foundation Server.
   

Tip:

If you created multiple <Project Source…> lines in the Analysis Settings file, then you should create the same number of lines here, and you should map each line to a destination folder.

1. Ensure the target TFS server is correct. If you are doing migration to the Sandbox TFS, leave the server as it is (tfsdev2). If you are doing migration to the Production TFS instead of the Sandbox, change the TeamFoundationServer name to tfsprd01.
   
2. Save the file.
   

In this topic, you’ll perform the analysis phase of the migration.

1. Open a Visual Studio command prompt and navigate to the VssToTfsMigration/MyProject folder you created in the step Prepare Your Migration Environment.
   
2. Type the following command:
   

..\VSSConverter Analyze AnalysisSettings.xml
 

1. When you are prompted, provide the Visual SourceSafe administrator password.
   

The converter tool displays the status of the pre-conversion analysis. When it is completed, it generates a report and a user mapping file, and saves them in the current directory.

1. Open the file Analysis.xml which is generated by the analaysis process. It contains information about the VSS folders that you analyzed. Ensure that everything looks as expected. An example is below:   

In this topic, you’ll edit the user
map file that controls how VSS
users are mapped to TFS
users.

The analysis phase generated a user map file. The user
map file consists of all Visual SourceSafe users who have performed any source control operation on the folders that you specified for the migration. You use this file to map Visual SourceSafe users to Team Foundation users so that change history is preserved on a user by user basis.

To customize the user map file

1. Open the file usermap.xml with notepad. The file looks similar to the following.
   

<?xml version=”1.0″ encoding=”utf-8″?>

<UserMappings>

<UserMap From=”maryjane” To=”" />

<UserMap From=”bobbysue” To=”" />

<UserMap From=”jonesharry” To=”" />

<UserMap From=”smithtim” To=”" />

</UserMappings>

1. For each Visual SourceSafe username you want to map, add a valid Windows user name or Team Foundation Server user name in To field, as shown in the following example. The ADMIN user in VSS should be mapped to a real user in TFS, typically the project administrator. Users in VSS who are no longer with the company should be mapped to existing users.
   

<?xml version=”1.0″ encoding=”utf-8″?>

<UserMappings>

<UserMap From=” maryjane” To=”maryjane” />

<UserMap From=” bobbysue” To=”bobbysue” />

<UserMap From=” jonesharry” To=”jonesharry” />

<UserMap From=” smithtim” To=”smithtim” />

</UserMappings>

1. Save the file.
   

 

In this topic, you perform the migration.

Stop:

Before you migrate from Visual SourceSafe to Team Foundation version control, you must:

1. Read Preparing to Migrate Code to Team Foundation Server.
   
2. Prepare Your Migration Environment.
   
3. Prepare your VSS Database and Migration Setting Files.
   
4. Analyze your VSS Database for Migration.
   
5. Edit the Source Control Migration User Mapping File.
   

Perform the Migration

1. Open a Visual Studio command prompt and navigate to the VssToTfsMigration/MyProject folder you created in the step Prepare Your Migration Environment.
   
2. At the command prompt, type the following:
   

..\VSSConverter Migrate MigrationSettings.xml

 
 

1. Press Y to confirm the migration when prompted. Enter the VSS admin password when prompted
   
2. The converter tool displays the migration status. When the conversion process is completed, the tool saves a post-migration report in the current directory. You can use Internet Explorer to view the file for detailed information.
   

 

A partial migration can be performed after migration to migrate any files that were missed. For instance if a file was checked out it will not be migrated.

Each case will vary, but if you find that there are files that did not migrated you have the choice of doing a partial migration to move them or simply adding those files to the Team Foundation Server source manually.

To Perform a Partial Migration

1. Ensure the TFS destination subfolder that you want to re-migrate to is empty in TFS.
   
2. Define a new source and destination in your migrationSettings.xml file.
   
3. Rename or delete Migration.xml file (which gives you a report of VSS Converter during the migration) for each new migration or otherwise you cannot run VssConverter.exe
   

1. Re-run the migration.
   

If the migration fails or you make a mistake, you can re-run the migration. Just delete the files or the complete project from Team Foundation Server, check in the delete change, and start again.

Or you can ask your Team Foundation Server Administrator to delete and recreate the Team Foundation Server project.