LearnVSXNow! #8: Intermezzo — The regpkg.exe utility

When I started to write the next post for the series “Creating our first toolset”, I realized that my registry is polluted with the package registration entries for my former sample projects. While I cleaned up the “junk” by unregistering those packages, I got into an “intimate” relation with regpkg.exe. Previously I planned to wrote a post about this topic, but at this point I decided not to postpone it even if I had to make a short unexpected break.

So, in this post you can read those stuff I think is important to know about this utility. The VS 2008 SDK documentation does not tell too much about regpkg.exe, here I try to help you with some predigested information from my experience.

Getting familiar with regpkg.exe

If you read the previous posts and created the sample packages, till this time you have a few VSPackages registered under the experimental hive of Visual Studio. Due to the registrations your registry (and your VS Experimental Hive) gets polluted with unused but still registered packages. To clean up this mess, we are going to have a closer look of regpkg.exe and use it to unregister the packages.

Any package and its objects (like menu commands and tool windows) can be integrated with Visual Studio IDE through the registration process driven by the regpkg.exe utility that ships with the VS 2008 SDK (and of course with SDKs related to VS 2005). This utilities responsibility is to register and unregister VSPackages, and to provide utility functions for “manual” registration and removal.

Which regpkg.exe to use?

If you have installed VS 2005 SDK and VS 2008 SDK on your computer, you have two versions of regpkg.exe utilities on your machine. Each can co-operate only with the package developed in the corresponding version of VS SDK. If you put the folder name of any regpkg.exe into the environment variable in order to find them automatically, you may have problems by running the incorrect version. When you get an error message about failed package registration the number one reason can be the wrong regpkg.exe version.

The VS 2008 SDK version of the utility can be found under your VS 2008 SDK installation folder (see the VSSDK90Install environment variable) in VisualStudioIntegration\Tools\Bin. Under Bin you can find a VS2005 folder and there is the VS 2005 SDK version of regpkg.exe.

Why is this difference between the two versions? The regpkg.exe scans a .NET binary for attributes attached to a Package derived class. These attributes are defined in the Microsoft.VisualStudio.Shell.dll interop assembly for VS 2005 and in the Microsoft.VisualStudio.Shell.9.0.dll for VS 2008. The registration attributes (even having the same name) are different and so regpkg.exe does not find them.

You can check this behavior. Remove the reference for the ~Shell.9.0.dll for any VSPackage project and add instead a reference to the ~Shell.dll interop assembly. When you compile your VSPackage you will get a “No registration data found in this assembly” error message. This message comes after you successfully compiled you package, since changing the reference assemblies does not cause compilation failure. You get the message from the MSBuild task that run regpkg.exe, and the reason of the failure is the problem with the registration attributes.

What does regpkg.exe do?

Regpkg scans the specified assembly and looks for attributes that are related to registration. Collects those attributes and creates a list of entries to be used for further processing. By the command line parameters of regpkg.exe we can tell what to do with this registration entry list. We can

—  Export those entries into files to be used later by an installation program (.msi file).

—  Write them to the registry — and so register our package.

—  Delete them from the registry — and so unregister the package.

Using regpkg.exe

When you run regpkg.exe you must pass the name of you assembly along with options (in form of command line parameters) to be used for registration. Regpkg.exe accepts the following command line syntax:

AssemblyPath is the path to your assembly relative to the current folder where you run regpkg. The options specify the operation what you expect and the location of registration entries. The following table summarizes the options you can use with the utility:

Examples

Let’s look some examples of using regpkg.exe!

Creating a .reg file

The following example creates an EmptyPackage.reg file for the registry items related to the EmptyPackage project treated in Part #2:

After running this command line, we can look into the .reg file:

This file contains three sections under the Configuration registry key. The first and third sections reflect one attribute of the EmptyPackagePackage class in the package source code, as we can recognize:

The second section describes the assembly and the package using the Guid attribute.

Registering the package

Omitting the /regfile option our package information goes directly to the registry instead of a file:

We can check how this command line works when opening regedit.exe and looking for the InstalledProducts subkey under the key according to /root:

Unregistering the package

I suppose, you guess how to unregister our package. Yes, we simply add the /unregister option to the command line:

Using regedit.exe you can check that the EmptyPackagePackage registration key has been deleted.

Unregistering packages during development

It would be nice if we could add something to our projects to clean up unnecessary packages from the VS Experimental Hive. We can do it be many possible ways. I suggest you one of the simplest: add a command file (.cmd) to your package projects and put the regpkg.exe call with the /unregister option. Use a command file like this:

I suggest calling regpkg.exe with the VSSDK90Install environment variable to avoid collision with the VS 2005 SDK’s regpkg.exe. I supposed you put the command file in the same folder as the project’s .csproj file. If you did not, please modify the path of your .dll file accordingly.

Do not forget about the fact that when you build the package it will be registered again. If you use a solution with more than one package it is worth to put a .cmd file into the solution folder to unregister all packages in the solution.

Where we are?

Now we have a closer look about what regpkg.exe is and how it works. Because VS 2005 SDKs and VS 2008 SDK use different regpkg.exe files, be careful and always use the correct one.

With this utility you can put registration entries into a file and examine it before actually registering the package. It can help to see what’s behind or even in the case of package registration troubleshooting.

It is a good practice to add a command file to your project to unregister it manually on your demand.