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:
regpkg.exe [options] AssemblyPath
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:
| Option |
Description |
| /ranu |
This option is required when you develop a VSPackage with a user account that is not the machine administrator and you want to modify the registry. By using this option registry modification is done within the HKEY_CURRENT_USER hive. I suggest always using this attribute while in development phase.
|
| /root:RegRoot |
Specifies the root item of the registry affected by modifications (key insertion or removal). If not specified, regpkg.exe searches for the DefaultRegistryRoot attribute in the specified assembly to guess out the value of this parameter.
While developing a package you generally use the Visual Studio Experimental Hive, so you must use the Software\Microsoft\VisualStudio\9.0Exp root. Regpkg.exe will put the entries in the Configuration key and its subkeys under the root you specify.
|
| /unregister |
Use this option to sign that you want to remove package information from the registry. You cannot use this option together with any of the file options described in the next row.
|
/regfile:FileName
/rgsfile:FileName
/vrgfile:FileName
/wixfile:FileName
/rgm |
Using any of this options forces regpkg.exe to export registry settings into files to be used by external utilities (e.g. installation programs). The first four options must specify a filename: this is the name of the output file. You can use only one of these options they cannot be combined. The file types are .reg, .rgs, .vrg and .wix according to the specified option. When you choose the /vrgFile option you can also create an additional .rgm file by adding the /rgm option.
If you want to see what kind of information is about to write into the registry, I suggest you to use the /regfile option. After running regpkg.exe you can open the .reg file in Notepad to see the results. By running the .reg file you can merge the information right into the registry.
|
/CodeBase
/Assembly |
When registering a package the assembly containing the package also should be registered, since it have to be loaded into the memory in order to run its code. This assembly can be registered by either with its full name to load from GAC (/Assembly option) or with its physical path (/CodeBase option) to load it from that path.
|
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:
regpkg.exe /regFile:.\EmptyPackage.reg /ranu Ä
/root:Software\Microsoft\VisualStudio\9.0Exp .\bin\Debug\EmptyPackage.dll
After running this command line, we can look into the .reg file:
REGEDIT4
[HKEY_CURRENT_USER\9.0Ex\Configuration\InstalledProducts\EmptyPackagePackage]
@="#110"
"Package"="{223643a0-af7c-4741-99df-e9641691af50}"
"ProductDetails"="#112"
"PID"="1.0"
"LogoID"="#400"
[HKEY_CURRENT_USER\9.0Ex\Configuration\Packages\{223643a0-af7c-4741-99df-e9641691af50}]
@="MyCompany.EmptyPackage.EmptyPackagePackage, EmptyPackage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
"InprocServer32"="C:\\Windows\\system32\\mscoree.dll"
"Class"="MyCompany.EmptyPackage.EmptyPackagePackage"
"Assembly"="EmptyPackage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
[HKEY_CURRENT_USER\9.0Ex\Configuration\Packages\{223643a0-af7c-4741-99df-e9641691af50}]
"ID"=dword:00000001
"MinEdition"="Standard"
"ProductVersion"="1.0"
"ProductName"="EmptyPackage"
"CompanyName"="MyCompany"
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:
[InstalledProductRegistration(false, "#110", "#112", "1.0", IconResourceID = 400)]
[ProvideLoadKey("Standard", "1.0", "EmptyPackage", "MyCompany", 1)]
[Guid(GuidList.guidEmptyPackagePkgString)]
public sealed class EmptyPackagePackage : Package { ... }
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:
regpkg.exe /ranu /root:Software\Microsoft\VisualStudio\9.0Exp Ä
.\bin\Debug\EmptyPackage.dll
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:
regpkg.exe /unregister /ranu /root:Software\Microsoft\VisualStudio\9.0Exp Ä
.\bin\Debug\EmptyPackage.dll
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:
"%VSSDK90Install%\VisualStudioIntegration\Tools\Bin
egpkg.exe" /unregister /ranu /root:Software\Microsoft\VisualStudio\9.0Exp .\bin\Debug\<your .dll>
pause
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.
Posted
Jan 22 2008, 06:40 PM
by
inovak