Integrating GAC Assemblies with Visual Studio

Created: 19 February 2006

The question comes up all the time about how to get documentation and debugging support for GAC assemblies into Visual Studio (VS).  This article will discuss the steps it takes to make this happen.  The steps are straightforward once you understand what goes on behind the scenes.

Visual Studio and the GAC

The first thing that must be understood is the fact that VS does not reference assemblies from the GAC.  If you open the Add References dialog in VS you will notice that none of the assemblies are actually coming from the GAC.  Instead the .NET framework assemblies are pointing to C:\Windows\Microsoft.NET\Framework\vx.y.z while SQL and Office point to different directories.  VS ALWAYS refers to assemblies from regular directory paths.  At runtime the CLR will load GAC assemblies from the GAC but this is independent of VS.

The next thing to understand is that the GAC only supports storing assemblies.  Documentation and debug files, along with configuration or other files, can not go in the GAC.  Therefore if VS did use the GAC it still would not have access to the documentation or debug files of assemblies.  So how do we get VS to recognize these files?

Assembly Folders

All assemblies along with their debug (PDB) and documentation (XML) files should be installed into a normal directory.  This is in addition to placing the assemblies in the GAC.  The target directory for these files is known as the assembly folder.  It is this folder that you will point VS to.  When VS loads an assembly it will automatically pick up any PDB and XML files in the same directory provided they match the assembly.  If VS loads the PDB file then debug information is available for the assembly.  If VS loads the XML file then Intellisense will display documentation about the members of the assembly.  This is automatic.

So, when installing your GAC assemblies, copy the original assemblies, the associated PDB files and the XML documentation files to a normal directory.  Then install the assemblies into the GAC.  Now all you need to do is have your users point VS to the appropriate folder and they'll get debugging and Intellisense support.

Registering Your Assembly Folder

I know what you are thinking.  "But SQL, Office and .NET itself automatically shows up in Add References dialog.  My assemblies do not even though I put them into the GAC.  What is going on?"  Please refer to what I said in the first part of this article: "VS ALWAYS refers to assemblies from regular directory paths."  The Add References dialog IS NOT populated from the assemblies in the GAC.  VS must be told where the assemblies come from.  Enter the Registry.

When VS wants to get the assemblies for the Add References dialog it will query the Registry for the keys under HKLM\Software\VisualStudio\8.0\AssemblyFolders.  Each key under the main key represents an assembly folder.  The actual name of each key is irrelevant but the default value of the key must be the full path to an assembly folder.  VS will add all the assemblies from the assembly folder to the Add References dialog.

Therefore if you want your assemblies to automatically show up in the dialog all you need do during installation is to add a new subkey under the base key, given earlier, and specify the full path to your assembly folder as the default value.  VS will automatically list your assemblies when the dialog is displayed.  Assuming that you followed the steps given earlier in the article the user will also automatically have debugging and documentation support. 

Here is an example of what you might have in the Registry:

HKLM\Software\Microsoft\VisualStudio\8.0\AssemblyFolders\AvalonAssemblies => (Default): C:\Windows\Microsoft.NET\Windows\v6.0.4030
HKLM\Software\Microsoft\VisualStudio\8.0\AssemblyFolders\Kraken => (Default): C:\Program Files\Kraken\v2.1.0

Putting It All Together

So, in summary, to expose your GAC assemblies, debug files and documentation files to VS do the following.

1. Create a regular directory for your files.
2. Copy the assemblies, debug files and documentation files to the directory.
3. Install the assemblies into the GAC.
4. Create a new subkey under HKLM\Software\Microsoft\VisualStudio\8.0\AssemblyFolders.
5. Set the default value of the key to the directory created in step 1.

Caveats

When I say that VS does not use the GAC please be aware that it might but not in a manner in which we can take advantage of it here.  You will also notice that the core framework is not listed in the Registry.  Whether the framework is hard-coded into VS or whether it uses a different techique I can not say for sure.  Nevertheless it is not extensible for our purposes.