Milinda Pro: Migrating from Visual SourceSafe to Team Foundation (VSS to TFS)

This post will describe how to totally migrate a Visual Sorcesafe database to Team Foundation Server. After migration the database you will have all the details on VSS database such as your source codes, users, and version history, etc...

There are some prerequisites which you should consider before start the migration process. Those are,

Team Explorer on Visual Studio.
Log on to the computer by using administrative credentials.
SQL Server Express.
Visual SourceSafe 2005 or later versions.
The Visual SourceSafe database that you want to analyze.
The administrator’s password for the Visual SourceSafe database.

And also some permissions, Therefore To perform the procedures in this post, you must have the following permissions.

In the Visual SourceSafe database that contains the data that you want to migrate, you must know the password of the Admin account.
On the migration machine (the machine where Visual Studio is installed), you must be a member of the Administrators group.
On the database that VSSConverter uses, you must have "create database" permission.
Be a member of the sysadmin server role for SQL Express. (By default, you are a member of the sysadmin server role if you are a member of the Administrators security group on the computer where SQL Express is installed.)
On your application tier for Team Foundation, you must be a member of the Team Foundation Administrators security group. For more information, see Team Foundation Server Permissions on MSDN.

Basically there are 3 main steps involved on migration.

Preparing the Visual SourceSafe Database

Analyzing the Projects for Migration.

Migrating SourceSafe Project Folders to TFS

1. Preparing the Visual SourceSafe Database
This step also can be break down into three steps.

Ask all database users to check in their files.
Create a backup copy of your Visual SourceSafe Database to migrate.
Use the Visual SourceSafe Analyze utility to locate and fix data integrity issues in the database.

a. Ask all database users to check in their files.
You should make sure that all the users are not loged-in to the VSS and all the files are checked in to the VSS.

So you can check loged in users from "Microsoft Visual SourceSafe Administration" tool. (Start --> All programs --> Microsoft Visual Sorcesafe --> Microsoft Visual SourceSafe Administration).

Also you can list all the check out files with the checked out user by issuing following command on cmd.
Here we are using ss.exe which is supplied by VSS therefore you should change the directory to VSS installation path.
Ex:- cd "C:\Program Files\Microsoft Visual SourceSafe"

If you need user wise list, type following command on cmd: ss status -R -Umilinda > "C:\Users\milinda\Desktop\VSS Checkouts\milindaCheckouts.txt"
This command will save all the files those checked out by milinda to the C:\Users\milinda\Desktop\VSS Checkouts\milindaCheckouts.txt file.
If you need all the checked out files list, type following command on cmd: ss status -R > "C:\Users\milinda\Desktop\VSS Checkouts\allCheckouts.txt"
This command will save all the files those checked out by all users to the C:\Users\milinda\Desktop\VSS Checkouts\milindaCheckouts.txt file.

b. Create a backup copy of your Visual SourceSafe Database to migrate.
Make sure that no one is using the database and that Analyze will not begin to run while you are backing up the database. To backup the VSS database just copy the following folders and files which are located on sorcesafe's database path. (You may find this database path from Visual SourceSafe Explorer File --> Open sorcesafe databse or press Ctrl+P).

\DATA
\Temp
\USERS
user.txt
srcsafe.ini

When you follow this procedure, you can do a full restore of the database by replacing the existing Users, Temp and Data folders as well as the Users.txt and Srcsafe.ini files with the copied versions.
You can also use this procedure to move the database to another location by placing the copied files into a new folder. To open the database, on the File menu in the Visual SourceSafe Explorer, click Open SourceSafe Database to browse to the new location.

c. Use the Visual SourceSafe Analyze utility to locate and fix data integrity issues in the database.

Just run analyze.exe on command prompt as “analyze -F -V3 <sourcesafe data directory>”which is located on “C:\Program Files\Microsoft Visual SourceSafe”

-F stands for fix, This will automatically repairs inconsistencies and corruption that are detected, as long as no users are logged in.

-V3 to displays all errors.

More command line options can be found here.

Remember you should give the data path (\DATA) as argument not the database path which you found from Visual SourceSafe Explorer.

As my experience it will take 3 hours to 4 hours time duration to complete the analysis on 4.2GB database. Somehow this duration depends on errors on your database also.

Now preperation of Visual SourceSafe Database is finished. Let's move to next step.

2. Analyzing the Projects for Migration.

This process is based on xml input file. After running this step you will get an user mapping file and analyze report file which are needed for next step.

VSSConverter.exe tool is used to analyze the VSS projects that located on “C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE”. But still you can be invoked it from the Visual Studio command prompt. Or simply cd to the above path from cmd and follow the following commands.

My recommendation is copy VSSConverter.exe and VSSConverter.exe.config file to a different location and perform following commands.

VSSConverter.exe accepts following inputs to perform its operations

A path of the folder that contains the srcsafe.ini file for the Visual SourceSafe database under migration.
An XML-based file that contains settings.

This path you may find on Visual SourceSafe Explorer (File --> Open sorcesafe databse or press Ctrl+P)

The XML-based file format is,

<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
      <ConverterSpecificSetting>

            <Source name="VSS">
                  <VSSDatabase name="VSSDatabase_name"></VSSDatabase>
            </Source>

            <ProjectMap>
            <Project Source="$/FolderA"></Project>
            <Project Source="$/FolderB"></Project>
            </ProjectMap>

      </ConverterSpecificSetting>

      <Settings>
       <Output file="Analysis.xml"></Output>
     </Settings>
</SourceControlConverter>

Modify the VSSDatabase_name to point to the path to your VSS database.
In the <projectmap> section, specify the Visual SourceSafe folders to analyze.

To analyze the whole database, use <Project Source="$/"></Project>

Save above XML file as settingsAnalyze.xml to the directory where VSSConverter.exe and VSSConverter.exe.config file located.

Now you can run the converter tool to analyze VSS projects. The user who is performing the analysis must be a system administrator for SQLExpress. By default, the user who installs Visual Studio will receive the required permissions for SQLExpress.

cd to directory where VSSConverter.exe and VSSConverter.exe.config file located and run following command

VSSConverter Analyze settingsAnalyze.xml

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 (VSSAnalysisReport.xml) and a user mapping file (usermap.xml), and saves them in the current directory.

You can use this user mapping file to map Visual SourceSafe users to Team Foundation users.

3. Migrating SourceSafe Project Folders to Team Foundation Server

The converter also needs an xml file. It is most similar to settings.xml file which is created at analyze step. Therefore,

Copy settingsAnalyze.xml file content and save it as settingsMigration.xml. (Ensure that the system drive has sufficient space to hold the largest file size under migration.)

Change the settings file as follows.
- In the <ProjectMap> sections, for each Visual SourceSafe folder, add the destination folders in TFS. This destination should be already created on TFS.
  
  <Project Source="$/FolderA" Destination="$/Team_ProjectA"> </Project>
- To migrate everything in your Visual SourceSafe database, insert the following XML instead.
  
  <Project Source="$/" Destination="$/Team_Project/"> </Project>
- Under the <Settings> section, add a <TeamFoundationServer> section, and specify the name, port, and protocol for the Team Foundation Server to which you are migrating. Use the following format. Here you should set the collection to a collection that you created on TFS insted of 'DefaultCollection'.
  
  <TeamFoundationServer name="TFS_server_name" port="port_number" protocol="http" collection="tfs/DefaultCollection"></TeamFoundationServer>
- Remove <Output file="Analysis.xml"></Output> from the <Settings> section, or rename the output file to "migrationAnalysis.xml".


<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
   <ConverterSpecificSetting>
      <Source name="VSS">
         <VSSDatabase name="VSSDatabase_name"></VSSDatabase>
         <UserMap name="c:\Migrate\Usermap.xml"></UserMap>
      </Source>
      <ProjectMap>
         <Project Source="$/FolderA" Destination="$/TeamProjectA">
         </Project>   
         <Project Source="$/FolderB" Destination="$/TeamProjectB/ProjectB">
         </Project>
      </ProjectMap>
   </ConverterSpecificSetting>
   <Settings>

      <TeamFoundationServer name="server_name" port="port_number" protocol="protocol" collection="tfs/DefaultCollection"></TeamFoundationServer>

    </Settings>
</SourceControlConverter>

Edit the Source Control Migration User Mapping File
If you want to map user name to TFS from VSS as it is, you can keep usermapping.xml file remain unchanged and go to next step.

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.

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.

For example,

<?xml version="1.0" encoding="utf-8"?> <UserMappings> <UserMap From="Admin" To="MYDOMAIN\Jennifer"></UserMap> <UserMap From="guest" To="TestAlias1"></UserMap> <UserMap From="Jane" To="Jane"></UserMap> <UserMap From="Mike" To=""></UserMap> </UserMappings>

If you provide a user name mapping similar to <UserMap From="Mike" To=""></UserMap> where "Mike" is a valid Windows user name, Team Foundation maps "Mike" to "MYDOMAIN\Mike," where MYDOMAIN is the default domain.

Before you run the following command you should create the team project as you define on settingsMigration.xml file. You can refer this to create new team project
Execute following command on cmd to migrate the VSS database to TFS as you define in above xml files.
VSSConverter Migrate settingsMigration.xml

When you are prompted, provide the password for the Visual SourceSafe admin user.

So that is it.........
After long post, you may have a totally migrated TFS database from VSS with all the VSS data such as source files, histories, users, etc..

The whole process takes 6-7 hours time duration to migrate 4.2GB VSS database. But this may change up to your database size, users, histories, network speed, etc.

I apologize, If this post is getting too long but these are the basic step that you should follow to migrate. Have a nice day thanks.

Milinda Pro

Pages

Migrating from Visual SourceSafe to Team Foundation (VSS to TFS)

1 comment: