A .pkgdef file is way to encapsulate application configuration information in an easily editable, distributable, and deployable form. It was introduced in Visual Studio 2008 SP1 to support the configuration of Isolated Shell applications. In Visual Studio 2010, .pkgdef files take on a more expanded role and are much more integrated into both the IDE and the Shell (Integrated and Isolated). This article will briefly describe the .pkgdef format and introduce the scenarios where it is used in VS 2010. Future posts will go into more detail about particular scenarios.

Here is a portion of a .pkgdef file that registers the Extension Manager (which is written as a VS Package) with the IDE:

It looks a lot like a .reg file as exported from the Registry Editor. There is one key difference: the root of the registry key (e.g., “HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\10.0”) has been abstracted into the token “$RootKey$”. This, and several other tokenized values for registry keys and paths, allows a given .pkgdef file to be reusable for multiple applications and portable to any machine.

This example also demonstrates why this format was originally called a “pkgdef”. A .pkgdef file can be used to define the registration of a package. Now that this format is used for many other registration and configuration tasks, there was some talk of changing the name and extension to something more generic. We decided that the pkgdef appellation was just as good as anything else. Like most computer terminology, the first name seems to have stuck.

Let’s go back and look at that first application of the .pkgdef file to configure Isolated Shell applications in VS 2008 and see what it involved. An Isolated Shell application reads its configuration data from at least four .pkgdef files.

Notice that that configuration and registration information originates from both the application developer and Microsoft. All of these values have to be merged into a common location specific to the application so that the Shell and the Packages in the application can retrieve them. In VS 2008, this was done during installation of the Isolated Shell application by running the application executable with the “/setup” switch (as a setup Custom Action). This caused the Shell to read all of the .pkgdef files and build a new configuration hive for the application in the registry under HKEY_LOCAL_MACHINE. During the development and test cycle of an Isolated Shell application, the “/ranu” (“run as normal user”) switch was used to create a test hive under HKEY_CURRENT_USER, in order to avoid issues with having Administrator access to the registry.

Visual Studio 2010 makes the .pkgdef load and merge operation a normal part of initialization sequence for both the Shell and the IDE. It also locates the target of the merge, known as the config (or configuration) cache, under HKEY_CURRENT_USER (next to the user settings for the application, but with a “_Config” suffix). This eliminates the need to run the merge as part of setup and eliminates the need for the “/ranu” switch during testing. It also enables an additional scenario: the Extension Manager.

The Extension Manager feature allows users to download extensions to the Visual Studio IDE and integrate them without having to run setup. Extensions that are written as VS Packages that must register with the IDE do so using a .pkgdef file. Simply restarting the IDE after the extension is installed (by unzipping its VSIX file) and enabled causes the IDE to build a merged registry hive out of the values that were written to HKEY_LOCAL_MACHINE during Visual Studio setup and the values in .pkgdef files found on disk. The user is not required to take any extra steps or have Administrator privileges.

You may notice that in the case of the Isolated Shell application all of the configuration values come from .pkgdef files. But in the case of the Visual Studio IDE some of the values come from HKEY_LOCAL_MACHINE. In the latter case, VS continues to use the HKLM hive in order to support some compatibility and servicing scenarios. But we plan to continue moving more configuration values out of the registry as we are able.

The .pkgdef file was introduced in VS 2008 to allow a more modular way to deploy configuration values for the Visual Studio Shells. Improvements in .pkgdef file loading and merging in VS 2010 have made the use of .pkgdef files more automatic and enabled the setup-less installation of Visual Studio extensions.

In future posts, I plan to describe in more detail how and when VS decides to refresh the config cache, why a .pkgdef file might not be loaded and how to debug that, and the purposes of the various .pkgdef files. In the meantime, Aaron Marten and Dmitry Goncharenko have already written several excellent related posts, some of which I have already referenced above:

• Pkgdef and the Experimental Instance in VS 2010
• All Your RegKeys Are Belong To Us
• Bootstrapping of VS packages and VSIX extensions in VS2010

You may also want to read an Introduction to the Visual Studio Shell or view a recent Presentation about the Shell in VS 2010.

Bill Weinberger: Developer, Visual Studio Platform

Bill is a relative newcomer to Microsoft, but has many years of software industry experience working on IDEs and vertical applications. For Visual Studio 2010, he was a key contributor to PkgDef Management.