Migrating Add-in Projects

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.

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.

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.

See Also

Concepts

Updating a Host Application to Support Visual Studio Tools for Applications 2.0

Upgrading to Visual Studio Tools for Applications 2.0