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.
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.
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):
Warning
CheckPackageSignature failed; invalid Package Load Key
{YOUR PACKAGE GUID HERE}
Microsoft Visual Studio Appid Stub
2006/12/11 17:49:25.950
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}:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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