Migrating Add-in Projects

Article
11/16/2012

Add-ins that were created by using Visual Studio 2005 Tools for Applications will not run in the Microsoft Visual Studio Tools for Applications 2.0 environment without modification. You can migrate existing add-ins to the new environment in your implementation of the Visual Studio Tools for Applications integrated development environment (IDE). By adding code to migrate projects, you enable add-in developers to open their existing projects and compile them in the new environment without making extensive updates to their code (unless you have substantially changed the host application's object model).

Perform the following tasks to migrate the project:

Create an upgrade helper class.
Register the upgrade helper class.
Identify projects that need to be migrated in Visual Studio.

Creating an Upgrade Helper Class

The upgrade helper class contains properties and methods that add and remove assembly references in the add-in project file, change information that is passed to the Microsoft Visual Studio Tools for Applications 2.0 debugger, and specify other changes that make the add-in project compatible with the updated host application.

To create this class, implement the IVstaUpgradeHelper interface. The following table explains how to use each member of the IVstaUpgradeHelper interface to migrate add-in projects.

Member	Use this member to:
AddedReferences	Specify a list of managed assemblies that you want the add-in project to reference.
DebugInfoCommandLine	Specify parameters that you would like to pass to the Visual Studio Tools for Applications debug executable.
DebugInfoExeName	Specify the full path of the application to run when the debugging session starts.
IconImageList	Specify a path to an icon image list. The image list contains 16x16 pixel images to be associated with the host, host item, and open folder items in Solution Explorer.
InProcessHostGuid	Specify the GUID of a new in-process host that you would like to load when existing projects are opened. Note You can specify only a single GUID. Therefore, you can introduce only one in-process host as part of this interface implementation.
RemovedReferences	Specify a list of managed assemblies that you want to remove from the add-in project assembly references.
TemplatesPath	Specify a path to new Microsoft Visual Studio Tools for Applications 2.0 item templates.
UpdateBaseType	Update references to the base types and the base interface of the entry point in the proxy assembly. For more information, see Architecture of Generated Proxy Code.

The following example shows a class that implements the IVstaUpgradeHelper interface.

public class UpgradeHelper : IVstaUpgradeHelper
{
    public Guid InProcessHostGuid
    {
        get
        {
            return new Guid("{2626C5BC-F0CB-4f28-8B17-CA4200A4C0F7}");
        }
    }
    public List<AddedReference> AddedReferences
    {
        get
        {
            List<AddedReference> addedReferencesList = new List<AddedReference>();
            addedReferencesList.Add(new AddedManagedReference("Contoso_V2.Proxy.Fulltrust"));
            addedReferencesList.Add(new AddedManagedReference("Contoso_V2.Interop"));
            return addedReferencesList;
        }
    }
    public List<RemovedReference> RemovedReferences
    {
        get
        {
            List<RemovedReference> removedReferencesList = new List<RemovedReference>();
            removedReferencesList.Add(new RemovedReference("Contoso.Proxy.Fulltrust"));
            removedReferencesList.Add(new RemovedReference("Contoso.Interop"));
            return removedReferencesList;
        }
    }

    public UpdatedBaseType UpdateBaseType(string oldBaseType)
    {
        string newBaseType = null;
        string newBaseInterfaceType = null;
        if (oldBaseType == "Contoso_V2.HostItemBase.Application")
        {
            newBaseType = "Microsoft.Contoso_V2.Proxies.ApplicationEntryPoint";
            newBaseInterfaceType = "Microsoft.VisualStudio.Tools.Applications.Runtime.IEntryPoint";
        }
        return new UpdatedBaseType(newBaseType, newBaseInterfaceType);
    }
    public string TemplatesPath
    {
        get
        {
            return "AppNetWizards\\AppNetProjectWizard\\Templates";
        }
    }
    public string DebugInfoExeName
    {
        get
        {
            return "#HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Contoso_V2\\InstallPath#\\ShapeAppV2.exe";
        }
    }
    public string DebugInfoCommandLine
    {
        get
        {
            return "/ondisk:&quot;[$OUTPUT][$ASSEMBLY]&quot;";
        }
    }
    public string IconImageList
    {
        get
        {
            return "#HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Contoso_V2\\InstallPath#\\Contoso_V2.exe#125";
        }
    }
}

Installing the Upgrade Helper Assembly into the Global Assembly Cache

After you compile the class library project that contains the upgrade helper class, deploy the resulting assembly to the global assembly cache.

You must sign the assembly with a strong name before you can add it to the global assembly cache.

For more information about how to install an assembly in the global assembly cache, see How to: Install an Assembly into the Global Assembly Cache.

Registering the Upgrade Helper Class

Register the upgrade helper class so that it can be identified by the Visual Studio Tools for Applications project system. Perform the following tasks to register the upgrade helper class:

Add a registry key that identifies the upgrade helper assembly.
Add a registry entry that points to the registry key.

After you complete these tasks, run vsta.exe using the /hostid and /setup switches. For more information, see How to: Register the Host Application.

Adding a Registry Key That Identifies the Upgrade Helper Assembly

Add the following key to the registry to identify an upgrade helper assembly:

On 32-bit platforms:

HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\hostID\2.0\VSTA\UpgradeHelper\GUID
On 64-bit platforms:

HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\VSTAHostConfig\hostID\VSTA\UpgradeHelper\GUID

The hostID key identifies your host application. The GUID key identifies the upgrade helper class. You can generate a GUID by using a GUID generation tool called Guidgen.exe, which is located in the directory %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\Tools.

The following table shows the two entries to add this new key.

Entry	Type	Value Description
Assembly	Reg_SZ	A comma-separated value list that contains the assembly name, version, culture, and public key token. To obtain this information, open a Command Prompt window and change directories to the location of gacutil.exe. Then, type gacutil /l assemblyName where assemblyName is the name of the assembly excluding the .dll extension.
Class	Reg_SZ	The class name of the upgrade helper class qualified by its namespace.

Adding a Registry Entry That Points to the Registry Key

Under the hostID/2.0 subkey, add an entry of the type REG_SZ and name it UpgradeHelper, as shown in the following examples:

On 32-bit platforms:

HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\hostID\2.0\UpgradeHelper
On 64-bit platforms:

HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\VSTAHostConfig\hostID\2.0\UpgradeHelper

Set the value of this entry to the GUID that you used to identify the upgrade helper assembly.

Identifying Projects for Migration in Visual Studio

Add an entry to the registry to indicate that the host application has been updated to support Microsoft Visual Studio Tools for Applications 2.0. Name this entry UpgradeFrom. This entry causes Visual Studio 2008 to migrate the project so that it can run against an updated host application.

Under the hostID/2.0 subkey, add an entry of the type REG_SZ as follows:

On 32-bit platforms:

HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\hostID\2.0\UpgradeFrom
On 64-bit platforms:

HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\VSTAHostConfig\hostID\2.0\UpgradeFrom

Set the value of this entry to the host ID of the previous version of the host application.

Share via