.gif)
Team Development with Visual Studio Team Foundation Server
J.D. Meier, Jason Taylor, Prashant Bansode, Alex Mackman, and Kevin Jones
Microsoft Corporation
September 2007
Applies To
- Microsoft® Visual Studio® 2005 Team Foundation Server
(TFS)
- Microsoft Visual Studio Team System
Objectives
- Structure projects for effective team development in Microsoft®
Visual Studio® Team Foundation Server (TFS) source control.
- Keep server-side and client-side folder structures synchronized.
- Choose a strategy for unit test structure.
- Create a folder structure that supports various branching
scenarios.
- Learn what a workspace is and how it maps local files to
source control.
- Understand what files are added to source control.
Overview
Many of the default folder conventions used by Visual Studio
when creating new solutions and projects are not optimized for team development
and for use with TFS 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.
This chapter 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 TFS source control (the server-side).
It provides example folder structures for a variety of application types
including Microsoft Windows® Forms, smart clients, and Web applications. The chapter
then explains how workspaces are used to manage the mappings between client and
server folder structures.
How to Use This Chapter
Use this chapter to learn about sample folder structures
suitable for team development projects of various sizes and complexity. To gain
the greatest benefits from this chapter, you should:
- Use the server-side structure suggestions. Use
the suggested server-side folder structures to organize your project
source code within TFS source control.
- Use the client-side structure suggestions. Use
the suggested client-side folder structures to organize your project
source code in your local development workspace.
- Read the companion How To articles. These articles provide
a step-by-step walkthroughs of some of the processes discussed in this
chapter:
Server-Side Structure
Most team projects contain one or more Visual Studio
solutions, each of which contains one or more Visual Studio projects. When you
require branching to support isolated development paths, you use a root level
folder named Main (on both client and server) to group together your
Visual Studio projects. The following is a sample folder structure within TFS
source control:
$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
/Docs à Contains product documentation
/Tests à Container for tests
/FunctionalTests
/PerformanceTests
/SecurityTests
/TeamBuildTypes à Created automatically by Team Build.
/BuildType1
/BuildType2
Main is a container folder for the source files and
other related artifacts such as build output, design documentation, and test
cases. 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 (.vcproj or .vbproj)
is contained in a dedicated project folder, located beneath
/Main/Source/MyApp1/Source. Unit tests that accompany each source project are
located beneath the UnitTests folder. You can place additional Visual
Studio solution (.sln) files in the Main folder to allow you to work
with multiple different groupings of projects.
The Docs and Test folders are used to hold
additional artifacts associated with the team project including product documentation
and automated tests.
The TeamBuildTypes folder is automatically created
for you when you generate your first Team Build. If you want to manually check
in a team build type you can create this folder by hand, add your Team Build
files, and TFS recognizes this folder for you automatically.
For more information about project groupings and solution
structure, see “Chapter 3 - Structuring Projects and Solutions in Source
Control.”
Storing Unit Tests
You can store unit tests beneath a folder named UnitTests
at the same level as Source as shown here.
…
/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 treats unit tests as first-class citizens.
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: You can find unit tests in one place.
- Pro: You separate shipping code from non-shipping code.
- Pro: Your build process can easily run all unit tests
across all projects.
- Con: It is harder for developers to run unit tests for
their project only.
- Con: When you branch source, it will not include unit
tests.
UnitTests in Each Project
- Pro: Developers can easily run unit tests on a single
project.
- Pro: When you branch, your branched folders include 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: It is generally harder to run all unit tests at once
at build time across all projects.
Storing Documents
The Documentation 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 Microsoft Windows SharePoint®
team site, consider the following:
- Use SharePoint for internal team documents 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. By doing so, you get notified when a file is in
use and you help avoid having to perform manual merges.
Use caution when using SharePoint because strict management
of document versions is required. It is easier to overwrite changes in
SharePoint compared to TFS source control. By default, SharePoint enables the
"overwrite existing file" option selected when files are uploaded.
Client-Side Structure
The local folder structure on your development workstations
should be identical to the server folder structure. Keep source artifacts well
organized on your workstations by placing all source from all team projects
together beneath a single root folder, such as C:\DevProjects. Create one
sub-folder for each team project as shown in this example:
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 application
folder structure used on the source control server as shown in the following
example:
\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
\Docs à Contains product documentation
\Tests à Container for tests
\FunctionalTests
\PerformanceTests
\SecurityTests
Note: The client-side structure automatically mirrors
the server-side structure if you create a workspace mapping from the
application root to your local computer. However, in very large projects this can
result in slow workspace load times. To optimize your approach for very large
projects, create workspace mappings below the root to only retrieve the files
you need for development.
Branched Folders
To support development isolation with branches, create
additional folders as siblings of Main. You can also place additional
Visual Studio solution (.sln) files in Main to enable developers to work
with various groupings of projects. Branches created from the Main
source folders can be used to support ongoing maintenance of product releases
or parallel streams of development.
In the following sample structure, in addition to the Main
root folder, a Development folder (branched from Main) is used to
provide isolation for features or for teams. A Releases folder which is
a container for release branches (again branched from Main) provides
isolation for released builds that require ongoing maintenance and current
release lockdown.
$MyTeamProject1
/Development
/FeatureBranch1
/Source
/MyApp
/FeatureBranch2
/Source
/MyApp
/Main
/Source
/Releases
/Release1 – Maintenance
/Source
/MyApp
/Release2 – Maintenance
/Source
/MyApp
/Release3 – Current release lockdown
/Source
/MyApp
Note: Do not branch unless you need to. If required,
you can label a release and branch at a later time.
For more information about project groupings and solution
structure, see “Chapter 03, Structuring Projects and Solutions in Source
Control.”
For more information about branching scenarios and related
folder structures, see “Chapter 5, Defining Your Branching and Merging Strategy.”
Workspaces Explained
A TFS workspace is a client-side copy of the files and
folders in TFS 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 in 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 computer, 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.
Note: You can only map each physical location on the
local file system by using a single workspace. However, you can map each server
directory to entirely different local directories by using different
workspaces.
Creating a New Workspace Mapping
Because mappings are recursive, when you create a new
workspace mapping and you perform a Get Latest Version operation at the root of
that workspace, the entire local folder structure is created automatically. The
newly created local folder structure matches the server structure.
Keep the following recommendations in mind when you create
new workspace mappings:
- 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 an appropriate local folder such
as C:\DevProjects\TeamProject1.
Where Are Workspace Mappings Stored?
Workspace information is maintained on both the client and
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 tbl_Workspace and
tbl_workingfolder) in the TfsVersionControl database.
Cloaking
You can use cloaking as a performance optimization when you
want to prevent a part of the source control tree from being retrieved. The
following are typical scenarios for using cloaking:
- You want to build the project locally and a folder is not
needed for the build, for example a documentation folder.
- You are part of a large team project and you only want to retrieve
part of the project.
For either of the above scenarios you can cloak folders to
stop the client retrieving those folders. You cloak folders on the client by
editing the workspace and changing the status of the working folder from active
to cloak.
Keep the following recommendations in mind when you cloak:
- Do not cloak individual files. This is likely lead to
maintenance problems later in the project.
- For a large project, map out the root folder and cloak sub
folders rather than creating multiple workspaces for the project.
What Files Should Be Version 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). Extensible
Markup Language (XML) configuration files contain project and application
specific details used to control your application’s run-time behavior. Web
applications use files named Web.config. Non-Web applications use files named
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 name it
App.config and locate it within the project folder.
- Source files (*.aspx, *.asmx, *.cs, *.vb,
…). These are source code files, depending
on application type and language.
- Binary dependencies (*.dll). If your project relies
on binary dependencies such as third–party dynamic-link libraries (DLLs),
you should also add these to your project within source control. For more
information about managing dependencies, see Chapter 6, “Managing Source
Control Dependencies in Visual Studio Team System.”
What Files Should Not Be Source Controlled?
The following files are specific to each developer and therefore
should not be added to version control:
- 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 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, it is recommended that all team members use a
consistent (local) virtual root location when developing Web applications.
- Build outputs. These include assembly DLLs,
interop assembly DLLs and executable files (EXEs). (However, note that
assemblies such as third-party binaries that are not built as part of the
build process should be placed under version control as described above).
Summary
Structure projects in TFS source control for effective team
development. Use a root-level folder called Main to group together your Visual
Studio projects. The Main folder should contain child folders to store various
project assets such as source code, tests, documents, and team build types.
Use SharePoint for internal team documents such as use cases
and design documentation. Use TFS source control for product-related
documentation that you plan to ship to your customers. This might include
installation and deployment guides, operations guides, and Help files.
Keep the server-side and client-side folder structures
synchronized in order to reduce confusion caused by differences in folder
organization. To optimize your approach for very large projects, create
workspace mappings below the root to ensure that you only retrieve the files
you need for development.
Additional Resources