Debugging Package Load Failures

You can just picture the situation. You've coded up your package and tested it out on your development machine. You've even managed to get a setup project together. Everything is working just as expected, but when you run your setup on another machine, you get a dialog like this:

Never fear, Dr. eX is here to cure what ails you! There are several possible causes for a package load failure.

Invalid/Missing Package Load Key

Perhaps the number one cause of failure when deploying a new package is an invalid or missing package load key. In order to deploy your package on an end-user's machine, you'll need to embed a package load key as a string resource.

How to diagnose a PLK issue

To find out if your package is failing to load because of a problem with the PLK, you can use the /log switch included in Visual Studio 2005. If there is a failure because of a PLK problem, you will see something like the following in the VS activity log (located at {USERPROFILE}\{AppData}\Microsoft\VisualStudio\{Hive}\ActivityLog.xml):

You should note that even if you do have a valid PLK, you may still see this warning once or more in the log. This is because Visual Studio attempts to check if your PLK is valid for different versions of Visual Studio. For example, even if you applied for a PLK to load in Visual Studio 2005, at runtime Visual Studio will check if you have a valid key for Visual Studio 2002, 2003, or 2005. Since the key isn't a valid 2002 key (even though it is valid for 2005), a warning is logged. This check is done to ensure that packages created for earlier versions of Visual Studio continue to load in later versions.

A PLK is a signed hash of the following registration information taken from your package registration key at HKLM\Software\Microsoft\VisualStudio\8.0\Packages\{YOURGUID}:

• CompanyName (This is entered when first creating your login on the VSIPMembers.com site. You can find the exact string on the list of Products registered there.)
• ProductName (This is entered when first creating the product information, not when requesting the PLK)
• ProductVersion
• MinEdition (Standard, Professional, etc...)
• Your Package Guid
• The "appid" that your PLK is for (i.e. the version of Visual Studio)

Because the PLK is a signed hash of this information, if you need to change any of these details about the package, you must obtain a new Package Load Key from the VSIP members website. If for some reason, you don't get the email with the PLK from the website, you can resubmit for a new PLK, try out asking on the Visual Studio Extensibility forum, or contact Microsoft Product Support.

To find out more details about how package load keys work and how to properly embed a PLK in your package DLL, check out the topic about them on MSDN.

How to remedy a PLK issue

In the above MSDN topic, there is a link to another excellent article which contains more detailed information on Troubleshooting a Package Load Failure caused by a PLK problem.

Exception in Constructor/SetSite/Initialize Methods

If you've determined that the PLK check is succeeding (or you aren't to the deployment stage yet), but your package is not loading, it is possible that your package is throwing an exception in its constructor or SetSite/Initialize method. At package load time, an object of your package type is instantiated and the constructor is executed. Then, in order to site the package to the hosting instance of Visual Studio, the SetSite method is called. If you are deriving from the Package class in the Managed Package Framework (which most packages written in C# do), you will not see a SetSite implementation in your code. Rather, the MPF implementation of SetSite will call the Initialize method, which you can override.

How to diagnose an exception in the constructor or SetSite method

The simplest way to determine this problem is by setting breakpoints in the constructor and SetSite and/or Initialize method and stepping through your execution path with the debugger. If any exceptions are thrown (or error codes returned), Visual Studio will fail to continue the package loading process.

How to remedy an exception in the constructor or SetSite method

Remedying an exception is, of course, a case-by-case task. You will need to determine the proper fix for your package to prevent the exception from being thrown to Visual Studio if it is a recoverable, non-fatal error situation.

Dependency Load Failure

Even though your package DLL may be loading just fine, that doesn't mean that all the dependencies in your package are loading! For example, if your package references a binary on your development machine that is not properly redistributed on an end user's machine, you may get a package load failure.

How to diagnose a Dependency Load Failure

For managed packages, the simplest way to diagnose such a problem is via the Assembly Binding Log Viewer tool (fuslogvw.exe) included with the .NET Framework SDK. The MSIL Dissassembler (ildasm.exe) may also be helpful in determining the exact assemblies that your package depends on.

For native packages, things are a bit trickier, but not hopeless. Dr. eX recommends using the profiling feature in the Dependency Walker tool (depends.exe) on devenv.exe (Visual Studio's executable). This will give you detailed information about where Visual Studio is loading binaries from. If Visual Studio can't find your package binary, it will be logged during the profiling. Filemon may also be helpful as it allows you to see real-time file system activity. Dumpbin.exe (using the /DEPENDENTS switch) may also provide some clues.

How to remedy a Dependency Load Failure

In most cases, the problem is caused by not properly redistributing a binary on which your package relies. The remedy is to obtain permissions and needed resources from the author of the dependent binaries and include these in your package's setup. In the case that you can't obtain such permissions (for legal or technical reasons), your only solution may be to remove the dependency.

For managed assemblies, you will need to ensure that your dependencies are located in the Global Assembly Cache (GAC) or the probing path for Visual Studio. The probing path is determined by the devenv.exe.config file and includes the PublicAssemblies and PrivateAssemblies folders. The Assembly Binding Log Viewer (mentioned above) will log the details of the probing algorithm so you can see where Visual Studio attempted to load the assembly from.

Registration Problem (Assembly/Codebase/InProcServer32)

There are a few different ways to register your package such that Visual Studio knows where to load it from. If you're package is managed, your key in the registry under Packages will have either a value for Assembly (containing the complete strong name of the assembly) or Codebase (containing a file path to your assembly) as well as a InProcServer32 value pointing to mscoree.dll (the .NET Runtime). If you're package is native, the InProcServer32 value should point to the location of your DLL on disk.

How to diagnose a Registration Problem

In order to diagnose this issue, you will need to compare the registration values to where files are actually located on disk. For a managed package, the Assembly Binding Log Viewer (fuslogvw.exe) tool mentioned earlier will also be helpful as it will contain information on where Visual Studio attempted to load your package from.

How to remedy a Registration Problem

Because this is caused by improper registration, you will need to adjust your setup program to register appropriately. See the MSDN help topic on deploying VSPackages for more information.

ProjectAggregator2 Not Installed

When you install the Visual Studio 2005 SDK on your machine, a component called ProjectAggregator2 is also installed silently. This component is used for packages which implement a project system in managed code. If you are writing a managed project system (or project subtype), you will need to redistribute ProjectAggregator2.msi as a part of your setup program.

How to diagnose ProjectAggregator2 Not Installed

During the package setup, ProjectAggregator2.msi should be installed before the package itself is installed. On an end-user's machine, you can look in the Add/Remove Programs dialog in Windows and see if there is a listing for "Microsoft Visual Studio ProjectAggregator2". Note that you will not see this listed in Add/Remove Programs on a machine with the Visual Studio SDK installed.

How to remedy ProjectAggregator2 Not Installed

You will need to install ProjectAggregator2.msi before your package is installed as part of your setup program. This MSI package can be installed silently by calling msiexec.exe. Also note that since Windows Installer is a transaction-based technology, will need to have a "wrapper" setup program to invoke msiexec and install ProjectAggregator2.msi. Due to the design of Windows Installer, you cannot invoke a MSI installation from another MSI.

Take two DLLs, and call me in the morning...

If you've been diagnosed with a package that fails to load, hopefully one of the above remedies will get your package back on its feet. Remember, that as with most problems, an ounce of prevention is worth a pound of cure. The doctor recommends the following tips to avoid PackageLoadFailureitis:

• Apply for a package load key (and use it in testing) as early as you can in the development cycle. This will prevent last minute scrambles to apply for, wait for, embed, and test the package load key just before you ship your package.
• Know what binaries you depend on, and ensure you have legal permissions to ship them.
• Use reliable installer technologies for managing registration and installation of your package. The Visual Studio 2005 SDK includes several samples that demonstrate the use of one such technology, Windows Installer (via WiX).
• Follow other Visual Studio Package deployment guidance as prescribed in the documentation.

As a final note, a couple of my colleagues and I in the research lab are working on a tool which will do much of the diagnosis of package load failures mentioned in this article automatically for you! We're tentatively calling it the "Package Load Analyzer" and it should be coming to a release of the Visual Studio SDK soon. It will be a deployable tool that you can use not only in development, but also for debugging purposes on test and end-user systems to help you make your package more reliable and robust.

Regards,
Dr. eX