Summit Software

UpgradeHelper Sample Now Available

Melody — Thu, 04 Dec 2008 19:52:00 GMT

A new sample "UpgradeHelper Sample" is available showing how to register and use an UpgradeHelper.

Excerpt:

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

6) The UpgradeHelper is triggered at the end of the normal Visual Studio conversion wizard.

7) The VSTA registries required for the UpgradeHelper are a little tricky- you may want to base yours off the included example

New Sample Available: Two Applications Share a HostID Sample

Melody — Tue, 18 Nov 2008 21:31:00 GMT

I posted a new sample today which goes with my previous blog. This sample demonstrates many of the host Application, hostID, proxy and entry point combiniations outlined in the Application, HostID, Proxy, and EntryPoint Associations blog. If there is another combination you are interested in or if you have any questions on the sample, please leave a comment.

Excerpt from the Two Applications Share a HostID Sample:

This sample demonstrates how two applications can share one host ID.

There are two applications which share a common base type library: Applicatoin_A and Application_B share the SharedLib library. Application_B is based on Application_A with additional methods.

Each application has its own entry point type, Applicatoin_A .ApplicationA and Applicatoin_B.ApplicationB, and the shared base type library has an entry point type SharedLib.SharedApplication. Both applications have a HostItemProvider which can return the entry point for its application or the SharedLib.SharedApplication.

Application_A can load and run add-ins written for the entry points ApplicationA and SharedApplication, but not ApplicationB add-ins.

Application_B can load and run add-ins written for the entry points ApplicationB and SharedApplication, but not Application_A add-ins.

Application_A and Application_B can both debug at the same time (using different macro projects) using the same HostID. Application_A uses a macro project based on the ApplicationA_Template. Application_B uses a macro project based on the ApplicationB_Template.

Results:

It is possible to use the same hostID for different applications and debug them concurrently
It is possible for an application to load and run add-ins, so long as the add-in is compatible with the host (the HostItemProvider must return the entry point type of the add-in).

Application, HostID, Proxy, and EntryPoint Associations

Melody — Mon, 17 Nov 2008 21:54:00 GMT

There are a variety of configurations possible between host applications, hostID's, proxies, and entry points. Which configuration to use is a design decision which requires careful consideration, especially if you are deploying multiple applications bundled together or one application targeted at different user groups. Below are some possible configurations to consider.

Scenario 1) 1 Host Application, 1 HostID, 1 Proxy, 1 Entry Point:
This is the simplest and most straight forward scenario. The host application loads add-ins which are all written against the same proxy using the same entry point. The HostItemProvider for this scenario is very simple because there is only one type to return. The add-ins are created based templates using the same hostID, proxy, and entry point. Multiple templates using the same entry point may be used, for example one template could be the "bare bones" variety generated by ProjectGen and another could be more robust including events already hooked up.

Scenario 2) 1 Host Application, 1 HostID, 1 Proxy, Multiple Entry Points:
This setup builds on the first scenario but offers templates using different entry points, for example Application level and Document level templates. The host loads the add-ins using a more complex HostItemProvider to determine which entry point type to return to the add-ins. The add-ins are created based on templates using the same HostID and proxy, but different templates and entry points. Each entry point must have at least one template to be used by add-ins.

Scenario 3) 1 Host Application, 1 HostID, Multiple Proxies, 1 Entry Point:
This setup is similar to the second scenario but offers templates using different proxies, for example a SimpleOM proxy for basic users and a FullOM proxy for power users. The HostItemProvider for this scenario is very simple because there is only one type to return; the difference in the object model exposed is in the proxy and does not affect the HostItemProvider. The add-ins are created based on templates using the same hostId and entry point, but different templates and proxies. Each proxy must have at least one template to be used by add-ins.

Scenario 4) 1 Host Application, 1 HostID, Multiple Proxies, Multiple Entry Points:
This is a somewhat complex setup which offers both different proxies and different entry points which can be used to make a variety of templates, for example a SimpleApplication and AdvancedApplication as well as SimpleDocument and AdvancedDocument templates (SimpleApplication would have "this" or "me" as an Application object and expose only a few parts of the object model, while the AdvancedDocument would have "this" or "me" as an Document object and expose a robust view of the object model). The host application loads the add-ins written against different proxies and entry points. The HostItemProvider would determine which entry point type to return based on the entry point type of the add-in, for example Application or Document, but not Simple or Advanced; therefore, the SimpleApplication and AdvancedApplication add-ins would be handled the same way by the HostItemProvider. The add-ins are created based on templates using the same hostId but different templates using entry points / proxy combination. Each entry point/proxy combination would need its own template to be used by add-ins.

Scenario 5) 1 Host Application, Multiple HostID, 1 Proxy, 1 Entry Point:
This setup is very similar to the first scenario, but uses different hostIDs. Each hostID has its own templates which could be very similar, for example having the hostID as the only difference. The host application loads add-ins which are all written against the same proxy using the same entry point but multiple hostIDs. The HostItemProvider for this scenario is very simple because there is only one type to return. Add-ins are loaded based on entry point types, not hostIDs, so it is possible for one application to load add-ins based on templates registered under different hostIDs so long as the entry point type for the add-in can be resolved in the HostItemProvider. The add-ins are created based templates using the same proxy and entry point, but the templates are registered under different hostID's.

IDE and template considerations for this scenario- Each hostID should use a different ProjectTemplatesLocations because the VSTA IDE is HostID specific; therefore, projects for HostID_A cannot be opened in the IDE for HostID_B. Also, a host application can only register as a debug host for one hostID at a time; multiple IDE's for different HostIDs cannot be displayed or managed by the same application concurrently.

Scenario 6) 1 Host Application, Multiple HostID, Multiple Proxies, Multiple Entry Point:
This complex setup is very similar to the fifth scenario, but using different multiple proxies and entry points like the fourth scenario. Each hostID has its own templates which could be very similar, for example having the hostID as the only difference, or very different, for example using different proxies and entry point combinations. The host application loads add-ins written against different proxies and entry points based on templates registered under different hostIDs. The HostItemProvider would determine which entry point type to return based on the entry point type of the add-in. Add-ins are loaded based on entry point types, not hostIDs, so it is possible for one application to load add-ins based on templates registered under different hostIDs so long as the entry point type for the add-in can be resolved in the HostItemProvider. The add-ins are created based templates using different proxy / entry point combinations and registered under different hostIDs.

Error when a project based on a different hostID is opened in ShapeAppCSharp's IDE:

Scenario 7) Multiple Host Applications, 1 HostID, 1 Proxy, 1 Entry Point:
This is a simple scenario which can be used by applications which share base types, including the base type which will be an entry point type (for example two applications which use the same Document type as the entry point). The host applications load add-ins which are all written against the same proxy using the same entry point. The HostItemProvider for this scenario is very simple because there is only one type to return. The add-ins are created based templates using the same hostID, proxy, and entry point. Multiple templates using the same entry point may be used, for example one template could be the "bare bones" variety generated by ProjectGen and another could be more robust including events already hooked up.

IDE and template considerations for this scenario- Multiple applications can concurrently display, manage, and debug IDE's for the same hostID (ex: run two instances of the ShapeAppMacroRecordingCSharp sample at the same time). Therefore, applications can share a hostID without "locking" the other application out of debugging.

Because both applications use the same HostID, they will share the same IDE and registry settings like ProjectTemplatesLocation, AppName, and UserFilesFolderName. Therefore, the IDE cannot be customized through the default settings file to be different for each host application. Also, all templates for the hostID will appear as choices in the IDE. It is possible to refine this by storing the templates in subfolders under the ProjectTemplatesLocation. For example the ProjectTemplatesLocation could be C:\MyApp\Templates with the sub folders VisualBasic and CSharp, and within these folders the template could be divided in folders like C:\MyApp\Templates\{VisualBasic, CSharp}\{App_A, App_B}; the templates would appear as choices under the sub folders.

Project template storage and new project pane for templates stored as described above:

Monitoring and Controlling the IDE- Catching the File.Exit and other events

Melody — Thu, 13 Nov 2008 20:35:00 GMT

You may wish to monitor a user’s actions in the IDE and respond to or cancel them. I found a great article and sample which shows how to catch any and all events. One common request that this could be used to address is responding to the user exiting out of the IDE.

When the IDE is launched from the host, exiting the IDE really hides it instead of closing it, leaving the vsta.exe process running, and the user is not prompted to save changes. Below is some code added to the ShapeAppMacroRecordingCSharp sample which catches the File.Exit event, prompts the user to save the project, and quits the IDE bringing down the vsta.exe process. An additional method is also included which catches all events, this is very useful for determining the GUID and ID of a specific event you are interested in.

This workaround is based on an article by Carlos J. Quintero, HOWTO: Capturing commands events from Visual Studio .NET add-ins and a sample from CodeProject, Add-in to attach ASP.NET debugger.

private void EnsureIDE()
{ /*unchanged code omitted*/

//get and subscribe to all events prior to execution
EnvDTE.CommandEvents commandEvents = dte.Events.get_CommandEvents("{00000000-0000-0000-0000-000000000000}", 0);

commandEvents.BeforeExecute += new EnvDTE._dispCommandEvents_BeforeExecuteEventHandler(commandEvents_BeforeExecute);

//get and subscribe to the File.Exit event prior to execution
EnvDTE.CommandEvents exitCommand = dte.Events.get_CommandEvents("{5EFC7975-14BC-11CF-9B2B-00AA00573819}", 229);

exitCommand.BeforeExecute += new EnvDTE._dispCommandEvents_BeforeExecuteEventHandler(exitCommand_BeforeExecute);
}

void exitCommand_BeforeExecute(string Guid, int ID, object CustomIn, object CustomOut, ref bool CancelDefault)
{
   //Project.IsDirty is always false, so use .Saved which starts true
   if (this.macroProject.Saved == true)
   {
      //prompt the user to save the project
      DialogResult answer = MessageBox.Show("Do you want to save changes to " + this.macroProject.Name + "?", "ShapeAppCSharp", MessageBoxButtons.YesNo);

      if (answer == DialogResult.Yes)
      {
         this.macroProject.Save(null);
      }

     //change the saved state
      this.macroProject.Saved = false;
   }

//quit the IDE
this.dte.Quit();
}

void commandEvents_BeforeExecute(string Guid, int ID, object CustomIn, object CustomOut, ref bool CancelDefault)
{
EnvDTE.Command objCommand = default(EnvDTE.Command);
string sCommandName = null;

//break here to check out any commands you are interested in
objCommand = dte.Commands.Item(Guid, ID);

   if ((objCommand != null))
   {
      sCommandName = objCommand.Name;

      if (sCommandName.Equals("Something.WorthWatching"))
      {
         //do something
      }
   }
}

Visual Basic:

AddHandler Me.mDTE.Events.CommandEvents("{5EFC7975-14BC-11CF-9B2B-00AA00573819}", 229).BeforeExecute, AddressOf exitCommand_BeforeExecute

Private Sub exitCommand_BeforeExecute(ByVal Guid As String, ByVal ID As Integer, ByVal CustomIn As Object, ByVal CustomOut As Object, ByRef CancelDefault As Boolean)

'Project.IsDirty is alwyas false, so use .Saved which starts true

If Me.macroProject.Saved Then

'prompt the user to save the project

Dim answer As System.Windows.Forms.DialogResult = System.Windows.Forms.MessageBox.Show("Do you want to save changes to " + Me.macroProject.Name + "?", HostId, System.Windows.Forms.MessageBoxButtons.YesNo)

If answer = System.Windows.Forms.DialogResult.Yes Then

Me.macroProject.Save(Nothing)

End If

'change the saved state

Me.macroProject.Saved = False

End If

'quit the IDE

Me.mDTE.Quit()

End Sub

Error when running setup- VSTAVersion

Melody — Thu, 13 Nov 2008 17:46:00 GMT

There is a somewhat confusing error that appears when running setup, if the registry entry VSTAVersion = 9.0 is not present. The error states “Cannot find one or more components. Please reinstall the application.” To correct this add the above registry entry (be sure to specify “9.0” not “2.0”) and re-run setup. For more information on this, see Host Configuration Registry Key Settings.

Generics Part I: Generic Parameters of Intrinsic Types

Melody — Fri, 24 Oct 2008 19:26:00 GMT

With VSTA v 2 it is possible to use generic parameters of intrinsic types with minimal effort. The example below demonstrates this with a method added to the ShapeApp.Application class which accepts a List<string>.

Steps:
1) Create the proxy file ignoring the ProxyGen warnings:
ProxyGen.exe Warning: 21070 : Generics are not supported. The following types contain generic parameters and will be excluded. Its occurrences will be replaced by System.Object.
List`1

2) In the proxy file, the generic types were replaced with System.Object. Change the object type back to the type List<String>.

3) In the HostTypeMapProvider.GetTypeForCanonicalName, add a check for these types and return them if found.

Host:

using System;
using System.Collections.Generic;

public partial class Application
{

public int ReturnCount(List<string> listToCount)
{ return listToCount.Count; }
}

HostTypeMapProvider:
internal partial class HostTypeMapProvider
{
   public System.Type GetTypeForCanonicalName(string canonicalName)
   {
       //default fetch from the dictionary
       if (canonicalToTypeName.ContainsKey(canonicalName))
       {
           return canonicalToTypeName[canonicalName];
       }

//check for List<string>

if (canonicalName.Contains("List") && canonicalName.Contains("String"))
return typeof(System.Collections.Generic.List<string>);

return null;
}
}

Proxy:
public abstract partial class Application : global::System.MarshalByRefObject
{
//change type from object to List<string>
[global::Microsoft.VisualStudio.Tools.Applications.Runtime. HostMemberAttribute("ReturnCount", BindingFlags = global::System.Reflection.BindingFlags.Instance | global::System.Reflection.BindingFlags.Public | global::System.Reflection.BindingFlags.InvokeMethod)]

//public virtual int ReturnCount(object listToCount) { throw new global::System.NotImplementedException(); }
public virtual int ReturnCount(List<string> listToCount) { throw new global::System.NotImplementedException(); }
}

public partial class ApplicationEntryPoint
{
   //change type from object to List<string>
   //public virtual int ReturnCount(object listToCount)
   public virtual int ReturnCount(List<string> listToCount)
   {       return this.RemoteObject.ReturnCount(listToCount);   }
}

After ~5 minutes of idle time debugging macro projects fails with an IPC Port error.

Gary — Wed, 22 Oct 2008 20:00:00 GMT

After ~5 minutes of idle time, VSTA macro projects are unable to debug and VSTA IDE displays a “Failed to write to an IPC Port: The pipe is being closed” or similar. Second attempt produces this error message “Requested Service not found” error message dialog. Loaded add-ins do not timeout (that was fixed in .Net 3.5 SP1).

Periodically ‘Start Debugging’ manually or programmatically (DTE.Debugger.Go()) debugging the open project prevents this problem from occurring, but this not an acceptable workaround .

Steps to repro:

1) Build the ShapeAppMacroRecordingCSharp sample.

2) Run the associated setup .js file.

3) Run the ShapeAppMacroRecordingCSharp sample.

4) Launch the IDE.

5) Set a break point in the OnStartup method of the ide.

6) Debug from the IDE and confirm the break point is hit when debugging.

7) Leave the host application and IDE idle for 5 minutes or more.

8) ‘Start’ Debug from the IDE: “Failed to write to an IPC Port: The pipe is being closed” message will appear.

9) ‘Start’ Debug from the IDE again: “Requested Service not found” message will appear.

Solution:

This is a bug in the sample. The ShapeAppMacroRecordingCSharp sample should add InitializeLifetimeService() method with infinite timeout to the class VstaDesignTimeIntegration as shown below

/// <summary>

/// Provides Designtime VSTA Integration for ShapeAppCSharp.

/// </summary>

internal sealed class VstaDesignTimeIntegration : MarshalByRefObject, IExternalDebugHost

{

#region MarshalByRefObject

public override object InitializeLifetimeService()

{

return null; // Allows remoting from VS as long as we live.

}

#endregion MarshalByRefObject public override object InitializeLifetimeService()

. . .

Host Attributes in the Proxy File

Melody — Fri, 17 Oct 2008 13:39:00 GMT

In the proxy file, all types and non-static members in non-classEntryPoint types are marked with a host attribute. The host attributes HostTypeAttribute and HostMemberAttribute are used to reconcile name changes. When there is no name change the attribute is unnecessary. The VSTA runtime uses this attribute, if available, to determine which type/member to call in the host.

For example, in the descriptor file if we change the method name for Application.NewDocument to Application.UpdatedName_NewDocument, the method in the proxy will be called Application.UpdatedName_NewDocument and will have the HostMemberAttribute "NewDocument". If this attribute is removed VSTA will attempt to call Application.UpdatedName_NewDocument in the host and this will fail. Similarly, if you change a HostMemberAttribute, VSTA will use the attribute name and the call will fail if no methods match the attribute name. Also, if you switch attribute names, the method for the attribute will be called. This may be useful in some cases.

Descriptor file:
(Application class)

Proxy file:
(Application class)
[global::Microsoft.VisualStudio.Tools.Applications.Runtime.HostMemberAttribute("NewDocument", BindingFlags = global::System.Reflection.BindingFlags.Instance | global::System.Reflection.BindingFlags.Public | global::System.Reflection.BindingFlags.InvokeMethod)]

public virtual void UpdatedName_NewDocument() { throw new global::System.NotImplementedException(); }

(ApplicationEntryPoint class)
public virtual void UpdatedName_NewDocument()

{

this.RemoteObject.UpdatedName_NewDocument();

}

Add-in:
Me.UpdatedName_NewDocument

this.UpdatedName_NewDocument();

VSTA Documentation on MSDN

Melody — Fri, 10 Oct 2008 14:53:00 GMT

The MSDN site now includes documentation for VSTA v 2.0. The documentation available through the MSDN site is an updated version of the documentation included with the SDK. Updates in the on-line documentation include sections on how to properly expose structs and tips on debugging. This site also provides a Community Content section where users can post helpful tips and workarounds.

Click here to go to VSTA 2.0 on MSDN

Updated EventSample with EntryPoint Generic Event Handling

Melody — Wed, 08 Oct 2008 19:52:00 GMT

There is a new sample up demonstrating generic event handling in entry point classes. Click here to download EventSample VB v2.1 – Exposing Generic Events in Entry Point Classes

Excerpt from EventSample VB v2.1 EventHandlerT in EntryPoint Classes.doc:

At this time there is no direct way to expose an EventHandler<T> in the host to VSTA add-ins. This sample uses a workaround which involves using non-generic event handling between the host and proxy, and generic event handling between the proxy and add-in. This is accomplished by raising the non-generic events in the host and adding methods to the proxy to translate the events and event args. The host and proxy must be modified; however, the host item provider and host type map provider do not require any alterations.

This workaround only works for generic events raised by the entry point class the add-in is based on. There is a separate workaround for generic events raised by other classes which is more involved.

This sample is a modified version of the Event Sample VB v 2. To run this sample, extract the zip file and run the included setup file SetupEventSample VB v 2.1.js. Build the solution to move the proxy to the GAC and build the included sample add-in to load the assembly. Both events hooked into the by the add-in will be triggered by entering a message into the input box and selecting “Add”.

The proxy and add-ins use tight versioning, the proxy assembly is marked as version 2.1 and the project templates included use this assembly as version specific. To use the included AutoProxyGen Input.xml file to regenerate the main proxy file, update the file locations (the proxy included will work so this is not necessary). Only one modification was done to the auto-generated proxy file, in the entry point class and it’s base the non-generic events were changed from public to private so that only the generic events are visible to add-ins.

Workaround Components:

Host

1) Define custom event args.

2) Define an EventHandler<T> in the EntryPoint class using the custom event args (must be the entry point the add-in will be based on).

3) Define a delegate using the custom event args. This will be used to communicate between the host and proxy.

4) Define an event based on the delegate defined in 3 above. This will be used to communicate between the host and proxy.

5) Anytime the EventHandler<T> is raised, raise the event based on the delegate, this event will trigger the EventHandler<T> in the proxy/add-in.

Proxy

6) Create the proxy as normal. This will define in the proxy:

a. The custom event args from 1.

b. The delegate using the custom event args from 3.

c. The event based on the delegate from 4 in both the class and the entry point class.

This will skip:

a. The EventHandler<T> (all generics are skipped).

ProxyGen.exe Warning: 21040 : The following event type MainApplication contains generic type information and will not be parsed: cEventHandlerT.

7) Re-implement the custom EventArgs in the proxy while keeping the auto-generated custom EventArgs. Do this by using a different name for the re-implemented custom event args, or nesting them in a class.

8) Expand the partially defined entry point class in the proxy (suggest to do this is a separate code file) adding:

a. A private event EventHandler<T> for the custom event args for internal use by the proxy. Do not define the add and remove methods for this event.

b. A flag for the private event defined above initialized to false.

c. The EventHandler<T> defined in the host skipped by ProxyGen using the re-implemented event args deined in 7 above. Define the add and remove methods for this event. In the Add method, hook the value passed in to the private event defined in 8a above. Then, if the flag defined in 8b is false, hook the auto-generated generic event handler defined in the main proxy file to a new method to be defined in the expanded entry point class (defined below) and set the flag to true. In the remove method, remove the value from the private event defined in 8a above.

d. Add a method which satisfies the signature for the generic event handling, using the original event args. In this method, translate the original event args to the re-implemented event args. Use the re-implemented event args to raise the private event defined in 3a.

9) Expand the partially defined class in the proxy adding the EventHandler<T> (suggest to do this in the same separate code file).