Migrating VSPackages to Visual Studio 2008

  • Article

VSPackages that you developed by using Visual Studio 2005 SDK in either native or managed code will run in Visual Studio 2008 without recompilation. However, you can take advantage of new Visual Studio 2008 features by adding them to your VSPackages and then recompiling the source code in Visual Studio 2008.

You can use the same package load key (PLK) in both environments.

Binary Compatibility

In general, Visual Studio packages are backward-compatible with earlier versions. Most VSPackages that work in Visual Studio 2005 will continue to work in Visual Studio 2008 without modification. Most services, entry points, and events maintain compatibility, but there are some exceptions, which are listed later in this topic. Programmatic interfaces also maintain compatibility generally, but elements of some interfaces may change and require source code modification to work with Visual Studio 2008.

In particular, the version number of the Microsoft.VisualStudio.Shell.Design.dll assembly has been changed to 9.0 for Visual Studio 2008. Most packages that have been compiled against the earlier version of this assembly will continue to work correctly because a "binding redirect" in Visual Studio 2008 forces managed binaries to use the later version of the assembly. However, if your package uses (or has a class that inherits from) one of the types in the following list, it must be recompiled against Visual Studio 2008 before it can run correctly.

The following kinds of code must be recompiled by using the Visual Studio 2008 versions of Microsoft.VisualStudio.Shell.Design and Microsoft.VisualStudio.Shell:

Forward Compatibility

In general, forward compatibility is not supported by Visual Studio. A VSPackage is forward-compatible if it was written for a specific version of Visual Studio and can be used in an earlier version of Visual Studio without modification. 

Registration

A VSPackage built for an earlier version of Visual Studio must be registered correctly in the system registry to work in Visual Studio 2008. The Visual Studio 2008 registry hive is

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\.

Any registration that is related to an earlier version of Visual Studio must be updated to use the Visual Studio 2008 registry hive. This can be accomplished by modifying the existing .msi file that is used to install the VSPackage, or by creating a new .msi file. Modifying an existing .msi file typically just involves replacing instances of

"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\" with "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\".

Package Load Keys

PLKs issued for earlier versions of Visual Studio are honored in Visual Studio 2008. Any PLK-related information in the registry must remain unchanged from installation to installation so that the PLK can be validated and your VSPackage can load. If you want to update your VSPackage version information in the registry or modify any other registry information about your VSPackage, then you must obtain a new PLK. (A new PLK is not required when you are just re-registering the same VSPackage in the new Visual Studio 2008 registry hive, as described in the Registration section of this topic.)

CTC and VSCT Command Files

In the Visual Studio 2008 SDK, every integration sample uses a .vsct file to describe the commands that are provided and consumed by the sample VSPackage. The .vsct files replace the .ctc files that were used in earlier versions of Visual Studio. The .vsct files are easier to create and maintain because IntelliSense and schema validation are enabled for them in the Visual Studio code editor.

Visual Studio 2008 and the Visual Studio 2008 SDK still support .ctc files because both .ctc files and .vsct files are compiled into the same underlying object format. Therefore, although we recommend that you use .vsct files, you can continue to use .ctc files.

For more information, see Visual Studio Command Table (.Vsct) Files.

Native Packages

VSPackages written in native code can handle differences between versions of Visual Studio by using the IServiceProvider that is provided in the SetSite method. Services can be queried from IServiceProvider. If those services are unavailable from the service provider, then a NULL interface value is returned. All VSPackage code should be written to handle an unavailable service, as shown in the following example.

// Query for the global service
CComPtr<IGlobalService> spIGlobalService;
HRESULT hr = 
    GetVsSiteCache().QueryCachedService<
        IGlobalService, 
        __uuidof(SGlobalService)>(&spIGlobalService);

if (spIGlobalService && !FAILED(hr))
{
    // IGlobalService is available
    hr = spIGlobalService->ExecuteGlobalService();
    if (SUCCEEDED(hr))
    {
        // IGlobalService is behaving as expected
        …
        return;
    }
}

// IGlobalService is not available or is not behaving as expected
// Handle this by degrading this VSPackage’s functionality 
// and logging the failure or informing the user

Managed Packages

VSPackages written in managed code behave differently than native VSPackages because of the loading characteristics of the common language runtime (CLR). When a managed library is loaded by the CLR, the CLR ensures that all types referenced by the DLL are also loaded in the process. For instance, if IGlobalService is referenced by your managed VSPackage, but that type is not loaded or is not available in any one of your referenced assemblies, then the CLR may not load your VSPackage. If the process that is loading a type is running under a debugger, then a TypeLoadException may be seen. Also, you can run the Fusion Log Viewer (fuslogvw.exe) to view the CLR log that is associated with the loading failure. Fusion Log Viewer is included with the .NET Framework.

You cannot use the same kind of coding in your managed VSPackage as you might have used in your native VSPackage because the loader will not even load such code if the types cannot be loaded in the process. VSPackages that reference types from one version of Visual Studio (for example, Visual Studio 2005) that are not available in another version of Visual Studio (for example, Visual Studio 2008) may not load. The only way to avoid this situation is to ensure that all types in all referenced assemblies are available in the Visual Studio version that is targeted by the VSPackage.

If the required types and assemblies are not included in Visual Studio, then you must redistribute them. You should ensure that such assemblies are redistributable according to the license agreement for Visual Studio, Visual Studio SDK, or other source. Just reshipping raw binaries is typically not allowed under license agreements. Such binaries should be explicitly listed in the license, or in a file list on the disk. The binaries should be installed by using a correct .msi file or a self-extracting executable that contains a correct .msi file so that the original author of the binary can update it.

Interop Assemblies

Managed-code VSPackages that directly reference the Visual Studio interop assemblies should work on a newer version of Visual Studio without recompilation, because each version of Visual Studio includes the interop assemblies from earlier versions together with new interop assemblies.

Forward Compatibility

If your VSPackage is written for a newer version of Visual Studio and you want it to work in an earlier version, then you must address two issues. First, all assemblies referenced by your VSPackage must be recognizable by the earlier version or they will not load. For interop assemblies, this means that you should only target assemblies that are included in both Visual Studio versions unless you intend to install assemblies from the newer version into the earlier version.

For example, imagine that you have a VSPackage that references the Visual Studio 2005 interop assemblies in Microsoft.VisualStudio.Shell.Interop.8.0.dll. You want the VSPackage to work in Visual Studio 2003, but Microsoft.VisualStudio.Shell.Interop.8.0.dll is not available on computers that only have Visual Studio 2003. To work on such a computer, your VSPackage must install Microsoft.VisualStudio.Shell.Interop.8.0.dll on that computer. To accomplish this, you can use vs_piaredist.exe, which is a redistributable file that installs the Visual Studio 2005 interop assemblies and is included in Visual Studio 2005. (By default, vs_piaredist.exe is installed in Visual Studio installation path\Common Files\Merge Modules\.). A similar redistributable, vs90_piaredist.exe, is available in Visual Studio 2008.

You must develop such a VSPackage carefully because the services, interfaces, events, and functionality that are available in the newer Visual Studio version may not be available in the earlier version. By considering this when you develop your VSPackage, you can ensure that its functionality will decrease gracefully when it is installed on the earlier version of Visual Studio.

Notice that for every additional assembly that is not available on the computer that has the earlier version of Visual Studio, this situation is compounded.

Managed Package Framework Binaries

The Managed Package Framework (MPF) that was included in Visual Studio 2005 has three main components. Two of these components are binary files named Microsoft.VisualStudio.Shell.dll and Microsoft.VisualStudio.Package.LanguageService.dll. Both are included in Visual Studio 2008. Therefore, VSPackages that depend on them will work in Visual Studio 2008.

The third component was included in the Visual Studio 2005 SDK and is a set of base classes that are named the Managed Package Framework Project System base classes. These sources, when they are included in a VSPackage project, get compiled into the VSPackage binary. The functionality that is contained in them is intended to function fully in Visual Studio 2008.

MPF Shell and Language Service

Visual Studio 2008 and the Visual Studio 2008 SDK include new versions of the MPF components. The new binaries are Microsoft.VisualStudio.Shell.9.0.dll and Microsoft.VisualStudio.Package.LanguageService.9.0.dll. They contain all the functionality of earlier versions, and also contain some new functionality and bug fixes. Although code that uses these new binaries must be recompiled, most of the time, no source changes are required.

Forward Compatibility

The Visual Studio 2008 MPF binaries do not work in Visual Studio 2005 and earlier Visual Studio versions. Nevertheless, the source for these binaries is included in the Visual Studio 2008 SDK. Therefore, you may be able to compile the source into binaries that reference Visual Studio 2005 APIs and thereby port the new MPF to the Visual Studio 2005 platform. This use of the Visual Studio 2008 MPF code has not been tested.

Managed Project System Base Classes from VS SDK

VSPackages that contain the MPF Project System base classes from the Visual Studio 2005 SDK will continue to work in Visual Studio 2008. VSPackages that are built by using the MPF Project System base classes from the Visual Studio 2008 SDK may work in earlier Visual Studio versions, but this use has not been tested.

ProjectAggregator

Included in Visual Studio 2005 is a component named ProjectAggregator. ProjectAggregator provides a native base class for managed code project systems that compensates for some limitations in the platform where managed code project systems may not work correctly. In the Visual Studio 2005 SDK a component called ProjectAggregator2 was introduced. It expanded the capabilities of ProjectAggregator. The MPF Project System base classes in the Visual Studio 2005 SDK rely on ProjectAggregator2. The Visual Studio 2005 SDK includes a redistributable ProjectAggregator2 MSI that VSPackage developers can install with their VSPackages.

Visual Studio 2008 includes an updated ProjectAggregator component that provides all the functionality of ProjectAggregator2, works with the Visual Studio 2008 MPF binaries (Microsoft.VisualStudio.Shell.9.0.dll, specifically), and improves side-by-side scenarios in future versions of Visual Studio.

VSPackages that have been built by using the Visual Studio 2005 SDK and that rely on ProjectAggregator2 should only install ProjectAggregator2 when they are being installed to work with Visual Studio 2005. ProjectAggregator2 should not be installed by VSPackages that are intended to work with Visual Studio 2008 because it already contains the updated ProjectAggregator.

Toolbox Controls Installer

The Toolbox Controls Installer is a VSPackage that was introduced in the Visual Studio 2005 SDK in February 2007, and is redistributable for Visual Studio 2005. Toolbox Controls Installer makes the installation and removal of Toolbox controls easier. In Visual Studio 2008, Toolbox Controls Installer is included. Therefore, the Visual Studio 2008 SDK does not include a redistributable for it. Nevertheless, usage in Visual Studio 2008 is the same as it was in Visual Studio 2005. For more information, see the sample, Example.InstallToolboxControls.

Testing

We recommend that you test your VSPackage to ensure that it is working correctly in any update to Visual Studio. The samples included in the Visual Studio 2008 SDK contain unit tests and scenario tests that are good examples of integration testing. Such tests should continue to run with little or no modification for Visual Studio 2008.

See Also

Concepts

Experimental Build

Support for Settings Migration

Other Resources

Getting Started with the Visual Studio Integration SDK

Change History

Date

History

Reason

July 2008

Added information about ProjectAggregator.

Information enhancement.