Upgrade from Visual SourceSafe using the VSSUpgrade command-prompt tool
In most cases, you should use the VSS Upgrade Wizard instead of the VssUpgrade command-prompt tool to upgrade your Visual SourceSafe data. However, there are a few situations when you might want to use the VssUpgrade command-prompt tool to upgrade to an on-premises Team Foundation server (TFS).
To upgrade your Visual SourceSafe data using VSSUpgrade
Understand how the tool converts your data TFS and Visual SourceSafe have significant functional differences. As a result, the Visual SourceSafe upgrade tools modify certain kinds of data during the upgrade.
Prepare to upgrade Before you start the upgrade process, it’s critical that you plan ahead and prepare your data.
Important
You must run the Visual SourceSafe ANALYZE utility on your Visual SourceSafe repository before you proceed. See Copy and prepare your Visual SourceSafe database.
Learn about unique VssUpgrade features. If you don’t need any of them, then you should use the VSS Upgrade Wizard instead.
Analyze your data Before you upgrade your data from Visual SourceSafe to Team Foundation version control, you must use the Analyze command to determine whether any issues in your data will affect the outcome of the upgrade. This process also generates a user mapping file that is required to upgrade your data.
Upgrade your data To upgrade your data, you must specify how user names are upgraded, create a Migrate settings file, and then run the Migrate command.
View and verify the results, and resolve issues as necessary
VssUpgrade features
Use VssUpgrade if you want to upgrade and port your data to an on-premises team project and:
Perform the upgrade as part of an automated approach, such as a script.
Migrate multiple Visual SourceSafe projects into a single team project, using a folder structure that is specified by you.
Specify how user data is converted, for example, from Kim in Visual SourceSafe to EUROPE\KimT in TFS.
Ignore labels in the Visual SourceSafe data.
Resume the process after it has been interrupted while upgrading a large amount of data—for example, because of a network error.
If you don’t need any of these features, or if you need upgrade and port your data into a team project on Visual Studio Online, then you should use the VSS Upgrade Wizard instead of VssUpgrade.
Analyze your data
Before you upgrade your data from Visual SourceSafe to TFS version control, you must first use the Analyze command to determine whether any issues in your data will affect the outcome of the upgrade. This command also generates a user mapping file that the Migrate command uses to upgrade your data.
Create an Analyze settings file
Before you run the Analyze command, you must create an Analyze settings file. In this file, you specify the path of the Visual SourceSafe database that you will upgrade and the folders that you want to upgrade.
The following XML is an example of an Analyze settings file.
<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
<ConverterSpecificSetting>
<Source name="VSS">
<VSSDatabase name="c:\ourvss"></VSSDatabase>
<UserMap name="c:\ourvss\migrate\Usermap.xml"></UserMap>
<SQL Server="SQLInstanceName"></SQL>
</Source>
<ProjectMap>
<Project Source="$/Core"></Project>
<Project Source="$/ProjectA"></Project>
<Project Source="$/ProjectB"></Project>
</ProjectMap>
</ConverterSpecificSetting>
<Settings>
<Output file="c:\ourvss\migrate\logs\ContosoVSSAnalyze.xml"></Output>
</Settings>
</SourceControlConverter>
You can copy the previous example, paste it into your own Analyze settings file, and then modify it. The following information can help you adapt the example to meet your needs.
<?xml encoding> attribute
The <?xml encoding> attribute must match the encoding that is used in your Analyze settings file. For example, if the file is saved as Unicode, the <?xml encoding> tag is as follows:
<?xml version="1.0" encoding="unicode">
<VSSDatabase name> attribute
In the <VSSDatabase name> attribute, specify the path of the folder that contains the srcsafe.ini file for the copy of the Visual SourceSafe database that you are upgrading. For example:
<Source name="VSS">
...
<VSSDatabase name="c:\ourvss"></VSSDatabase>
...
</Source>
The path must not contain the string srcsafe.ini. For example, the following <VSSDatabase name> attribute is incorrect and will cause the VssUpgrade command to fail:
<Source name="VSS">
...
<VSSDatabase name="c:\ourvss\srcsafe.ini"></VSSDatabase>
...
</Source>
<UserMap name> attribute
The Analyze command gathers and compiles data about your Visual SourceSafe users and stores it in an XML file. Optionally, you can specify the path and name of the file where you want this data stored in the <UserMap name> attribute. If you do not specify this attribute, the Analyze command creates a file that is called UserMap.xml and puts it in the current directory.
<ProjectMap> section
In the <ProjectMap> section, specify the path of each Visual SourceSafe project that you want to upgrade in the Source attribute of a <Project> item.
To upgrade all the data in your Visual SourceSafe database, make the <ProjectMap> section match the following example:
<ProjectMap>
<Project Source="$/"></Project>
</ProjectMap>
Instead of upgrading your complete Visual SourceSafe database at the same time, you can upgrade selected projects at different times.
Tip
Use this option to avoid blocking your team during upgrade if you have lots of data to upgrade.
The paths in the Source attributes must not overlap. For example, the following <ProjectMap> section is not valid:
<ProjectMap>
<Project Source="$/ProjectA"></Project>
<Project Source="$/ProjectA/Controller"></Project>
</ProjectMap>
<Output file> attribute
In the <Settings> section, in the <Output file> attribute, you can specify the path and name of the file where you want the analysis report to be written. If you do not want to specify this option, you can omit the <Output> tag. In this case, the converter writes the report to a file that is named VSSAnalysisReport.xml and puts it in the current directory.
<SQL> element
You must specify a database for VssUpgrade to use to store temporary data by adding a <SQL> element to the <Source> section of your Analyze settings file. This element uses the following syntax: <SQL Server="SQL_Server_name"></SQL>.
For example, if you are running VssUpgrade on a computer that is named FABRIKAM-2, to use a local SQL Server Express instance on the same computer:
<Source name="VSS">
...
<SQL Server="fabrikam-2\sqlexpress"></SQL>
...
</Source>
To direct the converter to use SQL Server, for example a server that is named FabrikamSQLServer
<Source name="VSS">
...
<SQL Server="fabrikamsqlserver"></SQL>
...
</Source>
Run the Analyze command
From Windows Start, run Command Prompt as administrator.
In the Administrator: Command Prompt window, enter:
VssUpgrade Analyze settings.xml
Replace settings.xml with the path and name of the Analyze settings file that you created.
When you are prompted, enter the administrator password for your Visual SourceSafe database. If your database has no password, press Enter.
VssUpgrade displays the ongoing status as the Analyze command proceeds. When the process is completed, the system summarizes the results. For example:
Analyze complete.
Analyzed 859 files and 941 folders.
Warnings 0 and Errors 0
Pre-migration report file: C:\VSS\migrate\VSSAnalysisReport.xml
If there were any warnings or errors, you can find details about them in ConverterErrors.txt and VSSUpgrade.log.
The Analyze command generates:
A report that you can use to get details about possible problems and changes that the Migrate command may cause.
A user mapping file (Usermap.xml), which you can use to specify how user data will be converted during the upgrade process.
These files are explained in more detail below.
Review and resolve issues found by the Analyze command
The analysis report provides information about issues in your Visual SourceSafe database that may cause problems during the upgrade process. Try to resolve as many of these issues as possible to minimize problems with the upgrade process, as described in the next section.
Some Files are Checked Out
The report lists files that are currently checked out. The upgrade process does not preserve checkout information. Try to ensure that as many files as possible are checked in before upgrading.
Some Items have Data Integrity Issues
The report lists items whose data integrity has been compromised. The Visual SourceSafe ANALYZE utility may be able to fix these kinds of issues. Items that cannot be repaired will not be upgraded. For more information, see the following pages on the Microsoft Web site: ANALYZE Utility and How to Detect and Fix Database Corruption Errors in Visual SourceSafe.
Some Folders in Mapped Projects Contain History that is Not Included in the <ProjectMap> section
If a folder is moved from one project to another in a Visual SourceSafe database, the history of that folder is contained in both the original and current projects. To upgrade such a folder with all of its history, you must upgrade both the original and current projects.
For example, you are upgrading the Visual SourceSafe project Project2. This project contains the folder $/Project2/FeatureA, which was moved from Project1 at some point in its history.
If your <ProjectMap> section contains… |
For example… |
Then… |
|---|---|---|
Both projects. |
|
The folder is upgraded with its full history. |
The project that originally contained the folder but not the project that currently contains it. |
|
The folder is not upgraded. |
The project that currently contains the folder but not the project that originally contained it. |
|
The folder is upgraded with its history starting from when it was moved to the current project. The history that occurred before the folder was moved to the current project is not upgraded. |
For more information about the <ProjectMap> section of the settings file, see <ProjectMap> Section earlier in this topic.
Some label names are not supported by Team Foundation version control
The report lists label names that will change when they are upgraded because they contain characters that TFS version control does not support. See Naming restrictions in Team Foundation.
Upgrade your data
After you have run the Analyze command, you are almost ready to upgrade your data. Before you run the Migrate command, you must create a settings file. Optionally, you can specify how user names are upgraded.
Specify How User Names are Upgraded
You can control how user information is upgraded from Visual Source Safe to TFS version control. Specifically, you can specify what user name the Migrate command should associate with each changeset in the history of each item in TFS version control. You do this by editing the user mapping file that was created when you ran the Analyze command, as explained earlier in this topic.
The user mapping file is optional. If you omit the <UserMap name> attribute from your Analyze settings file, each changeset is built in the following manner:
The User field is set to the name of the account under which VssUpgrade is running.
The name of the user who performed the action in your Visual SourceSafe database is stored in the Comment field.
Example of a user mapping file
When you run the Analyze command, it compiles data about your Visual SourceSafe users and stores it in an XML file. This file lists every Visual SourceSafe user who has ever performed a version control operation in the Visual SourceSafe projects that you are upgrading.
The following example shows a user mapping file that was created by the Analyze command.
<?xml version="1.0" encoding="utf-8"?>
<UserMappings>
<UserMap From="Admin" To=""></UserMap>
<UserMap From="Guest" To=""></UserMap>
<UserMap From="Kim" To=""></UserMap>
<UserMap From="Satomi" To=""></UserMap>
<UserMap From="Mark" To=""></UserMap>
</UserMappings>
You can specify the To attribute of none, some, or all of the UserMap items in the user mapping file. For example, you could modify the previous example in the following manner:
<?xml version="1.0" encoding="utf-8"?>
<UserMappings>
<UserMap From="Admin" To="NORTHAMERICA\KenM"></UserMap>
<UserMap From="Guest" To="Test1"></UserMap>
<UserMap From="Kim" To="EUROPE\KimT"></UserMap>
<UserMap From="Satomi" To="ASIA\SatomiH"></UserMap>
<UserMap From="Mark" To=""></UserMap>
</UserMappings>
Notice that in the previous example, Guest is mapped to Test1, and no domain is specified. In these cases, VssUpgrade presumes that the account belongs to the default domain.
If you do not specify a <UserMap To> attribute, each changeset is built in the following manner:
The User field is set to the name of the account under which VssUpgrade ran.
The name of the user who performed the action in your Visual SourceSafe database is stored in the Comment field.
If you specify a <UserMap To> attribute and the value is a valid user on your Team Foundation Server, the User field is set to the name of that account. If the value is not a valid user on your Team Foundation Server, VssUpgrade will display an error and end the upgrade process.
Create a Migrate settings file
You use the Migrate settings file to specify what Visual SourceSafe data you want to upgrade and to control several aspects of how you want to upgrade it. The easiest way to create this file is to copy the file that you created in Create an Analyze settings file earlier in this topic. You then add more data to the file to make it usable by the Migrate command.
The following example shows a Migrate settings file.
<?xml version="1.0" encoding="utf-8"?>
<SourceControlConverter>
<ConverterSpecificSetting>
<Source name="VSS">
<VSSDatabase name="c:\ourvss"></VSSDatabase>
<UserMap name="c:\ourvss\migrate\Usermap.xml"></UserMap>
<SQL Server="SQLInstanceName"></SQL>
</Source>
<ProjectMap>
<Project Source="$/Core" Destination="$/CoreTeamProject"></Project>
<Project Source="$/ProjectA" Destination="$/ClientTeamProject/ProjectA"></Project>
<Project Source="$/ProjectB" Destination="$/ClientTeamProject/ProjectB"></Project>
</ProjectMap>
</ConverterSpecificSetting>
<Settings>
<TeamFoundationServer name="My_Server" port="8080" protocol="http" collection="tfs/DefaultCollection"></TeamFoundationServer>
<Output file="c:\ourvss\migrate\logs\ContosoVSSMigrate.xml"></Output>
</Settings>
</SourceControlConverter>
The following information can help you modify the Migrate settings file to specify how the Migrate command will upgrade your data.
<ProjectMap>
For each <Project> element in the <ProjectMap> section of your Migrate settings file, provide a Destination attribute to specify the path of the location on your Team Foundation Server where you want to upgrade the contents of the project in your Visual SourceSafe database (specified in the Source attribute).
For example, you want to upgrade the contents of ProjectA in your Visual SourceSafe database into ProjectA at the root of a team project that is called Client.
<ProjectMap>
<Project Source="$/ProjectA" Destination="$/ClientTeamProject/ProjectA"></Project>
</ProjectMap>
For the value in the Destination attribute to be valid, the following conditions must be true:
The team project in the Destination attribute (in the previous example, the team project is ClientTeamProject) must already be located in the team project collection before you start the upgrade process.
The path in the Destination attribute of a <Project> element must not overlap the path in the Destination attribute of any other <Project> elements. For example, the following <ProjectMap> section is not valid:
<ProjectMap> <Project Source="$/ProjectA" Destination="$/ClientTeamProjectA/"></Project> <Project Source="$/ProjectB" Destination="$/ClientTeamProjectA/ProjectB"></Project> </ProjectMap>
Note
If the folder in the Destination attribute contains any items, and if the path to any of your Visual Source Safe items overlaps with the version control path to any of these items, the upgrade process will fail.
<TeamFoundationServer> tag
In the <Settings> section, add a <TeamFoundationServer> tag, and specify the name, port, protocol, and path to the team project collection on your Team Foundation Server by using the following format:
<TeamFoundationServer name="ServerName" port="PortNumber" protocol="http" collection="path/collection name></TeamFoundationServer>
<Label migrate="false" /> tag
If your Visual SourceSafe database contains many labels that are applied to many files, the upgrade process may be prolonged. If your team does not need this data, you can configure VssUpgrade to ignore labels by adding the <Label migrate="false" /> tag to the <Settings> section.
<Output file> attribute
In the <Settings> section, in the <Output file> attribute, you can specify the path and file where you want the upgrade report written. If you do not include the attribute, the converter writes the report to a file that is named VSSMigrationReport.xml and puts it in the current directory.
Run the Migrate command
From Windows Start, run Command Prompt as administrator.
In the Administrator: Command Prompt window, enter:
VssUpgrade Migrate settings.xml
Replace settings.xml with the path and name of the Migrate settings file that you created.
The Migrate command displays each project that you are upgrading from your Visual SourceSafe database and each folder into which the data will be upgraded on your server for Team Foundation version control.
When you are prompted, enter the administrator password for your Visual SourceSafe database. If your database has no password, press Enter.
The system summarizes how it will run the upgrade process and asks you to confirm that you want to proceed. For example:
This will start migration with following inputs: SourceSafe Folders -> Team Foundation Server Folders $/ -> $/Sequence2 Full history migration of VSS Database: c:\vss Team Foundation Server: http://fabrikam-4:8080/tfs/DefaultCollection Migration Settings File: migrate_settings.xml Migration Report: C:\VSS\migrate\VSSMigrationReport.xml Depending on the VSS database size, migration may take few hours to complete. Please verify all inputs are correct and confirm. Start migration (Y/N)?Press Y to proceed.
VssUpgrade displays the ongoing status as the Migrate command proceeds. When the process is completed, the system summarizes the results. For example:
Verification of pinned versions: 0 file(s) added, 0 file(s) edited and 86 file(s) label updated
Verification of latest tip versions: No change was required (No fixes required. All latest tip versions were migrated successfully)
Started: Creating label "Pinned_Latest".
Finished: Creating label "Pinned_Latest".
Migration complete.
Migrated 6397 Actions
Warnings 7 and Errors 0
Post migration report file: C:\VSS\migrate\VSSMigrationReport.xml
If there were any warnings or errors, you can find details about them in ConverterErrors.txt and VSSUpgrade.log.
The Migrate command generates a report that you can use to get details about possible problems and changes that the Migrate command may have caused. See Take next steps after upgrading from Visual SourceSafe.
Resume the process by using incremental upgrade
If the upgrade process is interrupted for some reason, you can resume the process as an incremental upgrade from the point at which the process ended. An incremental upgrade can be useful if the upgrade process failed because of an error or network problems. During incremental upgrade, the converter will upgrade only the data that was not upgraded in previous sessions.
To start an incremental upgrade, follow the steps in Run the Migrate command. When the Migrate command asks whether you want to perform an incremental migration, press Y.
Limitations of an incremental upgrade
An incremental upgrade will not succeed unless you comply with the following restrictions:
In your Visual SourceSafe database, you must not have performed destroy, purge, archive, or restore activities.
You must not change the <ProjectMap> section of your Migrate settings file.
On your Team Foundation Server, you must not modify any folders (or any content in the folders) that are specified in the <ProjectMap> section of your Migrate settings file.
Next step
View and verify the results, and resolve issues as necessary