To support VSTA v 1 projects in VSTA v 2 you need to create and register an UpgradeHelper. This helper is triggered when a VSTA v 1 project is opened in the VSTA v 2 IDE. If VSTA v 1 is installed, VSTA v 1 projects will still open normally in the VSTA v 1 IDE when doubled clicked. Projects must be opened through the VSTA v 2 IDE to trigger the UpgradeHelper and once upgraded will open in the VSTA v 2 IDE when double clicked.
A couple of notes about using an UpgradeHelper:
1) You must use two unique HostID’s in order to use an UpgradeHelper. Using the same HostID for VSTA v 1 and VSTA v 2 will cause the UpgradeHelper not to be triggered. Related topic: How to Update a Host’s Folder in %My Documents%.
2) In the RemovedReferences section use only the name of the reference to removed- including any other information like the version or public key token will result in the reference not being removed.
3) Only valid projects will trigger the UpgradeHelper. Projects missing the AppAddIn.designer.cs file from the list of compilable files will not trigger the UpgradeHelper.
4) To be sure that the correct version of a reference is added, you may want to use the full GAC information for the reference since you cannot specify SpecificVersion=true. Related topic: Proxy Versioning Options for Project Templates. Example: "ShapeAppCSharpProxy, Version=2.0.0.0, Culture=neutral, PublicKeyToken=3c3c0c46dd27dbcf, processorArchitecture=MSIL"
5) VSTA v 1 projects cannot be opened programmatically through VSTA v 2. Using dte.Solution.AddFromFile or dte.Solution.Open will throw an error if the project has not been previously upgraded. We are looking for a workaround for this (add a comment if you know of one please).
The UpgradeHelper is triggered at the end of the normal Visual Studio conversion wizard.
The VSTA registries required for the UpgradeHelper are a little tricky- you may want to base yours off the included example
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHostConfig\ShapeAppCSharpV2\2.0]
@=""
"AppName"="ShapeAppCSharp"
"ProjectTemplatesLocation"="C:\\ShapeAppSamples\\ShapeAppMacroRecordingCSharp\\Templates"
"VSTAVersion"="9.0"
"UpgradeFrom"="ShapeAppCSharp"
"UpgradeHelper"="{10B201D5-F806-4385-8DED-7E785DD66946}"
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHostConfig\ShapeAppCSharpV2\2.0\VSTA]
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHostConfig\ShapeAppCSharpV2\2.0\VSTA\UpgradeHelper]
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHostConfig\ShapeAppCSharpV2\2.0\VSTA\UpgradeHelper\{10B201D5-F806-4385-8DED-7E785DD66946}]
"Assembly"="ShapeAppCSharp_UpgradeHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=27e4196f25ea49b1"
"Class"="ShapeAppCSharp_UpgradeHelper.ShapeAppCSharp_UpgradeHelper"
To use this sample:
1) Remove the ShapeAppCSharp folder from %MyDocuments%
2) Remove the ShapeAppCSharp registry hives from the config and context registry hives
3) Remove all ShapeAppCSharpProxies registered in the GAC
4) Open and build the ShapeAppAdvancedCSharp sample- this registers ShapeAppCSharpProxy Version = 1.0.0.0.
5) Run the setup file SetupShapeAppAdvancedCSharp.js (templates use proxy v 1)
6) Move the folders contained in the MyDocs folder to %MyDocuments%- this includes macro projects and sample add-in assemblies
7) Open and build the modified sample add-in for ShapeAppAdvancedCSharp (optional but you may want to see what the add-in does)
8) Run the ShapeAppAdvancedCSharp sample, launch the IDE and build the macro project to confirm the macro startup method runs.
9) Open and build the ShapeAppCSharp_UpgradeHelper. This will register the upgrade helper in the GAC, it will be registered with the host in step 11 below.
10) Open and build the ShapeAppMacroRecording sample- this registers ShapeAppCSharpProxy Version = 2.0.0.0.
11) Run the modified setup file SetupShapeAppMacroRecordingCSharp_v2.js. This uses the HostID ShapeAppCSharp_v2, registers the UpgradeHelper and registers templates which use proxy v 2.
12) The macro and sample add-in assembly should have been moved in step 6 above.
13) Open and build the modified sample add-in for ShapeAppMacroRecordingCSharp (optional but you may want to see what the add-in does)
14) Run the ShapeAppMacroRecordingCSharp sample,
a. launch the IDE (as normal for VSTA v 2) and build the macro project to confirm the macro startup method runs.
b. Launch the IDE for the VSTA v 1 macro project,
i. follow the prompts to navigate to the project and open it (C:\Documents and Settings\Administrator\My Documents\ShapeAppCSharp\Macros.sln)
ii. build the macro project to confirm the macro startup method runs.
The Code:
namespace ShapeAppCSharp_UpgradeHelper
{
public class ShapeAppCSharp_UpgradeHelper : IVstaUpgradeHelper
{
#region IVstaUpgradeHelper Members
List<AddedReference> IVstaUpgradeHelper.AddedReferences
{
get
{
//SUGGESTION: use the full GAC information for tight versioning
List<AddedReference> addedReferencesList = new List<AddedReference>();
addedReferencesList.Add(new AddedManagedReference("ShapeAppCSharpProxy, Version=2.0.0.0, Culture=neutral, PublicKeyToken=3c3c0c46dd27dbcf, processorArchitecture=MSIL"));
return addedReferencesList;
}
}
string IVstaUpgradeHelper.DebugInfoCommandLine
{
get{return ""; }
}
string IVstaUpgradeHelper.DebugInfoExeName
{
get { return "#HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\ShapeAppCSharp_v2\\InstallPath#\\ShapeAppCSharp.exe"; }
}
string IVstaUpgradeHelper.IconImageList
{
get{return ""; }
}
Guid IVstaUpgradeHelper.InProcessHostGuid
{
get
{
Guid newG = new Guid();
return newG;
}
}
List<RemovedReference> IVstaUpgradeHelper.RemovedReferences
{
get
{
//NOTE: use only the reference name, not the version or any other information
// or the reference will not be removed.
List<RemovedReference> removedReferencesList = new List<RemovedReference>();
removedReferencesList.Add(new RemovedReference("ShapeAppCSharpProxy"));
return removedReferencesList;
}
}
string IVstaUpgradeHelper.TemplatesPath
{
get {return ""; }
}
UpdatedBaseType IVstaUpgradeHelper.UpdateBaseType(string oldBaseType)
{
string newBaseType = null;
string newBaseInterfaceType = null;
if (oldBaseType == "Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.Application")
{
newBaseType = "Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.ApplicationEntryPoint";
newBaseInterfaceType = "Microsoft.VisualStudio.Tools.Applications.Runtime.IEntryPoint";
}
return new UpdatedBaseType(newBaseType, newBaseInterfaceType);
}
#endregion
}
}