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.
- 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.
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
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.
- 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