Share via

April 2011

Volume 26 Number 04

Team Foundation Server - Visual Studio TFS Team Project and Collection Guidance

By Willy-Peter Schaub, Mike Schimmel | April 2011

In the MSDN Magazine article, “Visual Studio TFS Branching and Merging Guidance” (, the Visual Studio ALM Rangers introduced a number of new branching scenarios and associated guidance to assist you in complex, real-world branching and merging environments, in order to improve the consistency and quality of solutions and the overall Application Lifecycle Management (ALM) process.

To recap, the Rangers are a group of experts who promote collaboration between the Visual Studio product groups, Microsoft Services and the Microsoft Most Valuable Professional (MVP) community by addressing missing functionality and removing adoption blockers.

In this article, the Rangers offer guidance for organizing and provisioning Team Foundation Server (TFS) Team Projects and Team Project Collections.

After reading this article, you should have a better understanding of:

  • Team Project Collections and their benefits
  • Considerations for choosing to combine one or more Team Projects into a single Team Project Collection, or to keep them in separate Team Project Collections
  • Considerations for organizing Team Projects and Team Project Collections to increase isolation or improve scalability
  • How to archive one or more inactive Team Projects

This article will help you understand how Team Project and Team Project Collection organization is influenced by issues such as:

  • Security and provisioning for TFS, Team Project Collections and Team Projects
  • Selecting a Process Template
  • Process Template customizations including customized work flows, Work Item Type customizations, custom reports, custom queries and customized process guidance
  • Team organization
  • Team Project organization including Areas and Iterations
  • Project management considerations including project milestones and schedules


Visual Studio TFS planning usually starts with the recommended infrastructure and the structuring of the Team Projects and Team Project Collections to ensure an effective and scalable ALM system for all stakeholders.

The Visual Studio 2010 Quick Reference Guidance ( and Visual Studio 2010 and TFS 2010 Virtual Machine (VM) Factory ( Rangers guidance projects provide concepts, guidance and quick reference posters to support capacity planning and help answer the question of whether infrastructure should be physical or virtual, or both.

Although you typically plan and define a Team Project Collection before a Team Project in a TFS 2010 environment, we’ll cover the Team Project first.

Visual Studio Team Projects

In TFS 2005 and TFS 2008, a single TFS server could host one or more Team Projects. Each Team Project is essentially a container for artifacts, including source code (organized into folders, branched folders and branches) and containing one or more Visual Studio solutions, Team Build configuration files, Team Load Test Agents, an optional SharePoint repository containing the pertinent documents for the project and security provisioning used by a team to track and perform a set of work as governed by a process template. The Team Project should not be confused with a Visual Studio .NET Project, which contains all of the build and configuration settings required to generate a Microsoft .NET Framework assembly; a Visual Studio .NET Solution, which contains one or more Visual Studio .NET projects and defines project dependencies, build process and order; or a project initiative, which is a scheduled initiative for building something from a set of requirements.

For more information on creating and managing Team Projects, you can refer to the “Creating and Managing Team Projects” MSDN Library page (

Let’s discuss considerations for organizing Project Initiatives into Team Projects. Team Projects often contain the largest unit of work associated with developing a single product or product line. For example, at Microsoft, Visual Studio and Office are two product lines each contained within its own separate Team Project (see Figure 1), because the development of these two product lines proceeds along completely different timelines with separate milestones and release schedules.

image: Visual Studio and Office Team Projects

Figure 1 Visual Studio and Office Team Projects

It’s important to take note of provisioning considerations and security isolation. One of the most time-consuming aspects of creating a new Team Project is the effort required to provision the project for use by one or more teams, primarily by defining the security users, groups and permissions that control access to a Team Project and its artifacts.  This provisioning effort needs to be balanced against the benefits of properly defining security at the right level of granularity so as to allow members of the team to be able to do what they need to do. At the same time, proper security provisioning protects a Team Project and its assets from inadvertent or intentional damage done by people who aren’t supposed to be performing certain tasks.

For product lines with different milestones and release schedules, such as Visual Studio and Office, it makes sense to organize each product line into a separate Team Project for security isolation. The development teams associated with each product line are likely to be completely separate and unlikely to require and be granted contribution or build permissions to both team environments.

For project initiatives with different methodologies—for example, where one team chooses to use the Microsoft Solutions Framework (MSF) for Agile Software Development version 5.0 and the second team chooses to use the MSF for CMMI Process Improvement version 5.0 Process Template—separate Team Projects are required because a given Team Project has one, and only one, Process Template associated with it.

For project initiatives that require unique definitions for Areas and Iterations, we suggest separate Team Projects, as a given Team Project defines a single Area and Iteration hierarchy. Alternatively, a single Team Project can use Areas to organize multiple feature teams (see Figure 2) that share the same Iterations (see Figure 3). Also see “Project of Projects with Team Foundation Server 2010,” by Martin Hinshelwood, at, for a discussion on a scenario using Areas instead of having many small Team Projects.

image: Team Project Using Areas to Organize Separate Feature Teams

Figure 2 Team Project Using Areas to Organize Separate Feature Teams

image: Team Project with Multiple Feature Teams Sharing the Iteration Hierarchy

Figure 3 Team Project with Multiple Feature Teams Sharing the Iteration Hierarchy

Version Control Check-out settings (such as exclusive Check-out, Check-in policies and Check-in notes) are defined for a Team Project, and these settings aren’t shared across Team Project boundaries. If separate project initiatives require different Source Control settings, they must be associated with separate Team Projects.

Process Template Customizations include customized or custom Work Flows, Work Item Types (WITs), Reports and Queries. You can customize a process template used to create new Team Projects or customize the specific Process Template used by a Team Project, whereby the latter is not shared across Team Projects.

Sharing of Team Project Artifacts is typically achieved by branching from one Team Project to another. In our previous article, we discussed various approaches for sharing common code, most of which involve branching.

As you can see, there are a number of considerations for deciding whether separate projects or project initiatives can share the same Team Project or must be associated with separate Team Projects. You should understand the various considerations and make Team Project organization decisions that are best for your organization.

Visual Studio Team Project Collections

Although Team Projects are somewhat independent of one another, in TFS 2005 and TFS 2008, certain maintenance activities such as consolidating multiple TFS servers into a single server were difficult. Further, separate business units within an organization could only achieve organizational isolation by implementing two or more TFS servers within the organization, increasing the cost of infrastructure, maintenance and overall complexity.

Visual Studio 2010 introduced Team Project Collections. Each TFS Server can have one or more Team Project Collections. In turn, a Team Project Collection contains one or more Team Projects. A Team Project Collection is the basic unit of recovery for TFS. From a backup and restore perspective, a Team Project Collection is similar to a SharePoint Site Collection.

The Visual Studio 2010 Quick Reference Guidance project ( provides a quick reference poster to assist you with the planning of the new Team Project Collection feature, as well as Team Projects. Team Project Collections provide a more scalable deployment for TFS servers. One Team Project Collection in TFS 2010 is the rough equivalent of one TFS Server in TFS 2005 or TFS 2008. For more information on creating and managing Team Project Collections, refer to\library\dd236915.

Considerations for isolating Team Projects into separate Team Project Collections include scalabil-ity, backup, recovery, security isolation and sharing of information among Team Projects.

Scalability of TFS servers is supported by the ability to load balance Team Project Collections across physical SQL Servers and SQL Server instances, taking advantage of scalability and load-balancing infrastructure that’s typically associated with database environments. If you have the ability to load balance across SQL Servers, you may benefit from splitting Team Projects across multiple Team Project Collections.

As noted earlier, the basic unit of recovery for TFS is the Team Project Collection. Team Projects can’t be individually backed up or restored. If you require granular backup and recovery capabilities (for example, if you don’t want to recover more than a single Team Project), it may benefit your organization to isolate Team Projects into separate Team Project Collections for the purpose of backup and recovery.

Security provisioning for Team Project Collections, if administered properly and with the correct degree of control and granularity, may be time consuming. As you add new Team Project Collections, you must consider the initial and ongoing effort to provision each of these collections. If the project teams for the Team Projects being managed on a TFS server have different security requirements, it may benefit you to isolate Team Projects into separate Team Project Collections for security purposes.

On the other hand, if the project teams for the Team Projects being managed on a TFS server don’t require security isolation, it may benefit your organization to have their Team Projects within the same Team Project Collection (see Figure 4).

image: Team Project Collection Sharing and Isolation Boundaries

Figure 4 Team Project Collection Sharing and Isolation Boundaries

While sharing of artifacts (such as source code files) can be done between Team Projects in the same Team Project Collection, they can’t be shared across collection boundaries (see Figure 4). If two Team Projects must share artifacts, they must be contained within the same Team Project Collection.

Discussions about the topics of using Team Project Collections for sharing and isolation of source code, and branching and merging, are not within the scope of this article. We recommend you refer to for associated discussions and information that will be included in forthcoming guidance.

Team Project Archiving Strategies

Periodic maintenance is essential, as a TFS environment can never be installed on unlimited physical resources. Administrators need to plan for periodic maintenance to archive completed project data and relieve pressure on the server before it becomes a performance issue for development teams.

The Rangers Upgrade Guidance ( defines a number of possible strategies as part of the upgrade guidance, similar to the procedure that the Microsoft Consulting Services has developed (see Figure 5):

image: Possible Archive Strategy

Figure 5 Possible Archive Strategy

  1. Start by making a copy of the Team Project Collection.
  2. Delete active Team Projects from the newly cloned archival Team Project Collection (using the TFSDeleteProject command-line utility).
  3. Delete the archived projects from the original (active) Team Project Collection.
  4. The new Team Project Collection can then be stored off to external media, such as tape or flash media, and then removed from the hardware. If an audit is made of the system, the archive media can easily be restored for that purpose.
  5. Detach the new Team Project Collection in order to easily get it back later.

In concept, this seems like a trivial strategy, but it really requires a policy for determining which Team Projects can be archived and which can’t. Take special note that source code branches are removed from the system when a TFSDeleteProject action is performed, and this isn’t an undoable event.

Following are suggestions for an archiving policy:

  • Establish a project close-out policy for development teams to cleanse project data and store it. Source code is not the only material that needs to be saved. Project requirements are interesting, but they’re probably not in a format that can be reused or from which enhancements can be made. Functional specifications need to be blended with previous ones to reflect the state of the product as it stands in production at the completion of the project. The requirements for that project can then be archived with no worry of losing data. Work Items can’t be merged from one Team Project to another Team Project like source code can, so decisions about how to store completed work items after a project is completed will be necessary.
  • Send a standard request to all teams notifying them of a pending archival action prior to the event, listing all Team Projects targeted for the archiving.
  • Establish a milestone folder in each Team Project that serves as a container for a completed project initiative’s final project data, including requirements listings, final project reports and any documentation that’s stored under normal methodology policy for project closeout.

Essentially, all project data—not only source code—needs to be preserved in order for an archive to be successful.

Splitting Team Project Collections is needed to react to a possible separation of a business unit into two or more managed entities. In this scenario, a similar approach to that used for archiving Team Projects is employed, although none of the Team Projects will be archived. The second Team Project Collection will have to be treated like the original in that it will now require periodic maintenance separate from the original Team Project Collection.

Moving Team Projects between Team Project Collections isn’t easy, and once a collection is split, it can’t simply be remerged, as only new Team Projects can be added to a collection. In order to merge Team Project Collections, custom code is required using the TFS API to copy project data from one collection to another.

 Although not recommended, TFS Integration Tools can be used to merge Team Projects into Team Project Collections—see the TFS Integration Tools documentation (

In a future article, we’ll investigate how the Rangers are overcoming and managing the challenges of distributed Agile team management using the Visual Studio ALM tooling.

Willy-Peter Schaub is a senior program manager with the Visual Studio ALM Rangers at the Microsoft Canada Development Center. Since the mid-’80s, he’s been striving for simplicity and maintainability in software engineering. His blog is at and you can follow him on Twitter at

Mike Schimmel is an ALM solution architect with the Microsoft Consulting Services U.S. Architects and a core member of the Visual Studio ALM Rangers. He has nearly 25 years of experience studying and practicing ALM, from research and consulting to competitive product sales and service delivery.

Thanks to the following technical experts for reviewing this article: Bill Essary, Bill Heys,Martin Hinshelwood,Bijan Javidi and Mario Rodriguez