If you’re still using TFS, there are some benefits and reasons why you may need to migrate to Azure DevOps (formerly VSTS), which is a cloud version of TFS with the most recent features. One of the benefits you may consider is global availability, easy access for the external users, the other benefits are the access to the most recent features and potential savings on the infrastructure and servicing (no upgrades, no servers, maintained security that relies on yours AAD instance).
In order to begin the migration, you need to complete the following pre-requisites (checklist):
- Make sure you have upgraded your TFS instance to the latest version (the current one is TFS 2018 Update 2). TFS 2018 does not allow you to have a single-step upgrade from every version of TFS in the past so your upgrade path may include a few interim steps along the way
- Check if the database collation eitherSQL_Latin1_General_CP1_CI_AS or Latin1_General_CI_AS
- Your users are in sync with AAD (Azure Active Directory)
- Your licenses are assigned to an Azure account you supposed to be using for migration
- ou have migration keys. You can generate two (one for a dry run/test run, the other to production). The keys can be generated here
- TFS Database size should not exceed 150Gb (otherwise you may need to consider some other database archiving options). To be discussed later
- Your TFS collection is validated and fixed (if necessary)
NOTE: Normally validation errors are related to the TFS upgrade and outdated process templates. Migration guide can be downloaded from Microsoft website here (this is a very helpful artifact that helps a lot during migration).
Most of the errors/warnings are easy to fix. Make sure you have none during validation procedure. First and foremost, you need to download a 'TFSMigrator' (command-line tool that will help you to verify TFS Db and schedule the actual migration).
Validation
To validate TFS database and prepare it for the migration, using CMD, go to TFSMigrator directory (assuming you have already downloaded and unzipped it), and execute the following command:
TfsMigrator validate /collection:http://tfs.<domain>/tfs/defaultcollection /connectionString:"Data Source=<TFSDbServer>; Initial Catalog=Tfs_Configuration; Integrated Security=True"
NOTE: You only need a /connectionString parameter if you execute this command remotely (e.g. not from TFS Server).
Error fixing
Once you executed the CMD statement mentioned above (to validate your collection), you may need to analyze the log generated to identify the errors and warnings (in case you have any). If you unzipped TFS Migrator to C:\ drive (like me), go to the directory (TFS_Migrator in my case) -> Logs -> DefaultCollection -> the folder you need would be named with a date-time stamp. Inside this folder, you'll see 'TfsMigrator.log'. This file has a lot of detailed information pertaining to the collection in the very beginning and starting from line 200 (approx.) you can see it analyzes all the project that belongs to your default collection one by one. The projects with no validation errors would be marked like this: "INFO: Successfully validated project <project name>". If you see 'Error' or 'Warning', the projects like that would require some attention and error/warning resolution before you can move any forward:
As it was already mentioned – the majority of errors are easy to fix and belong to outdated projects templates or the usage of reserved fields. To rename the field (that is applicable to all the projects), you should use a 'witadmin' tool, that can be found in VS directory: C:\Program Files (x86)\Microsoft Visual Studio <version>\Common7\IDE
Sample:
witadmin changefield /collection:http://<tfs_instance_name>:8080/tfs/defaultcollection /n:<source_field_name> /name:"<target_field_name>"
A good troubleshooting guide for all the error types related to migration/validation process can be found here.
Errors related to Process templates are more complicated. You may need some additional tooling that can be downloaded from GitHub (which is 'Process Customization Scripts'). Use the PS script to resolve Template validation errors:
.\ConformProject.ps1 "http://<tfs_instance_name>:8080/tfs/defaultcollection" "<project_name>" "C:\Projects_Source\process-customization-scripts\Import\Scrum" -Validate
NOTE: Specify process templates (Scrum in this case) that will be used further in this project. There are three of them available: Agile, Scrum and CMMI. Remove '-Validate' flag to commit the changes, otherwise, it is just a simulation run.
NOTE: You can copy the scripts along with subfolders to TFS Migrator directory for the convenience matters.
Prepare
Running 'Prepare' command means you have successfully fixed all the errors (if you encountered any) and is ready to move forward to one of the last steps in this process. With 'Prepare' command you're generating the import files set that will be used for the actual import execution ('import.json' and 'IdentityMap.csv'). The command you need to execute looks like the following:
TfsMigrator prepare /collection:http://<prod_tfs_instance>.com/tfs/defaultcollection /connectionString:"Data Source=<tfs_database_name>; Initial Catalog=Tfs_Configuration; Integrated Security=True" /tenantdomainname:<domain_name>.com /accountregion:CUS
The list of available regions can be found here.
Assuming you already have AAD (Azure Active Directory) and Azure DevOps set (otherwise there is no point in migration :)) you can move forward to the next step, related to TFS database export and Azure Storage account setup.
Azure part
Generate DACPAC file (database export):
SqlPackage.exe /sourceconnectionstring:"Data Source=<server name>; Initial Catalog=Tfs_DefaultCollection;Integrated Security=True" /targetFile:C:\temp\Tfs_temp.dacpac /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory
Dry-run
TfsMigrator import /importFile:C:\TFS_Migrator\Logs\DefaultCollection\20170929_143543\import.json
After this step, the test copy of your import will be available on https://<tenant name>-dryrun.visualstudio.com
If everything looks good, the project and the data are in place, you’re good to go with the actual import.
References
TFS Team Project Manager: https://github.com/jelledruyts/TfsTeamProjectManager (a tool that is used to access a TFS collection if you need any sort of fixes or template updates).