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.

• WindowPaneProviderService

• DesignSurfaceExtensionAttribute

• ProvideDesignerMetadataAttribute

• ProvideDesignerOptionsAttribute

• ProvideGlobalObjectProviderAttribute

• ProvideViewAdapterAttribute

• ProvideDesignerLoaderAttribute

• ProvideGeneratorAttribute

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

• Code that calls into WindowPaneProviderService to create a DesignerWindowPane (or a class derived from it). If you try to cast the return value to a Visual Studio 2008 version of WindowPane, the code will fail. Also, if you try to implement a custom WindowPaneProviderService, the code will fail.

• Types that have a ProvideGlobalObjectProviderAttribute (or any one of the other attributes) and you use Regpkg.exe to install your package in the Visual Studio registry hive.

Forward Compatibility

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\”.

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.)

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.

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

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.

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

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.

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

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.

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.

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.

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.

Concepts

Other Resources