Visual Studio uses references to identify the external assemblies that your project relies on. How these references are used depends on the type of reference as well as a number of other factors.
Adding a reference to a project is a simple matter of right-clicking on the references folder of a project and selecting Add Reference. (Add Web Reference is a completely different feature that is used for creating a reference to a web service and won't be covered here.)
The Add Reference dialog contains a number of tabs, three in Visual Studio .NET 2002 and 2003 and five in Visual Studio 2005. Figure 1-11 shows the Visual Studio .NET 2003 Add Reference dialog.
The .NET tab contains a list of .NET assemblies. You can select any of these assemblies and create a reference to that assembly. The COM tab contains a list of all the registered COM objects that you can reference. The Projects tab contains a list of all the projects in your solution, and by selecting one, you can create a reference directly to that project.
Visual Studio 2005's Add Reference dialog is shown with its extra tabs (Browse and Recent) in Figure 1-12.
The Browse tab is used to browse for an assembly from the filesystemthe same as the Browse button from the Add Reference dialog of older versions of Visual Studio. The other new tab is the Recent tab, which shows any assemblies you have recently used.
The majority of the time this process is as simple as selecting what you want to reference and then clicking the OK button. However, a better understanding of how references work will help avoid headaches when sharing projects between users and when working with projects under source control. One of the most frequent issues that developers encounter when working with shared solutions and projects is broken references.
The first tab that you see in the Add Reference dialog is the .NET tab, which lists .NET assemblies you can reference in your application. You can add a reference to any of these assemblies by simply clicking on the assembly and then the Select button. You can also use the Browse tab or Browse button to manually browse the filesystem for an assembly.
The list of assemblies displayed in the .NET tab is based on a set of directories that is configured through the registry. Visual Studio generates this list by iterating through the .NET Framework directory as well as any directories configured in the registry. You can add your own assembly to this list by adding a key to the registry with the directory your assembly is located in:
Open regedit (click Start
Navigate to HKEY_LOCAL_MACHINE if you want to add the directory for all users on your machine or HKEY_CURRENT_USER if you want to add the directory just for yourself.
Navigate to Software/Microsoft/.NETFramework/AssemblyFolders. Under this folder, you will see all the currently configured entries. (If you are configuring this under HKEY_CURRENT_USER, you may need to create the .NETFramework and AssemblyFolders keys.)
Right-click on AssemblyFolders, choose New
Double-click on the (Default) value of your new key and specify the directory you want to add.
Any assemblies in that directory will now appear in the list of assemblies listed in the .NET tab. You can also add a directory for a specific version of Visual Studio by following the preceding procedure but using the AssemblyFolders key, which can be found at Software/Microsoft/VisualStudio/7.1/AssemblyFolders.
Items that appear in a project's references folder are more than simple references to files. The assembly that is ultimately linked into the project is resolved using a complex set of rules. If a referenced assembly exists in the project directory but is not visible in the project, there is no guarantee it will be used. (This is a common misconception and can lead to a lot of confusion.)
The rules Visual Studio uses to resolve references are as follows:
Assemblies that are visible in the project as project items or links are considered. If Visual Studio .NET 2005 with MSBuild is being used, these must have a Build Action of Content or None.
Assemblies in Reference Path directories are considered. These are stored in .user files and are visible under project properties.
The HintPath of the reference is considered. This is a path to the referenced assembly (relative to the project). It is stored when the reference is originally created.
Assemblies in the native framework directory are considered (e.g., \Windows\Microsoft.NET\Framework\v1.1.4322 for Visual Studio .NET 2003).
Assemblies in the registered assembly folders are considered. These are the directories discussed in the last section about adding assemblies to the list of .NET assemblies. If Visual Studio .NET 2005 with MSBuild is being used, HKLM\Software\Microsoft.NETFramework\v2.x.xxxxx\AssemblyFoldersEx will be considered first.
If Visual Studio .NET 2005 with MSBuild is being used and the assembly has a strong name, Visual Studio will look in the GAC for the assembly.
It is important to note that this is the resolution process that Visual Studio goes through when determining what assembly to link to a project when building the solution, not the process that .NET goes through when finding the assembly to use when running the application.
References can become a problem if your project needs to be opened by another user who quite possibly won't have a copy of the assembly you are referencing. You can solve this problem in a number of ways. The easiest way is to make a copy of the assembly and include that assembly in your project. You cannot simply copy it to your project directory; you also need to ensure that it is a part of your project in Visual Studio. That way, you know that whoever opens the project will have access to this file. The major downside to this solution is that anytime this assembly changes, you will need to make a copy of the assembly and copy it into your project before you get the changes.
A good solution to the file reference issue is to create a single folder that contains all of the assemblies that are referenced through file references. This way, all the developers on a project can retrieve the latest versions of these assemblies from the same location, whether through a common shared directory or source control.
A project reference refers to another project in your solution; for instance, you might have a Windows Forms project that references a class library project. When the Windows Forms project is built, it will create a copy of the class library assembly and move it to your output directory.
What makes a project reference superior to an assembly reference is that Visual Studio will watch for any changes to the other project. When there are changes, you will automatically get a new copy of the assembly in your build directory. Visual Studio will also use project references to infer project dependencies. In the case of a Windows Forms project referencing a class library project, Visual Studio will determine that the class library project needs to be built before the Windows Forms project since the Windows Forms project depends on the output of the class library.
Project references also avoid problems when sharing the project between systems or when working with projects under source control.
The main thing to remember when working with references is to think not only about how the reference will work for you, but also how it will work for other developers working with your solution.
James Avery and Jamie Cansdale