How to Expose Methods in your VSTO Add-in

I have had this question a number of times and surprised myself when I did not see it in my blog. So here goes.

There are times when (like my Master Add-in Entry), you need to expose a set of methods or properties in your add-in so that other add-ins or applications are able to access them. Here is how it is done:

1) You create an interface and a class that uses that interface, like this:

[ComVisibleAttribute(true)]
public interface IExposedMethods
{
    void LoadDocument(string path);
}

[ComVisibleAttribute(true)]
[ClassInterface(ClassInterfaceType.None)]
public class ExposedClass : IExposedMethods
{
    public void LoadDocument(string path)
    {
        Globals.ThisAddIn.Application.Workbooks.Open(path);
    }
}

 

2) Next, you need to add the following code to your ThisAddin.cs:

private ExposedClass _exposedInstance;
protected override object RequestComAddInAutomationService()
{
    if (_exposedInstance == null)
        _exposedInstance = new ExposedClass();

    return _exposedInstance;
}

3) And finally, to call it and access this from another application instance, you do this:

Excel.Application xlApp = new Excel.Application();
xlApp.Visible = true;
object addinName = "MyAddinName";
Office.COMAddIn addIn = xlApp.COMAddIns.Item(ref addinName);
addIn.Object.LoadDocument(@"c:\path\test.xlsm");

It is actually quite easy to implement. And the beauty here is that the ExposedClass you created can have all sorts of methods and properties that are exposed. And because the _exposedInstance is global to ThisAddIn (via Globals.ThisAddin._exposedInstance), you can access it anywhere. So it is a perfect way for one add-in to contact another or for a parent Windows Form application to reach into the Add-in and set properties and call methods and have it open documents and such for you.

VSTO and COM/OLE…

If you have been doing much work in VSTO and especially around Excel and embeddings, you may have been bit by this bug. Does this error look familiar:

clip_image002

“The program used to create this object is Excel. That program is either not installed on your computer or it is not responding. To edit this object, install Excel or ensure that any dialog boxes in Excel are closed.”

This error can be caused by the following:

  • A .NET3.5 Add-in or a .NET 4.0 Add-in
  • You have attached to the WorkbookOpen and/or WorkbookActivate events.
  • You are trying to edit/open/double-click on an embedded Excel instance inside a Word or PowerPoint document.

There have been several reports of this problem on the Microsoft MSDN site:

There are also a number of KB articles that document the problem and attribute it to specific programs:

The problem is specifically documented here:

Simple Solution

The basic simple answer is to place a Marshal.ComReleaseObject(Wb) at the end (or better, in the Finally block) of your event handlers. This will properly allow Word and excel to handle the OLE communication by not having VSTO hang on to an instance handle of the workbook, therefore causing the error.

And this is not carte blanche to start placing ComReleaseObject() all over your code. I have found VERY VERY few limited cases where using ComReleaseObject() in an add-in necessary. And this is one of them. Hot smile

Orphan Issue

It is not a panacea, either. Confused smile While it resolves the issues of OLE initialization and allows you to edit your Excel embedding in Word (as one example), it does not prevent one other scenario that I like to call “Orphaned Excel.” In this scenario, you edit your embedded Excel instance in another Window (usually via a right-click / Ole Object / Open). If you leave Excel open, return to Word and close the document, Excel should close. But in the VSTO COM/OLE scenario it may not – it will remain open with the embedded workbook still editable. However, it is orphaned an no longer associated with its container. Any edits will be lost.

That is where a solution I created for Excel/Word OLE interaction comes in here:

This add-in is very well commented and explains the following:

  • When a workbook is opened, it looks to see if it is embedded.
  • If it is, it connects to the running instance of Word, and gets a reference to the parent document.
  • A timer in the add-in will then continually check the status of the document
  • If the parent document is still opened, nothing happens. However, if Word is existed or the parent document is closed, the child embedding is forced closed.

IMPORTANT NOTE

However, and this is important note. For everything you do, you are in the sandbox with other kids. Sad smile Your add-in is loading in the same AppDomain as everybody else. If there is another VSTO 3.5/4.0 Add-in loaded in Excel and that add-in is not doing any of the above – well, your still going to have problems.

That is what makes this issue so vexing. Steaming mad You can play by all the rules, but you cannot prevent other kids from throwing sand. This is why I see some customers going to the extreme to manage out (disable) all other COM add-ins when they load their solution. But this does not work for HKEY_LOCAL_MACHINE Loaded add-ins.

There are few options and most involve a lot of code. I say, TEST. If your are in an Enterprise environment, test all your VSTO add-ins together, find code owners and get everyone on the same page. If it is a vendor add-in causing the problem, point them here. Smile

Creating a Loader Add-in (Master Add-in)

I have now helped about half a dozen customers over the last 3 years to perform this very same task. In each case the scenario is the same:

  • They have documents that are very specific to their system
  • They want to create an add-in to assist with the management of these documents.
  • They only want the add-in to load when one of their document is opened.
  • BONUS: They also want to remove other add-ins
  • BONUS: They would like a pristine instance of Word or Excel.

There are several methods to accomplish each of these tasks. But the one I find is easiest to maintain is what I call the “Master Add-in” approach.

In the “Master Add-in” you essentially attach one event: DocumentOpen or WorkbookOpen. You place code in the event to detect whether it is a document you care about. This can be done in several ways:

  • You can look at the path where the file came from.
  • You can look at the name of the file, if there is a specific naming convention you follow.
  • Or, you can tag he document with Document Properties or Custom Xml Parts.

Once you have identified that it is a document you care about you follow this basic process:

  • Get the path to the file being open and store it.
  • Close the workbook or document being passed into the Open event.
  • Create a new Instance of Word or Excel.
  • Iterate through the COM Add-ins collection and the Add-ins collection and disable everything you do not want running. This includes disabling the Master Add-in as you do not want it running for the next parts.
  • Locate your COM Add-in in the collection and set Connect = true.
  • Open the document or workbook from the application object.

You will now have two instances of Excel or Word open. One that the user was originally working with which has the Master Add-in loaded and then the new one that is customized with your specific add-in and only your add-in.

This is useful for when you have multiple versions of your system and you can update the Master to recognize which version to launch.

Getting this to work just right is sometimes a challenge and you have to be careful not to disable all the add-ins for all instances. I have a few customer examples that I have built and will work on cleaning them up. I will combine the best parts and will write a new entry in the future which will walk you through creating one.