Chapter Four: Integrating the VSTA IDE

My integration journey is taking some exciting turns. As always, I would encourage you to read the first three posts in this series (Chapter One, Chapter Two, and Chapter Three) before reading this one.

            I have finally integrated the VSTA IDE into my Contact Manager program. I am going to go through how I did this, show some code, and talk about some of the problems I encountered. Here is a link to my code:

            The first thing to do is to run SetupContactManager.js (Right-click it and select Open with Commmand Prompt so you will. Now look in your MyDocuments folder. There should be a new folder with the name ContactManager. This is where the application will store the add-in and macro data for the program. All the files needed for this sample are included in the ZIP file, so you should not have to download any external dependencies (You will have to have the VSTA 2.0 SDK and SQL Server 2005 Express Edition installed, however.) Make sure any dependency errors are resolved, and then build the project. Open the application and click File then click Load IDE.

The VSTA IDE should open.

Now resolve the Interface Library dependency, by pointing it to the InterfaceLibrary.dll file under the main application's Debug folder.

Now create a method called Macro1 under the Startup and Shutdown methods. Make it do whatever you want.

When you are finished programming this method, go back to the main application and select File then Run Macro:

You should see this window:

Click Run, and the code in your Macro1 method will execute.

Here is an example:

Now I will walk you through the steps I took to get this functionality.

First, let me go over the features in VSTA that made this integration possible.

As you may already know, VSTA is software that allows the user of an application to run custom code in an application while the application is running, through a Visual Studio-like IDE. These custom bits of code are called AddIns. These Add-Ins are stored in a templates folder that is in the same folder as the application. When the user runs the Install batch file, it registers the application with the VSTA runtime using a specified name for the application called the HostID, and creates a folder for its Add-Ins in the MyDocuments folder. The user can now create Macros (custom user-created methods) in his Add-In.

            Now let’s dig a little deeper in to the code that makes this possible.

If you look at my code, you will notice that I have added four new files to the solution: VSTADesignTimeIntegration.vb, VSTARuntimeIntegration.vb, MacroManager.vb, and MessageFilter.vb. I am not going to get into MessageFilter.vb, but I will give a brief overview of the other three:

VSTADesignTimeIntegration.vb is in charge of showing the IDE, opening and creating Macro projects, and debugging the Add-In.

VSTARuntimeIntegration.vb is in charge of loading and unloading Add-Ins and Macros.

MacroManager.vb contains the Macro manager user interface, updates the list of Macros, and gets the Macros’ names.

I encourage you to explore these files, and see how they work in the application. Also, look over the documentation provided with the VSTA SDK, especially the part about registering your application.

     I am now going to walk you through what happens behind the scenes with VSTA in my application. In the AppLoad method, when the program is not run from script, the first workings of VSTA are started. The messagefilter is instantiated first. Once the messagefilter has been instantiated, the application instantiates VSTARuntimeIntegration and VSTADesignTimeIntegration, and runs their Connect methods. Because VSTARuntimeIntegration comes first, I will walk you through what happens when the application calls its Connect method. First, the application passes an instance of the host class (ContactClass) to VSTARuntimeIntegration. Then the application finds and loads the Add-ins, and runs their Startup methods. The Macros themselves are now loaded. Now the application instantiates VSTADesignTimeIntegration and runs its Connect method. Just like in VSTARuntimeIntegration, the VSTADesignTimeIntegration‘s Connect method passes in ContactClass. The application calls the methods in VSTADesignTimeIntegration when the application loads the IDE and on other IDE events, and when debugging Add-Ins. The Macro Manager provides a dialog box for viewing the available macros in the Add-In. It finds these macros by searching for methods in the Add-In that contain the string “Macro.” It then allows the user to either edit or run a macro based on what button the user clicks.

     I have used in this application a type of integration called “design-time only.” This method of integration differs from the method outlined in the VSTA SDK documentation. This integration does not have the Add-In connect to the host using a proxy object, which is the standard integration procedure. Instead, the host imports the add-in using a byte-stream, and does not utilize a proxy object. Without the use of a proxy object, the integration process becomes much simpler. The downside to this is that once the Add-In loads, the host can’t unload the Add-In. In addition, any crash of the Add-In will also crash the host, and debugging the Add-In will pause the host. These downsides, while not necessarily an issue, must be kept in mind when deciding which integration method to use.

     Now I will go over some problems I had while integrating VSTA, in hopes that you will know what to do if you run across these same issues. First, make sure that your Add-In template is located in the right folder (the folder specified in the CreateNewMacroProject method in the VSTADesignTimeIntegration.vb file), and that if you are using a setup file like the one in my application, you have the paths and HostID defined correctly.

     One of the specific mistakes I made was to instantiate more variables than the program required. This caused various errors in getting my application to run properly. Utilizing good programming practices in general will be immensely beneficial to you in any programming scenario. Also, be very careful in translating code from one language to another: be sure that you recognize the differences in the languages you are translating (the language’s syntax, what you must explicitly define, how the language handles variables, etc.).

     One other note:

If your program crashes or closes unexpectedly, check the processes in Task Manager to make sure an orphaned vsta.exe is not running. If it is, end it, or your computer will not shut down.

One other thing you may have noticed that has changed is the lack of a message box before the program loads. To ruin the Script, now you must specify a command-line argument of -s. I have created a shortcut to do this and put it in the Debug and Release folders.

     In my previous post, I discussed the Managed Extensibility Framework. However, MEF cannot be used to import VSTA Add-Ins for one reason: once MEF has loaded an Add-In, it cannot alter the Add-In, because the Add-in is locked. That is why VSTA must get a byte stream of the Add-in and work with that, instead of loading the Add-In files themselves. I have integrated MEF into an Add-in itself, however, and will talk about this in my next post.