Master Assembly and Project References #2
Chapter 1, Master Projects and Solutions
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 understand-
ing 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.
How the list is created. 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 direc-
tory 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:
1. Open regedit (click Start
➝ Run, then type regedit).
2. Navigate to HKEY_LOCAL_MACHINE if you want to add the direc-
tory for all users on your machine or HKEY_CURRENT_USER if you
want to add the directory just for yourself.
3. 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 cre-
ate the .NETFramework and AssemblyFolders keys.)
4. Right-click on AssemblyFolders, choose New
➝ Key, and name your key.
5. 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 Assembly-
Folders key, which can be found at Software/Microsoft/VisualStudio/
How references are resolved. Items that appear in a project’s references folder
are more than simple references to files. The assembly that is ultimately
Chapter 1, Master Projects and Solutions
#2 Master Assembly and Project References
linked into the project is resolved using a complex set of rules. If a refer-
enced 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 misconcep-
tion and can lead to a lot of confusion.)
The rules Visual Studio uses to resolve references are as follows:
1. 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.
2. Assemblies in Reference Path directories are considered. These are
stored in .user files and are visible under project properties.
3. The HintPath of the reference is considered. This is a path to the refer-
enced assembly (relative to the project). It is stored when the reference
is originally created.
4. Assemblies in the native framework directory are considered (e.g.,
\Windows\Microsoft.NET\Framework\v1.1.4322 for Visual Studio .NET
5. 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.
6. 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.
Managing .NET references. 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 direc-
tory; you also need to ensure that it is a part of your project in Visual Stu-
dio. 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.