VSS to Team System Migration Checklist

26 בספטמבר 2006

8 תגובות

Today we are migrating yet another client VSS database into Team System. Not first one and probably not the last. Migration is multistage process. You can find documentation for each part in MSDN. Here I would like to combine it into single checklist and complete with some our additions and clarifications.


  • Visual Source Safe 2005. Note: It is not included with VSTS installation or with VS2005. VSS2005 client is compatible with VSS6 database, you can install it safely.
  • VSSConverter.exe utility. Installed with Team Explorer. It is located usually in [C]:\Program Files\Microsoft Visual Studio 8\Common7\IDE\
  • List of users for Team System. You will need user names including domain as it defined in AD
  • Team Explorer – should be installed on each TS client.
We advise to run migration on TF server machine. In this case you need to insure all 3 utilities installed there.

  • SQL Server Express (if you are not performing migration on server machine) – Installed by default with Visual Studio 2005.

  • Make sure you have VSS administrator user/password and TS Project Administrator user/password.
  • Ask your team members to check in their files and disconnect from VSS (make sure they close IDE and VSS explorer). Updated checked out file versions will not be migrated into VSTS. If you absolutely can not check in, back it up and check in directly into VSTS after migration. Use VSS Admin tool to monitor logged in users. Use VSS Explorer to find checked out files (View>Search>Status Search).
  • Copy your VSS database. By performing this action you will achieve two goals: 1. VSS backup. Backup is important because VSS Analyze operation is potentially dangerous, it can (and without backup, according to Murphy's Law, definitely will) effectively destroy your database.
    2. Copying database to TFS machine will allow migration process to run locally. Migration is a very heavy operation, running it locally will greatly speed up the whole process.
  • Prepare Team Foundation Project. To perform migration you need Team Project with source control repository. Add users to appropriate project groups. To associate files' revisions with actual users you will need to map those users to VSS users.
  • Decide which VSS folders you would like to migrate and what will be your source tree structure in TFS. Many organizations use migration process as a convenient opportunity to rethink the project structure. If you are planning to do it, we strongly suggest you reconsider. a better idea is to migrate sources as is, check new source control validity and then restructure your projects. This approach is much safer.
Analyze Stage
At this stage VSS database analyzed for potential problems, and attempts made to fix as many problems as possible. Run Analyze.exe utility on VSS database (copied on the previous stage). We suggest using it with analyze –fp –v4 options. Make sure that the backup directory, located inside the data directory of VSS, is empty before you are running the tool. You can safely empty backup directory if it contain files. See http://msdn2.microsoft.com/en-us/library/ysxsfw4x.aspx for complete description of analyze.exe utility.

Migration Stage. Finally: Converting…
At this stage you should run VSSConverter.exe utility twice. First time to check VSS database for potential data loses and retrieve list of VSS Users. There is some information that can not be preserved in process of migration. To summarize, VSS Sharing, Branching and Pinning are not supported in Team System (implemented differently). See complete list of limitation here. The VSSConverter utility accepts an xml configuration file as parameter. You should specify in the configuration location of VSS database and VSS project path for each project you want to migrate. See attached analyze configuration file sample.
Use "$/" to analyze/migrate complete VSS database.
Using "$" without "/" will cause VSSConverter to hang.

Run VSSConverter analyze <configuration file name> .
You’ll need to provide the VSS admin password when prompted.
Have some coffee…

After the stage is finished, the utility produces UserMapping.xml file containing a list of all VSS users that performed at least one operation on the VSS database. Complete the mapping file with TFS user names. You’ll need to specify user names including the domain (MyDomain\MyUserName).
Check list of expected data losses in VSSMigrationReport.
Specify in configuration file Team Foundation Server name and port (8080 by default), and Destination path for each project being migrated. See migration configuration file sample.

Run VSSConverter migrate <configuration file name> .
Confirm migration and supply VSS admin password.
Go to see a long movie… Expect migration to take hours, 5 to 10 times longer then analyze.
Congratulations, you are done!
Connect your IDE to TFS and enjoy the ride.

Migration works for us smooth and easy, as long as we performing it step by step according to this checklist. Use it and let us know about any additions or problems you encounter.

Attached Files

  • VSSAnalyze.bat – Analyze VSS database
  • analyze.bat – Execute VSSConvert.exe analyze
  • migrate.bat – Execute VSSConvert.exe migrate
  • VssSetting_Analyze.xml – Sample configuration for analyze
  • VssSetting_Migration.xml – Sample configuration for migration
  • UserMap.xml – Sample user mapping file
Sample configuration files asume that both Team Explorer and VSS installed in default directory, VSS database located at "C:\Migration\SourceSafe" (location of srcsafe.ini), The whole VSS database being migrated (<PROJECT Source="$/"></PROJECT>), destination root project path in Team System is "$/Common", TF Server name is teamsys and port 8080.

הוסף תגובה
facebook linkedin twitter email

כתיבת תגובה

האימייל לא יוצג באתר. שדות החובה מסומנים *

8 תגובות

  1. Justin-Josef Angel26 בספטמבר 2006 ב 19:46

    This is diffidently Webcast material.
    You should consider doing a 30 minutes screen-cast of these entire process.

    Great Job! This is excellent reference.

  2. Leon26 בספטמבר 2006 ב 21:10

    Thanks Jastin,
    The problem is that it is more like 4-5 hours pretty boring demonstration… 🙂
    On the more serious note, you really think such a cast will be helpful?

  3. Asher26 בספטמבר 2006 ב 23:19

    I think a web-cast is a good idea. if you have a small VSS DB then the migration is relatively fast.
    I'd like to hear about handling branches/pinning/shares and how can they can be handles…..
    The have a web-cast on the Microsoft US site, but it’s simply awful. I couldn’t understand a word the guy says (some people in MS have accents that are….. well you know… it’s not English its indglish)

  4. Ahitana30 באוקטובר 2006 ב 17:51

    I have one doubt. If I have the srcsafe.ini in my local computer and the team foundation server is another machine, how can i migrate the sourcesafe database? Because I have a lot problems with permissions, because of my user machine is different to the TFS administrator.

  5. Leon30 באוקטובר 2006 ב 18:32

    Hi Ahitana,
    As I said in "Preparation" section, I suggest you to copy your VSS db to the TFS machine. This way you backing up your vss db and also shorten migration time.
    If for any reason you can not copy vss db, run migration from TFS machine under TFS administrative user. In this case VSS db shared directory should be accessible from TFS machine.
    Let me know if this helps,

  6. Eyal2 בנובמבר 2006 ב 9:20

    You might also want to check out the utility I wrote which is a GUI frontend to the VSSConverter.exe command line utility: http://www.epocalipse.com/blog/2006/04/06/vssconverter-gui/

  7. Data Migration28 בספטמבר 2010 ב 11:29

    Oh ! great Thanks for sharing such good stuff..