Structuring Solutions and ProjectsMicrosoft Corporation January 2002 Summary: This chapter explains how you should organize and structure Visual Studio .NET solutions and projects, and it presents the tradeoffs associated with single-solution and multi-solution development models. It also recommends folder structures that you can use to store projects locally and within Visual SourceSafe (VSS). This is Chapter 3 of the Team Development with Visual Studio® .NET and Visual SourceSafe? guide. Start here to get the full picture. To ensure that your development and build processes work effectively in a team environment, it's essential to start with a correct project structure that is consistent across all of your development workstations and build server. This chapter presents guidelines on:
Visual Studio .NET Solutions and ProjectsBefore discussing how to organize Visual Studio .NET solutions and projects, it's very important that you understand their basic mechanics and how they are managed locally and by your source control providertypically VSS. If you are already familiar with Visual Studio .NET solutions and projects and you understand the various file types comprising a project, you can skip this section and jump to Always Use Visual Studio .NET for Source Control Operations. Visual Studio .NET ProjectsVisual Studio .NET uses project files as containers for all of the build and configuration settings required to generate a .NET assembly. Project files have either a .csproj or .vbproj file extension, depending upon the project's language. There are many different project types [and associated Rapid Application Development (RAD) templates] although these can be divided broadly into two categories. The two categories of project types are:
Visual Studio .NET SolutionsSolution files (with the .sln file extension) are used to group related projects together and are primarily used to control the build process. You can use solutions to control build dependency issues and control the precise order in which contained projects are built. Important A project can be part of one or more solutions but solutions can't be included within other solutions. Figure 3.1 illustrates the relationship between projects and solutions and indicates the file types used by VSS to maintain solution and project level settings: Figure 3.1. Visual Studio .NET Projects and Solutions Solutions and Build DependenciesThe solution file also contains project dependency information used by the build process. For example, in the preceding diagram, the dependency information indicates that Project A depends upon Project B and Project B depends upon Project C. As a result, the build order must be Project C, then Project B, and then Project A. When project references are used within a single solution, Visual Studio .NET ensures the correct build order. Important There are two basic types of referencesproject references and file references. You set both types by using the Add References dialog box in Visual Studio .NET. Because project references also establish build order dependencies, you should use them whenever possible. For more information, see Referencing Assemblies in Chapter 4, "Managing Dependencies." Files Subject to Source ControlThe following list identifies the key file types that are automatically added to VSS when a solution is added to source control by using the Visual Studio .NET integrated development environment (IDE):
Note For Web applications, the source controlled configuration file is called Web.config. For non-Web applications, the source controlled file is called app.config and is contained within the project folder. At run time, the Visual Studio .NET build system copies App.config to the Bin folder and renames it to 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.
Files Not Subject to Source ControlThe following files are not added to source control because they are developer specific:
Always Use Visual Studio .NET for Source Control OperationsAll project creation and manipulation within VSS should be performed by using the integrated VSS support menus within Visual Studio .NETdon't use VSS Explorer for this. The Visual Studio .NET functionality guarantees that:
Other files, including the solution user file (.suo) and project file (.csproj or .vbproj), are also updated. Important Always interact with VSS through the Visual Studio .NET interface instead of through the VSS Explorer. The tight integration of the products ensures that files are managed correctly in a team environment. Partitioning Solutions and ProjectsThe way you partition solutions and projects has a big impact on the way your development efforts and build process function in a team environment. There are three main models to consider for partitioning solutions and projects. In order of preference, these are:
Important Unless you have very good reasons to use a multi-solution model, you should avoid this and adopt either a single solution model, or in larger systems, a partitioned single solution model. These are simpler to work with and offer a number of significant advantages over the multi-solution model, which are discussed in the following sections. Use a Single Solution Model Whenever PossibleWith the single solution model, you create a single Visual Studio .NET solution and use it as a container for all of the projects defined by your application. Note the following when you use a single solution model:
Figure 3.2. The Single Solution Model Use a single solution model whenever possible because it offers a number of significant advantages. AdvantagesThe single solution model offers the following advantages:
DisadvantagesYou are advised to adopt the single solution model whenever possible. However:
Consider a Partitioned Single Solution Model for Larger SystemsFor larger systems where you want to reduce the number of projects and source files required on each development workstation, consider grouping related sets of projects together within separate subsolution files. This allows you and fellow developers to work on separate and smaller subsystems within the inner-system boundary. Note A single project file can be included within one or more solution files. Solutions cannot be included within other solutions. Figure 3.3 illustrates the partitioned single solution model. Notice how separate solution files are used to allow you to work on smaller subsystems contained within the inner system boundary. Also note how this results in projects being contained within more than one solution file. For example, Projects D and H are in a total of three solution files including the master solution. Figure 3.3. The Partitioned Single Solution Model In the partitioned single solution model:
Note You should not separate two projects that reference one another into separate solutions, because this would necessitate the use of a file reference which should be avoided wherever possible. For more information, see Referencing Assemblies in Chapter 4, "Managing Dependencies". AdvantagesThe partitioned single solution model offers the following advantages:
DisadvantagesThe partitioned single solution model suffers from the following disadvantages:
Use a Multi-Solution Model Only if Absolutely NecessaryThe multi-solution model is similar to the partitioned single solution model except:
The multi-solution model is illustrated in Figure 3.4: Figure 3.4. The Multi-Solution Model AdvantagesThe multi-solution model offers the following advantages over the partitioned single solution model:
DisadvantagesThe multi-solution model suffers from the following disadvantages:
You should easily be able to work with a single solution that contains 10, 20, or even 30, projects. The maximum number of workable projects within a solution is difficult to precisely define, because it depends on the specification of your build server and development workstations and the size and number of source files associated with individual projects. Considerations for Grouping Projects into SolutionsThe best way to approach the problem of grouping projects into solutions is to consider the overall architecture of your application. For example:
If you break your projects into multiple solutions and cannot do so using the partitioned single solution model, carefully consider your cross solution dependencies, and the nature of the interfaces that separate the two dependent assemblies. When you organize projects into separate solutions you should:
Use a Consistent Folder Structure for Solutions and ProjectsLife in a team development environment is a whole lot easier if you use a common structure for storing Visual Studio .NET solutions and projects. To keep things symmetrical (and as a result, simpler), set up a folder structure within VSS that matches your local file system structure. Define a Common Root FolderDefine a common root folderfor example, C:\Projects on your file system and $/Projects within VSS. This acts as a container for all of your development systems. Beneath the common root folder, create a system root folder for each of your systemsfor example, C:\Projects\MyCompanysInsuranceApp and $/Projects/MyCompanysInsuranceApp respectively. Adopt a Parent-Child Folder Structure for Solutions and ProjectsYou should adopt a parent-child folder structure for solutions and projects. To do this:
Note If you use the partitioned single solution model, place project folders beneath the folder that contains the main solution file. For any subsolutions that you create, include project files directly from this location. Figure 3.5 demonstrates the recommended structure: Figure 3.5. Visual Studio .NET and VSS Folder Structure The following subsections describe how to use the Visual Studio .NET IDE to create the appropriate structures for Web and non-Web applications. How to Create a New ASP.NET Web ProjectBy default, when you create a new ASP.NET Web application, the project file is located in a nominated virtual root beneath your default Web site (usually \inetpub\wwwroot) and the associated solution file is located beneath \My Documents\Visual Studio Projects. This default arrangement is not ideal in a team development environment because it breaks the symmetrical structure between your VSS projects and local files. The following steps guide you through the creation of a new ASP.NET Web application in accordance with the recommended solution and project folder structure. The steps assume a solution called MyWebAppSolution and a project call MyWebApp. If you include the word Solution (or Soln) in the solution name, this helps to clearly differentiate it from the project file name. The desired structure is shown in Figure 3.6. Note that the project folder and Microsoft Internet Information Server (IIS) virtual root are one and the same. Figure 3.6. Recommended Web Application Structure To create a new Web application with this structure
How to Split a Web Application into Multiple ProjectsIn some cases, you may want to divide your Web application into multiple projects within the same solution to facilitate team development. For example, if you have separate teams responsible for different aspects of the same Web application, it is useful to be able to divide the application into multiple projects. This capability is not supported natively by Visual Studio .NET, but it can be achieved with some manual manipulation of virtual roots. Important A single project approach is simpler, so split a Web application up into multiple projects only if absolutely necessarytypically for very large Web applications. More InformationFor more detailed information about creating sub Web projects, see article Q307467, "HOWTO: Compose a Visual Studio 7 .NET ASP.NET application out of multiple project to facilitate team development," in the Microsoft Knowledge Base (available soon). Working with ASP.NET Code-Behind FilesYou should be aware that when you check out a Web form (aspx) file or a code-behind file (aspx.cs or aspx.vb), Visual Studio .NET automatically checks out both files. This is by design because user interface changes generally involve an aspect of coding within the code-behind file. For example, if you add a new control to a Web form, Visual Studio .NET automatically creates a member variable for the control in the code-behind file. How to Create a New Non-Web ProjectThe following steps guide you through the creation of a new non-Web project type such as a Windows-based or console application, a class library or a service. The steps assume a solution called MyWinAppSolution and a project call MyWinApp. The desired structure is shown in Figure 3.7: Figure 3.7. Recommended Project Structure for non-Web Projects To create a new non-Web application with this structure
For information about how to add the newly created project and solution to Visual SourceSafe, see How to Check In a New Solution to VSS in Chapter 6, "Working with Visual SourceSafe." Carefully Consider Naming ConventionsGive careful and early consideration to the way you name projects, assemblies, folders, and namespaces. While it is possible to rename these items later on in the development cycle, you should avoid this if possible. For information about how to rename a project, see Renaming a Project in Chapter 6, "Working with Visual SourceSafe." You should also aim for a consistent set of names because this can greatly simplify project organization. Use Common Names for Projects and AssembliesYour output assembly name should always match the project name from which it is generated. For example, you should be able to assume that an assembly called MyCompany.Utilities.Data.dll is generated by a project called MyCompany.Utilities.Data. If you change the name of an output assembly, consider changing the project name to match, and vice-versa. Use a Common Root Namespace NameThe root namespace into which you place your types (structures, classes, interfaces, and so on) should match the project and assembly name. For example, use MyCompany.Utilities.Data as the root namespace within the MyCompany.Utilities.Data.dll assembly. While .NET does not require this alignment, it makes sense to synchronize names because it then becomes easy to tell which types live in which assemblies. Note Microsoft Visual Basic® .NET projects expose the root namespace via project properties. By default, any type created within the Visual Basic project will be placed inside this namespace. If you use explicit namespace statements in your Visual Basic .NET project, delete the root namespace entry, otherwise the explicit namespace name is appended to the root namespace name. C# projects expose a default namespace property via project properties. This is again used to determine the namespace into which new types added to the project are placed. However, unlike Visual Basic .NET projects, the root namespace is explicitly stated via namespace statements within your source files. Use Common Names for VSS and Local FoldersAs mentioned earlier, keep your local solution and project folder names in synchronization with their equivalent VSS folder names. This is Chapter 3 of the Team Development with Visual Studio .NET and Visual SourceSafe guide. To read the next chapter, please see Chapter 4, "Managing Dependencies." |
|