Using Global Assembly Cache Tool (GACUTIL.EXE) effectively

The Global Assembly Cache Tool, or GACUTIL.EXE, is a great tool. I see a lot SharePoint developers not being too familiar using GACUTIL, since Visual Studio 2010’s built-in SharePoint Development Tools and SharePoint itself do the necessary plumbing and dirty work for you.

Sometimes things will break and you need to troubleshoot – that’s why I feel anyone doing custom development or managing customizations built for SharePoint need to understand how to use GACUTIL.EXE effectively.

Why do I need this tool?

The Global Assembly Cache or GAC, is a machine-wide cache for .NET assemblies. This includes assemblies provided in .NET Framework and any custom assemblies you’ve created, or any third party application has installed.

GAC can be found under %SYSTEMROOT%\Assembly – normally this maps to C:\Windows\Assembly:

Windows Explorer shows you a virtual view. It’s using something called the Assembly Cache Viewer (shfusion.dll) under the hood to provide this functionality. However, starting from .NET Framework 4.0, shfusion.dll has been marked obsolete and is removed.

The reason you most probably can still use the tool is the fact that it was deployed with older .NET Frameworks, but not automatically removed. A quick search reveals my copy of shfusion.dll belongs to .NET Framework 2.0:

This matters, because the now-obsolete shfusion.dll is not able to show any .NET Framework 4.0 assemblies. You can verify this by sorting by version – the only 4.0.0.0-assemblies listed are those that are not deployed through .NET Framework 4.0. Just so you know, when you are frantically searching for those v4 assemblies that seem to be missing.

If you use Command Prompt, the view under \assembly is quite different:

By having a centralized directory structure for all .NET assemblies provides a shared library throughout the operating system. GACUTIL.EXE is the command-line tool to manage, install and uninstall assemblies residing in this virtual directory.

Prerequisites for using GACUTIL.EXE

Each assembly file that resides in \assembly must be strongly named, meaning each file should be signed with a signature. The Strong Name Tool (sn.exe) is the equivalent of using Visual Studio to sign the assemblies you are about compile and create.

You can use the Strong Name Tool to verify the assembly you are working with is in fact signed properly. The parameters specified are case-sensitive. The command to view existing signature of a given assembly is sn.exe –Tp <assembly>. If I run sn.exe against an assembly that is not properly signed, I get a note saying the assembly is not valid:

If I run sn.exe against an assembly that is properly signed during compilation time, I can see its public key and public key token:

Using GACUTIL.EXE: Installing assemblies to GAC

Command line tools are best when they are simple, yet powerful. GACUTIL.EXE is excellent in this: It only has a few parameters and they are meaningful, and even obvious. The tool itself is included with Visual Studio – the easiest way to use GACUTIL is to open a Visual Studio Command Prompt.

To install a signed assembly to GAC, the syntax is gacutil.exe /i <assembly>:

To verify that GAC is updated, or at a later stage inspect what really is currently stored in GAC, use gacutil.exe /l <assembly>. Note however, that you need to exclude the file extension (typically .dll):

If you omit the /l –parameter, you get a list of everything that is in GAC:

Using GACUTIL.EXE: Removing assemblies from GAC

Sometimes you need to forcefully remove assemblies from GAC. Maybe a program didn’t uninstall correctly and you need to make certain that left-over files are removed correctly.

To remove a single assembly from GAC, use gacutil.exe /u <assembly> (once again excluding the file extension):

If you want to remove a specific version when you have multiple versions of a given assembly, you can specify the fully-qualified name in the typical .NET-friendly (and human unfriendly) format: gacutil.exe /u SignedLibrary,Version=1.0.0.0,Culture=neutral,PublicKeyToken=[token]

You can use the /f (force) parameter to enforce any uninstall action: gacutil /uf <assembly> would try to forcefully uninstall the specified assembly.

References

• Global Assembly Cache Tool: Parameters
• Assembly Cache Viewer (shfusion.dll)
• Global Assembly Cache