Migrate from Team Foundation Server to Visual Studio Team Services

Last Update: 11/29/2016

If your organization is currently using on-premises Team Foundation Server (TFS), consider moving into Visual Studio Team Services (Team Services). The most common reasons other organizations give for making this move are:

  • Simplified server management.
  • Immediate access to the latest and greatest features.
  • Improved connectivity with remote sites.
  • A transition from capital expenditures (servers and the like) to operational expenditures (subscriptions).

This whitepaper will help you decide whether moving to Team Services makes sense for your organization by providing information about these important areas:

  • Fundamental differences between TFS and Team Services.
  • Differences in specific feature areas between TFS and Team Services.
  • Migration of data from TFS into Team Services.

For each area, we'll discuss both the curent state of the world and the expected impacts from short and medium-term plans. Check back here for updates, because this information may change frequently.

Fundamental differences between TFS and Team Services

When you plan a move, there are a few fundamental differences between TFS and Team Services that are important for you to understand.

Scoping and scaling data

TFS has three options for scoping and scaling data - deployments, team project collections, and team projects. In the simplest case, deployments are just servers. Deployments can also be more complicated, however, including everything from a two-server deployment where SQL is split out on a separate machine to high availability farms comprising lots of servers. Team project collections serve as containers for security and administration in addition to serving as physical database boundaries. They are also used to group related team projects. Finally, team projects are used to encapsulate the assets of individual software projects, including source code, work items, and so on. Learn more about these concepts at Manage team project collections.

Team Services is slightly different. It currently only has two options for scoping and scaling data - accounts and team projects. Accounts in Team Services get their own URLs (for example, https://contoso.visualstudio.com) and always contain exactly one team project collection. Accounts can contain multiple team projects, like TFS team project collections.

We are planning a third option for scoping and scaling data in Team Services - a new entity called an Organization. Rather than adding support for multiple team project collections within an account, multiple accounts could be grouped within an organization. Additionally, we will merge accounts and their single team project collections into a single entity. The organization will be similar to the TFS deployment, and the account will be similar to the TFS collection.

To be ready to use the organization entity, we recommend that you create accounts in Team Services whenever you would have created collections in TFS. In the short term, having your work split across multiple accounts can cause some problems, but we plan to address these when the organization entity is introduced. In particular:

  • You purchase Team Services users per account, meaning that paid users only have access to the Team Services account in which the payment is made. If you have users who need access to multiple accounts, Visual Studio subscriptions can be an attractive option, since subscribers can be added to any number of Team Services accounts at no charge. We are also considering other ways we might make access to multiple accounts grouped into an organization available.

  • You currently have to administer accounts one at a time, which can be cumbersome when you have many accounts. We're working to support organization-wide policies.


With TFS, you typically connect to an intranet server (for example, https://tfs.corp.contoso.com:8080/tfs). You authenticate with Windows Authentication and your Active Directory (AD) domain credentials. Usually this process is transparent, and you'll never see any kind of sign-in experience.

With Team Services, you connect over the public internet (for example, https://contoso.visualstudio.com). You'll either authenticate with Microsoft Account credentials or with Azure Active Directory (Azure AD) account credentials, depending on your Team Services account setup. You can also set up Azure AD to require features like multi-factor-authentication, IP address restrictions, and so on.

We recommend that organizations configure their Team Services accounts to use Azure AD rather than Microsoft Accounts. This provides a better experience in many scenarios and more options for enhanced security.

Users and groups

In TFS, you provide users access to deployments by adding Active Directory (AD) groups to various TFS groups (for example the Project Contributors group for an individual team project). The AD group memberships are kept in sync. As users are added and removed in AD they also gain and lose access to TFS.

In Team Services, you can use a similar mechanism to provide access to groups of users by adding Azure AD groups to TFS groups. If you use Microsoft Accounts instead of Azure AD, you will have to add users one at a time.

Managing user access

In TFS and Team Services, you can give free access to work item features to an unlimited number of Stakeholders. Also, unlimited Visual Studio subscribers can have access to all Basic features at no additional charge. You only need to pay for other users who need access.

In TFS, all use is on the honor system. To set access levels for users based on their licenses, use the Access Levels administration page. For example, assign unlicensed users Stakeholder access only. Users with a TFS Client Access License (CAL) can have Basic access. Visual Studio subscribers can have either Basic or Advanced access, based on their subscriptions. Note that TFS does not attempt to verify these licenses or enforce compliance.

In Team Services, you must assign an access level to each user in your account's Users hub. Team Services validates Visual Studio subscribers as they sign in. You can assign Basic access for free to five users without Visual Studio subscriptions. To give Basic access to more users, you'll need to set up billing for your account and pay for more users. Otherwise, all other users get Stakeholder access.

If you use Azure AD groups to provide access to groups of users, Team Services will assign appropriate access levels to them automatically when they sign in for the first time. For Team Services accounts configured to use Microsoft Accounts for sign-in, you will have to assign access levels to each user explicitly.

Security and data protection

Many organizations want to know more about data protection when they consider moving to the cloud. Microsoft is committed to ensuring that Team Services projects stay safe and secure. We have technical features and business processes in place to deliver on that commitment. You can also take steps to secure your data. Learn more in our Data Protection Overview whitepaper.

Feature differences between TFS and Team Services

Even though Team Services is a hosted version of TFS, there are some differences between the features available in the two products. Some TFS features are not supported in Team Services at all - for example, Team Services does not support integration with SharePoint or Project Server. Other features differ between Team Services and TFS.

Process customization

You customize your process in TFS by modifying process templates or making changes to existing team projects using witadmin.exe. These options are quite powerful, but also cause a number of problems. Chief among these is that processes for existing team projects do not update automatically when TFS is upgraded.

For example, TFS 2013 introduced several new features which depended on new work item types and other process template changes. When you upgrade from TFS 2012 to TFS 2013, each team project collection gets new versions of each of the "in the box" process templates which include these changes. However, these changes are not automatically incorporated in existing team projects. Instead, after you finish upgrading you have to include them in each team project by using the Configure Features wizard or a more manual process.

To avoid these issues in Team Services, custom process templates and witadmin.exe have always been disabled. This has enabled us to automatically update all team projects with each Team Services upgrade. Meanwhile, the product team has been working hard to make customizing processes possible in ways that we can support easily and continuously. These first of these changes was recently introduced, and more changes are on the way.

With these new Team Services process customization capabilities, you can make customizations directly within the Team Services Web UI. If you want to customize your processes programmatically, you can also make customizations through REST endpoints. When you customize team projects in this way, those projects will continue to update automatically when we release new versions of their base processes with Team Services updgrades. Learn more:

Over time we will support more and more types of process customizations with this new approach. If you need process customization features which are not yet available and cannot wait for them, a second option for process customization in Team Services is available in private preview by request only.

With this option, you import customized process templates. This option is quite similar to using custom process templates in TFS, except that:

  • Restrictions exist in the customizations that can be imported into Team Services.

  • Process templates are associated with all team projects created from them, and changes made to the process are reflected in each team project.

Team projects in accounts which participate in this process customization private preview will not update automatically with Team Services upgrades.


Both TFS and Team Services have a variety of tools to give you insight into the progress as well as the quality of your software projects. These include:

For more information, see MSDN.

Migrating data from TFS into Team Services

When you decide to make the move from TFS into Team Services, you might start fresh with an empty account. Often, however, you will have existing code, work items, and other assets that you want to move. There are many approaches to doing this which vary in both the fidelity of the data transfer and the complexity of the process.

Option 1: Copy the most important assets manually

By far the easiest option for moving data into Team Services is to manually copy your most important assets and start relatively fresh. This can be difficult when you are in the middle of a large project, but you can make it easier if you do some advance planning and schedule your move when it makes sense for your team.

For example, when the Visual Studio Cloud Services team chose to move from TFS to Team Services, we also decided to move from Team Foundation Version Control (TF VC) to Git. This required a fair bit of planning, but when we actually performed our migration, we created a new Git repo using the "tip" version of our TF VC sources, and left our history behind in TFS. We also moved our active work items, and left behind all our old bugs, completed user stories and tasks, and so on.

Here's the general process:

  1. Identify the most important assets that you need to migrate - typically source code, work items, or both. Other assets in TFS – build definitions, test plans, and so forth – are harder to manually migrate.
  2. Identify a good time to make the transition.
  3. Prepare your target Team Services accounts. Create the accounts and team projects that you need, provision users, and so on.
  4. Migrate your data.
  5. Consider making the source TFS deployments read-only.

Option 2: High fidelity database migration.

The TFS/Team Services product team recently released a preview of a high fidelity TFS Database Import Service. More information on this service can be found at High Fidelity Migration. A downloadable migration guide is available at https://aka.ms/TFSImportData.

Migration Guide

Because the TFS Database Import Service operates at a database level, it can provide a very high fidelity migration. If you want to move your existing TFS data into Visual Studio Team Services, we strongly recommend using this option.

Option 3: Using public API-based tools for higher fidelity migration

If for some reason you cannot use the TFS Database Import Service but still want a higher fidelity migration than Option 1, you can choose from a variety of tools that use public APIs to move data. Generally these tools can provide a higher fidelity migration than a manual copy of "tip" data, but they are still relatively low fidelity. For example:

  • None of them will preserve the dates of TF VC changesets.
  • Many of them will not preserve the changed dates of work item revisions.
  • None of them will migrate all TFS artifacts.

In general, we only recommend this approach if the extra fidelity beyond a manual copy is critical. If you decide to take this approach, you might consider hiring a consultant who has experience with one or more of the tools. You should definitely consider doing a test migration before doing your final migration.

Many organizations need a very high fidelity migration for only a subset of their work. New work could potentially start directly in Team Services. Other work, with less stringent fidelity requirements, could be migrated using one of the other approaches. You will have to weigh the pros and cons of the various approaches against your motivations for moving into Team Services and decide for yourself what is the right strategy.

Migration Scopes

If you recall from the Scoping and scaling data section, the long term direction is for accounts to be groupable within organizations, with accounts serving as the Team Services equivalent of TFS project collections and organizations serving as the Team Services equivalent of TFS deployments. This is why the TFS Database Import Service only supports importing single TFS collections as single Team Services accounts. If you need to re-organize your TFS projects by splitting or merging project collections, migrating individual team projects, and so forth, you will need to use one of the other options – manual copy or public API based migrations.

(c) 2016 Microsoft Corporation. All rights reserved. This document is provided "as-is." Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.