Explained: Structuring Your Solutions and Projects in Source Control with Team Foundation Server

- J.D. Meier, Jason Taylor, Alex Mackman, Prashant Bansode

Applies To

  • Team Foundation Server
  • Visual Studio Team System

Summary

This article explains how you can structure Visual Studio solutions and projects in Team Foundation Server Source Control as well as on your local computer’s file-system. The client and server-side folder structures and conventions discussed in this article are not the only approach you can adopt, but they represent an approach proven to work effectively for many team development scenarios working on a variety of different application types.

Contents

  • Overview
  • Server-Side Structure
  • Client-Side Structure
  • Branched Folders
  • Workspaces Explained
  • What Files Should be Source Controlled
  • What Files Should Not be Source Controlled
  • Additional Resources

Overview

Many of the default folder conventions used by Visual Studio 2005 when you create new solutions and projects are not optimized for team development and for use with Team Foundation Server Source Control. Rather than accepting the defaults when you create new Visual Studio projects and solutions, you should give careful consideration to your local and server-based folder structure when creating new Visual Studio solutions and projects.

This article starts by explaining how you should structure solutions and projects on your development computer (the client-side) and how you should structure your folders within Team Foundation Source Control (the server-side). It provides some example folder structures for a variety of application types including Window Forms, smart client and Web applications. The article then explains how workspaces are used to manage the mappings between client and server folder structures.

Server-Side Structure

Most team projects contain multiple Visual Studio projects. Larger projects also often have multiple Visual Studio solution (.sln) files to group related sets of projects together. In order to support branching for isolated development paths, which tends to be required in all but the smallest development projects, a root level folder called Main (on client and server) is used to group together your Visual Studio projects. A recommended folder structure within Team Foundation Server Source Control is shown here:

$MyTeamProject1
     /Main 			            -> Can contain solution (.sln) files	
           /Source
		/MyApp1			    -> Contains MyApp1.sln file 
		     /Source		    -> Contain folder for all source
			   /ClassLibrary1   -> Contains ClassLibrary1.csproj 
			   /MyApp1Web 	    -> Contains Default.aspx
                     /UnitTests		       -> Container folder for unit tests
			   /ClassLibrary1Tests -> Contains test project and code
			   /MyApp1WebTests     -> Contains test project and code
		/SharedBinaries		       -> Shared binaries e.g. libraries
		/SharedSource		       -> Shared source code	 
     /Build				       -> Contains build output (binaries)            
     /Docs				       -> Contains product docs etc
     /Scripts				       -> Contains build scripts
     /Tests				       -> Container for tests
	  /FunctionalTests
	  /PerformanceTests
	  /SecurityTests


Main is a container folder for the source files and other related artifacts such as build output, design documentation, test cases and so on. An application folder (such as MyApp1 in the preceding example) contains the Visual Studio solution (.sln) file used to group together a related set of Visual Studio projects. Each project file (.vsproj or .vbproj) is contained in its individual project folder, located beneath /Main/Source/MyApp1/Source. Unit tests that accompany each source project are located beneath the UnitTests folder. You can also place additional Visual Studio solution (.sln) files into the Main folder to allow you to work with multiple different groupings of projects.

The folders Build, Docs, Scripts and Tests are used to hold additional artifacts associated with the team project including the binary output of builds, documentation such as use cases, design documents and diagrams, build scripts and tests.

Storing Unit Tests

In the proceeding example, unit tests are maintained beneath a folder called UnitTests at the same level as Source.
 …
  /MyApp1				-> Contains MyApp1.sln file 
	/Source			        -> Contain folder for all source
		/ClassLibrary1		-> Contains ClassLibrary1.csproj 
		/MyApp1Web 	        -> Contains Default.aspx
	/UnitTests			-> Container folder for unit tests
		/ClassLibrary1Tests	-> Contains test project and code
		/MyApp1WebTests 	-> Contains test project and code
 …

This scenario promotes tests to first class citizens, which is a benefit. However, it does so at the expense of project level branching compatibility. An alternate structure is shown here:

 …
  /MyApp1
	/Source
		/ClassLibrary1
		/ClassLibrary1Tests
		/MyApp1Web
		/MyApp1WebTests

The following pros and cons apply to each approach:

UnitTests as a Peer to the Source folder
  • Pro: one place to find all unit tests
  • Pro: shipping code is separated from non-shipping code
  • Pro: build can easily run all unit tests across all projects
  • Con: harder for developer to run unit tests just for their project
  • Con: branching source won't include unit tests, loosely bound to source

UnitTests in Each Project
  • Pro: Developer can easily run unit tests on a single project
  • Pro: Branching includes unit tests so they can stay tightly bound to the source in each branch
  • Con: You mix shipping with non-shipping code in the source folder
  • Con: Maybe harder to run all unit tests at once at build time across all projects

Storing Documents

The Docs folder is for product related documentation. To help determine what documents to store in TFS source control and what to store in a document library on your SharePoint team site, consider the following:
  • Use SharePoint for internal team documentation such as use cases, scenario and requirements documentation, and design documentation.
  • Use TFS source control for product-related documentation that you ship to your customers. This could include installation and deployment guides, operations guides, and help files.
  • Most documents are binary files, so consider using exclusive locks to avoid manual merges. This way, you get notification when a file is in use and you help avoid having to perform manual merges.

Be careful when using SharePoint if you need to strictly manage document versions. It is easier to overwrite changes compared to TFS source control because, by default, SharePoint enables the "overwrite existing file" option selected when you upload files.

Client-Side Structure

You should use the same folder structure on your development computer. To ensure a consistent approach for your team development and to keep team projects well organized on your development computer, you should keep your entire development source from all of the team projects you are working on grouped together beneath a single root folder such as C:\DevProjects. You should then create one sub folder for each team project as shown here:

C:\DevProjects			 Root container folder for all team projects
	\MyTeamProject1		 Container folder for TeamProject1
	\MyTeamProject2		 Container folder for TeamProject2


Beneath each team project folder, use a copy of the folder structure used on the server within source control to house individual applications.

\MyTeamProject1				-> Container folder for TeamProject1
    \Main				-> Contains .sln files that span projects
         \Source
 	 	\MyApp 1		-> Contains MyApp1.sln
  		    \Source			
	 		\ClassLibrary1	-> Contains ClassLibrary1.csproj 
			\MyApp1Web	-> Contains Default.aspx
		    \UnitTests		-> Contains unit test projects and source
			\ClassLibrary1Tests
			\MyWinApp1tests
		\SharedBinaries		-> Shared binaries e.g. libraries
		\SharedSource		-> Shared source code	 
	\Build				-> Container folder for build output
	\Docs				-> Contains project documentation
	\Scripts		       -> Contains build scripts, database scripts
	\Tests				-> Container for tests
		\FunctionalTests
		\PerformanceTests
		\SecurityTests

Branched Folders

If you need to create branches for isolation, create additional folders as siblings of /Main. You can also place additional Visual Studio solution (.sln) files into Main to allow you to work with multiple different groupings of projects. For example, you might need to create branches from your Main source folders to support ongoing maintenance of product releases and to support parallel streams of development for example where you have different teams working on different product features.

Note: Do not branch unless you need to. You can label a release and branch at a later time if you need to.

In the following example structure in addition to the Main root folder which acts as a container folder for your main source tree, a Development folder (branched from Main) is used to provide isolation for features or for teams and a Maintenance folder (again branched from Main) provides isolation for released builds that you need to support for example by applying hot fixes. This structure is shown here:

$MyTeamProject1
  /Development
	/FeatureBranch1
		/Source
			/MpApp
				…
	/FeatureBranch2
		/Source
			/MpApp
/Main
	/Source

/Production
	/Source
			…

/Maintenance
	/Release1
		/Source
			/MyApp
				…
	/Release2
		/Source
			/MpApp
				…


For more information about branching scenarios and related folder structures, see Explained: Branching in Team Foundation Server.

Workspaces Explained

A Team Foundation Server workspace is a client-side copy of the files and folders in Team Foundation Server Source Control. A workspace maps Source Control folders to local file system directories. When you make changes to files within the workspace on your local computer, the local changes, referred to as pending changes are isolated within your workspace until you check them into the server as an atomic unit. The collective set of changes, checked in as a batch is referred to as a changeset.

A single workspace can contain references to multiple team projects. You can also use multiple workspaces to isolate files or versions for your use only. Workspaces are per machine, per user account. Therefore, you can have different workspace definitions for each computer you use. Also, as a single user, you can have multiple workspaces on a single computer.

Creating a New Workspace Mapping

Because mappings are recursive, when you create a new workspace mapping and perform a Get Latest Version operation, your entire local folder structure is created automatically and will match the structure used in source control. If you are creating a new workspace mapping solution in Source Control, to adhere to the recommended structure discussed previously:
  • The project owner must ensure that the correct folder structure is used locally prior to adding the solution to source control for the first time.
  • When establishing a workspace mapping for a team project for the first time and performing a Get Latest Operation, be sure to map the root team project folder into C:\DevProjects\TeamProject1.

Where Are Workspace Mappings Stored?

Workspace information is maintained on the client and on the server. On the client, workspace information is held in VersionControl.config which is located in the following folder:
\Documents and Settings\user\Local Settings\Application Data\Microsoft\Team Foundation\1.0\Cache.

The VersionControl.config file maps the name of the workspace to a local directory on your computer. It does not hold the mapping between individual source control folders and your local directories. That information is held on the server in several tables (including tblWorkspace and tblworkingfolder) in the TfsVersionControl database.

What Files Should Be Source Controlled?

The following list identifies the key file types that you should add to source control. These are the file types that are added when you click Add Solution to Source Control.
  • Solution files (.sln)*. Solution files maintain a list of constituent projects, dependencies information, build configuration details, and source control provider details.
  • Project files (.csproj or .vbproj). Project files include assembly build settings, referenced assemblies (by name and path), and a file inventory.
  • Visual Studio Source Control Project Metadata (.vspscc)*. These files maintain project bindings, exclusion lists, source control provider names and other source control metadata.
  • Application configuration files (.config)*. XML configuration files contain project and application specific details used to control your applications ’s run time behavior. Web applications use files called Web.config. Non-Web applications use files called App.config.

Note: At run time, the Visual Studio build system copies App.config to your project’s Bin folder and renames it as Yourappname.exe.config. For non-Web applications, a configuration file is not automatically added to a new project. If you require one, add it manually. Make sure you call it App.config and locate it within the project folder.
  • Source files (.aspx, .asmx, .cs, .vb, …). Source code files, depending on application type and language.
  • Binary dependencies (.dll)*. If your project relies on binary dependencies such as third party DLLs, you should also add these to your project within source control. For more information about managing dependencies, see “Explained: Managing Source Control Dependencies in Visual Studio Team System.”

What Files Should Not Be Source Controlled?

The following files are not added to source control because they are developer specific:
  • Solution user option files (.suo)*. These contain personalized customizations made to the Visual Studio IDE by an individual developer.
  • Project user option files (.csproj.user or .vbproj.user). These files contain developer specific project options and an optional reference path that is used by the Visual Studio to locate referenced assemblies.
  • WebInfo files (.csproj.webinfo or .vbproj.webinfo). This file keeps track of a project's virtual root location. This is not added to source control to allow individual developers to specify different virtual roots for their own working copy of the project. While this capability exists, you and all team members are recommended to use a consistent (local) virtual root location when you develop Web applications.
  • Build outputs that include assembly dynamic-link libraries (DLLs), Interop assembly DLLs and executable files (EXEs). Note that you are advised to add assemblies that are not built as part of your system build process (such as third-party controls and libraries) to Source Control within the projects that reference them.

Related Items

For step-by-step guidance for structuring Visual Studio solutions and projects with Team Foundation Server, see:

Additional Resources

Last edited Apr 4, 2007 at 10:13 PM by jtaylorsi, version 13

Comments

ritchiep Mar 26, 2007 at 11:34 PM 
How about PDF format as well? The CodePlex stylesheet doesn't print very well.