When working in the Microsoft development environment, you are using one of two kinds of projects: reference-based or directory-based. These distinctions are not presented as categories within the environment, but they influence how your projects will be treated in source control tasks.
The reference-based project is similar to a Microsoft® Visual Basic® or Visual C++® project, in that it uses a project file to list and track files contained in the project, source code control information on those files, and other data. These project files may be physically located anywhere on the developer's system. Examples of a reference-based project (in the development environment) include Utility Projects or Database Projects.
The directory-based project is similar to a Visual J++™ project, in that it uses the directory that holds the project to define the list of files to build for that project. The directory-based project contains a project file but does not use that file as its only method of defining the list of files and their respective locations. All files in a directory-based project must be in the project's root directory or a subdirectory of the project's root directory.
The following table lists and compares characteristics of these two project models:
| Reference-based projects | Directory-based projects |
| You use the project file as the current list of files to build. This is also how a reference-based project tracks dependency files for builds. | You use the actual presence of the files in the specified directory as the current list of files in a project (along with maintaining a file list in the project file). |
| You track source code control issues in the project file. | You track source code control issues by altering directory contents. |
| Only files you choose in your settings for your build configuration are included in builds. | You can choose files to drop out of the build in the Project Explorer by removing them from the project. This will not delete the files but make them appear a lighter gray in the display. |
| You can build multiple projects that reference a single item in one location. | You must keep a separate copy of an item in a different directory for each project in which it builds. |
| You can keep files in the directory that are not part of the project. | You only include files that are completed and built in the directory. The files in progress are kept locally. |
| You can have placeholder or incomplete (or not built) files in the directory. | All files in the project directory will be built. Use the Exclude feature in the Project Explorer to ensure that the project contains only files that can be built. |
| A project can span subdirectories. You can use this to sort file types, possibly storing core files in one directory, user interface files in another, and so on. The project's files may be anywhere on the developer's system. | Each project is completely contained within its directory or a subdirectory of the project's root directory. |
| Multiple projects can be located in the same directory. | One project is contained in a given directory. |
| Only files referred to in the project file will be synchronized with source code control. | Files contained in the project directory are included in the next build after you synchronize with source code control. |
| When moving files, file paths must be updated in the project file. | No absolute path names in the project file, so the project can be moved as an entire unit, by moving the entire directory. |