Working with Assemblies in the GAC

I know there is a lot of information in the net about the GAC, so this post is going to cover the basics you need to work with the Telerik RadControls for ASP.NET AJAX. I also know it has been a long time since the first post in the series that treats the easiest upgrading approach, but you know what they say – better late than never :) For the impatient ones – go explore the references. So, let’s start with the Global Assembly Cache fundamentals:

What is the GAC

GAC is the short version of "Global Assembly Cache". It is a common place in the OS where assemblies that are going to be shared between different applications can be stored. The .NET assemblies are there, for one.

Where is the GAC

 Up until .NET 3.5 it was in C:\Windows\Assembly\
Since .NET 4.0 it is now in C:\Windows\Microsoft.Net\Assembly\GAC_MSIL\ and also the shell integration was removed, so you can no longer drag-and-drop an assembly in the folder and have it registered. More on that – later on.

Pros and Cons

Arguments and cases to support the GAC:

• Assemblies are shared between all applications on the machine, which is excellent for SharePoint
• Versioning is easy because the GAC can hold multiple versions of the same dll without issues
• A local copy in the Bin folder of the application is not needed, so you can shave off a few megabytes on the hard drive of your server

Disadvantages of using the GAC:

• The assemblies need to be added explicitly to the GAC when the application is deployed, a simple copy-paste no longer suffices
• Microsoft recommend that you do not use the GAC, but keep relevant assemblies in the Bin
• To put an assembly in the GAC it has to be signed, but this process is beyond the scope of this post
• Usually, elevated user privileges will be needed to modify the GAC

And one that can go in either category

• the GAC runs under full trust, while the Bin of a concrete application can be under Medium trust, depending on the environment.

Before you ask about performance - whether there is a performance gain is a question that is really difficult to answer because JIT compilation also yields great results. Perhaps for a large number of applications that use the same assembly there may be a difference but confirming or refuting this claim is a long story that is not the point of this post.

Add, Remove and View Assemblies in the GAC

First, you are going to need a tool from the .NET SDK that comes with Visual Studio – gacutil.exe. To run it go to Start -> All Programs -> Visual Studio <version> -> Visual Studio Tools -> run the Visual Studio Command prompt (or Developer Command prompt, depending on the VS version you use, but you got the idea, I think).

To install an assembly called SomeAssembly in the GAC, use the command

Note that the full path must be used so that the tool grabs the correct assembly.

To remove this assembly from the GAC, use the command

For this you only need the assembly name. Now, this will remove all versions of our assembly, so you may want to add versioning information:

where, of course, this fully qualified assembly name is a mere random example.

To view the contents of the GAC:

There are more options the tool offers, so MSDN holds the answers for the curious ones.

There are other ways to add an assembly to the GAC (Windows offers a shell integration for .NET 3.5 so you can just drag-and-drop it; and the Windows Installer) but since the gacutil tool is available for standalone download without Visual Studio I am not going to cover them. What I want to say is that Microsoft do not recommend using gacutil in production environment.

Referencing Assemblies from the GAC

Here is where things get interesting and confusing for some.

Each application still has to reference the assembly in order to use it, it does not matter whether from its own Bin folder, or from the GAC. The tricky part is “how”.

Let’s start, however, with a more basic task – recognizing a GAC reference (assuming you already have some of the Telerik.Web.UI assemblies installed in the GAC, I’ve chosen one of the older versions for this example):

How GAC References Look

Here is an example with two of our RadControls assemblies for a WebSite type of project:

An easy approach is to use the Property Pages dialog where you can manage the references:

Here is another way to tell:

Yes, this is in the web.config file of your website. Doesn’t look complicated, right? What you need to keep in mind is that such a reference requires the fully qualified assembly name in order to work.

A WebApplication requires that you examine the Telerik.Web.UI reference Properties under the References node in the Project tree. You will see how it is not a local copy of the assembly and that the path points to the GAC:

Now, repeat for the Telerik.Web.UI.Skins assembly.

Adding a Reference to an Assembly from the GAC

Let’s take the visual approach first:

For a WebSite	For a WebApplication
1. Open the Property Pages	1. Open the Add Reference dialog
2. Browse to the GAC to select assembly
3. Confirm the reference properties

Now, for some explanations to go with the images:

For a WebSite project just add the above reference in the web.config. I find it easier to write a couple of lines, but you can, alternatively, open the Property Pages dialog, click Add and browse to the GAC on your machine (we already learned where it is). In any case, you need to see the same final result that I showed above.

Just account for your current version, of course, and always use the same version for all Telerik.Web.UI.* assemblies.

A WebApplication needs more care, as usual, you can’t just write two lines of XML.

First, you need to know where to look in order to point the Add Reference dialog to the right assembly when you browse (see the Where is the GAC part above).

Then, make sure the Copy Local property is set to False and that you are referencing the expected version.

Now that you know what to look for things should be rather straightforward.

Common Issues

The first problem you may encounter is that the .NET tab of the Add Reference dialog box in VS will not show custom assemblies you have added to the GAC, you either need a third party plugin for your IDE, or a registry key so that it can know about this third-party assembly. Manually browsing to the desired folder is an easy resolution.

Then, you can often get the “Could not load file or assembly…” error. It means the reference is typed in wrongly or the assembly is not actually in the GAC of the machine. This can also be caused by wrong version numbers (e.g. Register directives left over in old user controls). A way to skip a seek-and-destroy mission through your site is to use a bindingRedirect. This is useful for SharePoint and Sitefinity scenarios.

“CS0433: The type ‘<RadControl class>’ exists in both ‘<assembly in the GAC>’ and '<Temporary ASP.NET Files for the site>” – this means there is a duplicate reference to our assembly – one that points to the GAC and one that points to a file somewhere else on the machine. Check your project references, clear the ASP cache and you should be fine.

Telerik and the Global Assembly Cache

Our assemblies are standard .NET assemblies, so all generic rules apply to them as well. There is nothing special and the above examples prove it – replace our assemblies with any other for the same approach and steps.

What we advise is that you keep the Telerik.Web.Design.dll assembly in the GAC (our installation wizard will put it there) in order to have access to the design-time mode of the RadControls, and reference the other assemblies (Telerik.Web.UI.dll and Telerik.Web.UI.Skins.dll) from the BIN folder.

What we learned today

There isn’t anything really hard about working with GAC references, just take a look at the Global Assembly Cache tutorial above and bookmark it for future reference. This will let you examine and properly update references to our assemblies when needed.

More importantly, we learned what the GAC is, what it is and is not good for.

If you have anything to add or you use another approach for working with the references in VS – let us know in the comments below!