Chapter 4 – Structuring Projects and Solutions in Team Foundation Source Control
.png "patterns & practices Developer Center")
Team Development with Visual Studio Team Foundation Server
| Retired Content |
|---|
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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:
- How To: Create Your Source Tree in Team Foundation Server.
- How To: Structure ASP.NET Applications in Team Foundation Server.
- How To: Structure Windows Applications in Team Foundation Server.
- How To: Structure Your Source Control Folders in Team Foundation Server.
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 pendingchanges, 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
- For more information about Team Foundation Source Control, see “Using Source Code Control in Team Foundation” at https://msdn.microsoft.com/en-us/library/ms364074(VS.80).aspx
- For more information about creating a workspace, see “How to: Create a Workspace” at https://msdn.microsoft.com/en-us/library/ms181384(VS.80).aspx