Andrew Whitechapel : COMAddIn

Exposing Events From Non-VSTO Add-in Automation Objects

andreww — Mon, 02 Mar 2009 07:03:00 GMT

I posted a while back about exposing an automation object from an add-in that fires events. That post was couched in terms of VSTO add-ins. A customer asked recently how the same technique could be used in a non-VSTO add-in. So, that’s the topic of this post.

First, here’s my automation object and the interfaces it implements. IAddInUtilities is a regular incoming interface that defines one method, CreateCustomTaskPane. The AddInUtilities class implements this method: because the AddInUtilities class is little more than an API into the add-in’s functionality, this implementation simply invokes a corresponding method on the add-in class itself to do the actual work of creating the task pane.

IAddInEvents is the outgoing event interface, which defines one method, SomeEvent. The AddInUtilities class does not implement this interface – like any other event interface, this will be implemented by the client. Instead, the AddInUtilities class declares its support for this interface by using the ComSourceInterfaces attribute. The class then exposes a method, FireEvent, to allow the add-in class to cause the event to fire.

// The custom interface that our COMAddIn.Object implements.

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

[Guid("C2743EFC-AD90-47a6-B1DC-12E52C6E2FE7")]

public interface IAddInUtilities

{

void CreateCustomTaskPane();

}

// The delegate type for our custom event.

[ComVisible(false)]

public delegate void SomeEventHandler(object sender, EventArgs e);

// Outgoing (source/event) interface.

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]

public interface IAddInEvents

{

[DispId(1)]

void SomeEvent(object sender, EventArgs e);

}

// The object we will expose through the COMAddIns collection.

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

[Guid("F743C9A0-DDEF-49d5-AEAA-2E6798814C23")]

[ComSourceInterfaces(typeof(IAddInEvents))]

public class AddInUtilities :

StandardOleMarshalObject,

IAddInUtilities

{

private Connect addInObject;

// Event field: this is what a COM client will hook up

// their sink to.

public event SomeEventHandler SomeEvent;

internal AddInUtilities(SharedAddInEvents.Connect o)

{

addInObject = o;

}

// This is the interface method we expose to potential clients.

public void CreateCustomTaskPane()

{

addInObject.CreateCustomTaskPane();

}

internal void FireEvent(object sender, EventArgs e)

{

if (SomeEvent != null)

{

SomeEvent(sender, e);

}

Next, we define a custom UserControl, which will form the basis of our custom task pane. As this is a shared add-in, not a VSTO add-in, we can’t take advantage of VSTO’s wrappers for custom task panes. So, we have to make our custom UserControl visible to COM, effectively registering it as an ActiveX control. At runtime, Office will instantiate this control via normal COM registry lookup and the CoCreateInstance mechanism. Our control will have just one button, and when the user clicks this button, we sink the Click event and fire the custom event exposed from our IAddInUtilities object.

[ComVisible(true)]

[Guid("6017B040-87CE-4bfc-88E8-18009A8EC403")]
public partial class SimpleUserControl : UserControl

{

public Connect AddInObject;

public SimpleUserControl()

{

InitializeComponent();

}

private void btnHello_Click(object sender, EventArgs e)

{

AddInObject.FireClickEvent(sender, e);

}

Finally, the main add-in class – which, in a shared add-in project, is typically named Connect. This implements IDTExtensibility2 as normal, and also ICustomTaskPaneConsumer – because we want to advertise to Office that we want to create custom task panes. In the OnConnection method, we instantiate our AddInUtilities object and expose it out through the COMAddIns collection.

[Guid("CA2575D4-E119-4257-B180-2121720CF773")]

[ProgId("SharedAddInEvents.Connect")]

public class Connect :

Object, IDTExtensibility2,

ICustomTaskPaneConsumer

{

private ICTPFactory factory;

private AddInUtilities addInUtilities;

public void OnDisconnection(

ext_DisconnectMode disconnectMode, ref System.Array custom) {}

public void OnAddInsUpdate(ref System.Array custom) {}

public void OnStartupComplete(ref System.Array custom) {}

public void OnBeginShutdown(ref System.Array custom) {}

public void OnConnection(

object application, ext_ConnectMode connectMode,

object addInInst, ref System.Array custom)

{

addInUtilities = new AddInUtilities(this);

COMAddIn comAddIn = (COMAddIn)addInInst;

comAddIn.Object = addInUtilities;

}

public void CTPFactoryAvailable(ICTPFactory CTPFactoryInst)

{

factory = CTPFactoryInst;

}

Recall that the AddInUtilities class makes a call to the CreateCustomTaskPane method in the add-in class. Here, we create a custom task pane based on our custom UserControl. When Office has created the task pane, we can extract the custom UserControl and set its add-in object property. We do this so that the control has a way to call back into the add-in class. When the user clicks the button in our task pane, the event is propagated from the UserControl to the add-in object, and we propagate it out to any clients that are listening for the event on the exposed COMAddIn.Object object (that is, in our case, the AddInUtilities object).

internal void CreateCustomTaskPane()

{

try

{

CustomTaskPane taskPane =

factory.CreateCTP(

"SharedAddInEvents.SimpleUserControl",

"My Caption", Type.Missing);

SimpleUserControl sc =

(SimpleUserControl)taskPane.ContentControl;

sc.AddInObject = this;

taskPane.Visible = true;

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

internal void FireClickEvent(object sender, EventArgs e)

{

addInUtilities.FireEvent(sender, e);

}

When the add-in is built, and the host Office app is running, we can invoke the AddInUtilities method to create a custom task pane from any suitable automation client. When the user clicks the button in the task pane, we fire an event, which the client can sink. For example, this is how you could connect from VBA:

Public WithEvents addInUtils As SharedAddInEvents.AddinUtilities

Private Sub CommandButton1_Click()

Dim addin As Office.COMAddIn

Set addin = Application.COMAddIns("SharedAddInEvents.Connect")

Set addInUtils = addin.Object

addInUtils.CreateCustomTaskPane

End Sub

Private Sub addInUtils_SomeEvent( _

ByVal sender As Variant, ByVal e As mscorlib.EventArgs)

MsgBox "Got SomeEvent"

End Sub

Note, when you build the project, you should have the Register for COM Interop option checked. This registers all ComVisible types, as well as building and registering a typelib for these types. Unlike VSTO projects, the ComVisible types are not associated in the registry with the typelib, so you need to add this extra registry key for the typelib under the CLSID for the AddInUtilities object:

[HKEY_CLASSES_ROOT\<Wow6432Node>\CLSID\{F743C9A0-DDEF-49D5-AEAA-2E6798814C23}\TypeLib]
@="{45C1778F-EFB9-4d93-81EF-EE14011C133B}"

Note also that I’ve carefully added explicit GUIDs for both interfaces, the AddInUtilities class, the custom UserControl, the main add-in Connect class, and the assembly itself (in the assemblyinfo.cs). If you don’t do this, VS will give you arbitrary GUIDs when it builds the project – and you won’t have any easy way to figure out what they are.

Exposing Events from Managed Add-in Objects

andreww — Mon, 13 Oct 2008 19:13:00 GMT

Following on from my recent posts on exposing add-in objects, here and here, it occurred to me that its sometimes useful to be able to expose events from these objects. Recall that you can expose your add-in through the COMAddIn.Object property in the Office OM, either directly (in a non-VSTO add-in) or through VSTO’s RequestComAddInAutomationService mechanism (documented here).

For example, let’s suppose you’re exposing an object from your add-in that provides a DoSomething method, like this:

namespace ComServiceOleMarshal

{

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddInUtilities

{

void DoSomething();

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddInUtilities :

StandardOleMarshalObject,

IAddInUtilities

{

public void DoSomething()

{

Globals.ThisAddIn.CreateNewTaskPane();

}

}

(Let’s assume the CreateNewTaskPane method in the ThisAddIn class does in fact create a new custom taskpane.) Then, in a document/workbook opened in the host application, you write some VBA macro code to consume this object, like this:

Private Sub CommandButton1_Click()

Dim addin As Office.COMAddIn

Dim addInUtils As ComServiceOleMarshal.AddinUtilities

Set addin = Application.COMAddIns("ComServiceOleMarshal")

Set addInUtils = addin.Object

addInUtils.DoSomething

End Sub

So far, so good. Now, suppose you want to be able to fire events from your exposed add-in object. For example, say the custom taskpane has a button, and when the user clicks the button, you want to propagate the event out through the exposed add-in object. To achieve this, you would write an event interface which defines the events you want to expose. Then, specify that the add-in object class implements this event interface, using the ComSourceInterfaces attribute, documented here:

// The delegate type for our custom event.

[ComVisible(false)]

public delegate void SomeEventHandler(object sender, EventArgs e);

// Outgoing (source/event) interface.

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]

public interface IAddInEvents

{

[DispId(1)]

void SomeEvent(object sender, EventArgs e);

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

[ComSourceInterfaces(typeof(IAddInEvents))]

public class AddInUtilities :

StandardOleMarshalObject,

IAddInUtilities

{

// Event field. This is what a COM client will hook up

// their sink to.

public event SomeEventHandler SomeEvent;

public void DoSomething()

{

Globals.ThisAddIn.CreateNewTaskPane();

}

// We expose a method to allow the add-in class to

// cause the event to fire.

inernal void FireEvent(object sender, EventArgs e)

{

if (SomeEvent != null)

{

SomeEvent(sender, e);

}

The ThisAddIn class is enhanced to sink the Click event on the button, and re-fire it out through the exposed add-in object:

public partial class ThisAddIn

{

private AddInUtilities addInUtilities;

protected override object RequestComAddInAutomationService()

{

if (addInUtilities == null)

{

addInUtilities = new AddInUtilities();

}

return addInUtilities;

}

internal void CreateNewTaskPane()

{

UserControl uc = new UserControl();

Button b = new Button();

b.Text = "Click Me";

b.Click += new EventHandler(b_Click);

uc.Controls.Add(b);

Microsoft.Office.Tools.CustomTaskPane taskPane =

this.CustomTaskPanes.Add(uc, "New TaskPane");

taskPane.Visible = true;

}

// When the user clicks the button on the taskpane,

// we sink the Click event here, and fire the custom

// event exposed from our IAddInUtilities object.

internal void b_Click(object sender, EventArgs e)

{

addInUtilities.FireEvent(sender, e);

}

Finally, the VBA client code is enhanced to use the WithEvents keyword when defining the add-in object, so that it can sink the propagated event:

Public WithEvents addInUtils As ComServiceOleMarshal.AddinUtilities

Private Sub CommandButton1_Click()

Dim addin As Office.COMAddIn

Set addin = Application.COMAddIns("ComServiceOleMarshal")

Set addInUtils = addin.Object

addInUtils.DoSomething

End Sub

Private Sub addInUtils_SomeEvent(ByVal sender As Variant, ByVal e As mscorlib.EventArgs)

MsgBox "Got SomeEvent"

End Sub

Note: for this to work, in the VBE you need to add a reference to the add-in’s typelib, and to the typelib for mscorlib, which is typically in a path like this: C:\Windows\Microsoft.NET\Framework\v2.0.50727\mscorlib.tlb.

As an aside, note that Richard Cook, a developer in my team, has started a cool series of blog posts that contrast .NET delegate-based event handling with classic COM IConnectionPoint eventing in managed code.

COMAddIns Race Condition

andreww — Thu, 14 Aug 2008 00:29:00 GMT

You can expose an arbitrary object from your add-in as a kind of extension to the Office host application’s object model. To do this, you set your object as the value of the Object property on the COMAddIn object that represents your add-in in the host’s COMAddIns collection object. You can do this directly in a non-VSTO add-in, or through VSTO’s RequestComAddInAutomationService mechanism.

If you intend for this to be used by other add-ins, VSTO doc-level customizations, VBA, or any other in-proc extension (smart tag, realtime data component, etc), the race condition does not apply. However, once you’ve exposed your object, it is also callable from out-of-proc automation clients – whether this is your intention or not.

For out-of-proc clients, there is a race condition on startup. Specifically, there’s a window of opportunity as the host application is starting up where such clients can get hold of the COMAddIns collection, and individual COMAddIn objects, before add-ins have actually been loaded.

For example, let’s suppose I have an Excel add-in (called “ComServiceOleMarshal”) that exposes an AddinUtilities object:

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddinUtilities

{

void DoSomething();

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities : IAddinUtilities

{

public void DoSomething()

{

MessageBox.Show("Something");

}

public partial class ThisAddIn

{

private AddinUtilities addinUtilities;

protected override object RequestComAddInAutomationService()

{

if (addinUtilities == null)

{

addinUtilities = new AddinUtilities();

}

return addinUtilities;

}

…and a WPF client that offers a Button. When the user clicks the Button, we’ll launch Excel, get hold of the add-in and its AddinUtilities object, and invoke the DoSomething method:

private void buttonInvokeAddIn_Click(object sender, RoutedEventArgs e)

{

Excel.Application excel = null;

try

{

excel = new Excel.Application();

excel.Visible = true;

object addinName = "ComServiceOleMarshal";

Office.COMAddIn addin = excel.COMAddIns.Item(ref addinName);

ComServiceOleMarshal.IAddinUtilities utils = null;

utils = (ComServiceOleMarshal.IAddinUtilities)addin.Object;

utils.DoSomething();

MessageBox.Show("Close this message to continue");

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

finally

{

if (excel != null)

{

excel.Quit();

excel = null;

}

GC.Collect();

GC.WaitForPendingFinalizers();

GC.Collect();

GC.WaitForPendingFinalizers();

}

Nine times out of 10 (or, actually, more like 9,999 times out of 10,000), this will fail on the line that attempts to invoke the DoSomething method. This is because the previous line failed to get hold of the AddinUtilities object and returned null into the utils variable.

It would be nice if there were some convenient event fired by the host application to notify interested listeners when the add-ins have actually been loaded, and the COMAddIns collection contains fully-populated objects. Unfortunately, there is no such event. For Excel, you might consider sinking events such as the WorkbookActivate, WorkbookOpen or WindowActivate events. Similar events are exposed by the other Office apps. Unfortunately, these will not fire in all scenarios, and typically will not fire when the application first starts.

Instead, you might think you could put in an artificial delay in your application: perhaps you could launch Excel and get the COMAddIn object when your window is loaded, and then implement your Button handler to fetch the AddinUtilities object later. Unfortunately, while this might reduce the chances that you’ll hit the race condition (simply by virtue of the fact that you’re doing extra work before attempting to get the object), it doesn’t solve it, and is non-deterministic.

So, the only sensible approach is to attempt to get the AddinUtilities object, and retry until you succeed. This can actually be pretty lightweight:

while (utils == null)

{

utils = (ComServiceOleMarshal.IAddinUtilities)addin.Object;

System.Threading.Thread.Sleep(100);

}

utils.DoSomething();

You’d probably also want to build in some bail-out clause, so that you don’t end up retrying forever. For example, you could prompt the user, or simply restrict the number of times to retry, and so on. Here’s a simple example:

while (utils == null)

{

if (MessageBox.Show("Continue trying to get the object?",

"Alert", MessageBoxButton.YesNo) == MessageBoxResult.Yes)

{

System.Threading.Thread.Sleep(100);

utils = (ComServiceOleMarshal.IAddinUtilities)addin.Object;

}

else

{

break;

}

if (utils != null)

{

utils.DoSomething();

}

Update: turns out this is a bug in the VSTO runtime - to be fixed soon, I hope.

Why your COMAddIn.Object should derive from StandardOleMarshalObject

andreww — Tue, 12 Aug 2008 00:24:00 GMT

In general, it is important that any code in a managed Office add-in should execute on the main UI thread. The reason for this is that there are several components that simply will not work when executed from any other but the main UI thread – examples include calls on WinForms controls, and calls into the VSTO runtime. Fortunately, in most normal circumstances, your add-in code will run on the main UI thread.

However, there is one scenario where you need to be more vigilant. Recall that you can expose your add-in through the COMAddIn.Object property of the COMAddIn object that represents your add-in in the COMAddIns collection, either directly (in a non-VSTO add-in) or through VSTO’s RequestComAddInAutomationService mechanism (documented here). If this object is consumed in-proc (for example, by another add-in in the same process, or a VSTO doc-level customization, or VBA macro), there should be no problem. On the other hand, if the object is consumed by an out-of-proc client, there will be a problem.

By default, calls coming from out-of-proc clients will not be executed on the main UI thread. This is because from COM’s perspective all managed objects by default are thread-neutral. One consequence of this is that COM will not attempt to switch threads to execute calls into such objects, and since cross-process COM calls will come in on an arbitrary RPC thread, COM decides to make the call right on this thread.

This, of course, is not the behavior that we want. What we really want is to tell COM that our managed object lives in a Single Threaded Apartment (STA), because then COM will marshal the call onto the thread the object was created on (which, for Office add-ins, will be the main UI thread). To achieve this, you can simply derive your exposed add-in object from System.Runtime.InteropServices.StandardOleMarshalObject. This class is documented here.

The underlying reasons for this behavior go back to the original design of COM and OLE (OLE being a layer on top of COM that supports various UI mechansims). Essentially, COM objects involved with UI programming nearly always require a single-threaded apartment. Multi-threaded apartments were designed on the assumption that there was no UI. Further details here.

For an example of where using StandardOleMarshalObject will make a difference, let’s suppose I have an Excel add-in (called “ComServiceOleMarshal”) that exposes an AddinUtilities object:

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddinUtilities

{

void DoSomething();

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities : IAddinUtilities

{

public void DoSomething()

{

Globals.ThisAddIn.CreateNewTaskPane();

}

The main ThisAddIn object in the add-in instantiates this AddinUtilities object, exposes it via RequestComAddInAutomationService, and also exposes a CreateNewTaskPane method which the AddinUtilities object calls. The CreateNewTaskPane method uses the VSTO CustomTaskPanes.Add method, which internally invokes Office code in order to create a new task pane. Thus, we’ve set things up such that any call into the AddinUtilities method will result in a call into the Office host app.

public partial class ThisAddIn

{

private AddinUtilities addinUtilities;

protected override object RequestComAddInAutomationService()

{

if (addinUtilities == null)

{

addinUtilities = new AddinUtilities();

}

return addinUtilities;

}

internal void CreateNewTaskPane()

{

Microsoft.Office.Tools.CustomTaskPane taskPane =

this.CustomTaskPanes.Add(new UserControl(), "New TaskPane");

taskPane.Visible = true;

}

If you write client code to consume this AddinUtilities object in an in-proc component, such as another Excel add-in, a VSTO doc-level customization, or from VBA, everything should work OK:

'In-proc VBA

Private Sub CommandButton1_Click()

Dim addin As Office.COMAddIn

Dim automationObject As Object

Set addin = Application.COMAddIns("ComServiceOleMarshal")

Set automationObject = addin.Object

automationObject.DoSomething

End Sub

However, if you write an external automation client to invoke the AddinUtilities object, things will go horribly wrong. For example, here’s a simple managed console client:

static void Main(string[] args)

{

Excel.Application excel = new Excel.Application();

excel.Visible = true;

Console.WriteLine("press a key to invoke the AddinUtilities object");

Console.ReadLine();

object addinName = "ComServiceOleMarshal";

Office.COMAddIn addin = excel.COMAddIns.Item(ref addinName);

ComServiceOleMarshal.IAddinUtilities utils =
(ComServiceOleMarshal.IAddinUtilities)addin.Object;

utils.DoSomething();

Console.WriteLine("press a key to close Excel");

Console.ReadLine();

}

When this code attempts to call through to the AddinUtilities object, we’ll typically get an E_NOINTERFACE error like this:

System.InvalidCastException: Unable to cast COM object of type 'System.__ComObject' to interface type 'Microsoft.VisualStudio.Tools.Office.Runtime.Interop.ICustomTaskPaneSite'. This operation failed because the QueryInterface call on the COM component for the interface with IID '{3CA8CD11-274A-41B6-A999-28562DAB3AA2}'failed due to the following error: No such interface supported (Exception from HRESULT: 0x80004002 (E_NOINTERFACE)). at ComServiceOleMarshal.IAddinUtilities.DoSomething() at ConsoleTest.Program.Main(String[] args) in C:\Temp\ComServiceOleMarshal\ConsoleTest\Program.cs:line 29

This message is pretty obscure. What’s happening is that the CustomTaskPanes.Add method uses the ICustomTaskPaneSite interface to call into the VSTO runtime. Since the VSTO runtime is implemented as an STA COM object, the call has to go through the COM marshaling mechanism. However, the ICustomTaskPaneSite interface has not been designed to be marshaled, and so the entire call fails. To fix all this, you can simply derive the AddinUtilities class from StandardOleMarshalObject, and rebuild:

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities :

StandardOleMarshalObject,

IAddinUtilities

{

public void DoSomething()

{

Globals.ThisAddIn.CreateNewTaskPane();

}

Now calls to the exposed object should work correctly for out-of-proc clients also. Source code for the add-in and the client are attached to this post. Many thanks to Misha for helping me figure out the exact behavior here.

Integrating Doc-level and Add-in Solutions

andreww — Fri, 21 Mar 2008 03:20:00 GMT

Everyone knows you can build document-level Office solutions and you can build application-level Office add-ins. Suppose your requirements dictate that you build a solution that uses both techniques – can this be done? First, let’s pause and consider whether this is a good idea in the first place, and whether you could re-architect to use only one or the other.

In most cases, the requirements for a solution can be met either with doc-level solutions or app-level add-ins. The Office application’s COM object model is entirely available to both types of solution. In some cases, there will be clear advantages to one or the other approach. For example, the VSTO-enhanced doc-level host-item controls (eg, XmlNodes and Content Controls in Word – or, ListObjects and NamedRanges in Excel) are only available in doc-level solutions. In other cases, you could do it either way. For example, suppose you have a need for some control UI in a custom task pane – you could use the doc-level Actions Pane, or you could use the app-level Custom Task Pane. Suppose you need Ribbon customization – again, you could do this either with a doc-level solution or with an app-level add-in. The same is true for custom CommandBars in older versions of Office.

On the other hand, there will be some contexts where the only possible solution requires the use of both techniques. Consider this scenario, for example:

· Your solution needs to work with users who have Word 2003 and with other users who have Word 2007.

· A user must be able to work with the solution in one version, then hand the document to another user who might be using the other version, who then hands it back for further work. In other words, the same document must be editable in both versions, it must be round-trippable, and the VSTO customization must work in both versions.

· The solution requires custom CommandBars when running in Word 2003, and custom Ribbon when running in Word 2007.

· The solution requires some form of Custom Task Pane or Actions Pane.

These requirements impose significant constraints on the solution design, specifically:

· The solution must use the Word97-2003 binary file format, because the VSTO v3 runtime that works with the new Open XML file format does not work with Word 2003.

· You cannot use doc-level Ribbon customization, because this only works with the new file format. So, you must use app-level Ribbon customization.

· You cannot use an app-level Custom Task Pane, because it must work the same in Word 2003 which does not support Custom Task Panes. So, you must use the doc-level Actions Pane.

To meet these seeminly conflicting requirements, you’d have to design the solution to use both doc-level and app-level components:

· Build an app-level add-in, which will work in both Word 2003 and 2007. This would include conditional code to determine which version of Word the solution is running in, and set up either a Ribbon customization or custom CommandBars accordingly.

· Build a doc-level customization, targeting the old binary file format in Word 2003 – which will also work in Word 2007, so you can have a doc-level ActionsPane.

· Remaining business logic could be put in either place: either in the doc-level customization or in the app-level add-in. If you need closely integrated processing of VSTO doc-level host-item control wrappers, this obviously goes in the doc-level customization. Any other work could go in either place.

· Connect the doc-level customization with the app-level add-in through shared logical interfaces. That is, the doc code will include an object that implements some interface, say IDocumentCommands, that is known to the add-in; and the add-in will include an object that implements some interface, say IAddInCommands, that is known to the doc code. These interfaces should be defined in a separate assembly that is then re-used by both the doc customization and the add-in.

· The runtime hook-up can use the fact that all app-level add-ins are exposed through the host application’s COMAddIns collection. Each add-in can expose any arbitrary functionality by setting the COMAddIn.Object property to some arbitrary object. In a sensible system, you would set this property to an object that implements an interface that is known to both the doc-level customization and the app-level add-in, say IAddInCommands.

· Calls from the doc-level customization to the app-level add-in will therefore go through this object, via standard CLR COM interop.

· The Office COM object models do not expose any COMAddIns equivalent for doc-level customizations. That means that the doc-level code must make itself available in a custom manner, and without the benefit of CLR COM interop.

· Therefore, the solution requires that the doc-level code gets hold of the add-in’s exposed object via the COMAddIns collection, and hands off to the add-in some exposed doc-level object. From this point, calls in the other direction – that is, from the app-level add-in to the doc-level customization will go through remoting, via the shared (IDocumentCommands) interface.

Here’s an overview of the design:

Let’s break this down. First, we define the two interfaces in a separate class library. Note that the IDocumentCommands interface will be implemented in the doc code, and the implementing object will be used via remoting – so this does not need to be COM-visible. On the other hand, the IAddInCommands will be implemented by the object that the add-in sets into the COMAddIn.Object property, and will be used via COM interop – and therefore needs to be a COM-visible dual interface:

namespace DocumentAddInInterfaces

{

public interface IDocumentCommands

{

void InsertText(string s);

}

[ComVisible(true)]

[Guid("158CF0BC-16F3-49be-A4DD-E3A81283C7A0")]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddInCommands

{

void RegisterDocument(IDocumentCommands d);

void InsertText(string s);

}

When the add-in loads, it constructs some arbitrary object that it wishes to expose. This object implements an interface (IAddInCommands) that is known to both the add-in and the doc customization. This interface offers two methods: RegisterDocument, which allows the doc-level code to register itself with the add-in; and InsertText, which inserts some text in the document:

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddInCommands : IAddInCommands

{

private Word.Application wordApplication;

public AddInCommands(Word.Application w)

{

wordApplication = w;

}

public void RegisterDocument(IDocumentCommands d)

{

Globals.ThisAddIn.documentCommands = d;

}

public void InsertText(string s)

{

object missing = Type.Missing;

Word.Range r = wordApplication.ActiveDocument.Range(
ref missing, ref missing);

r.InsertAfter(

String.Format("Add-in.InsertText: {0}{1}",
s, Environment.NewLine));

}

The add-in sets this object as the value of the Object property in the COMAddIn object that represents this add-in in the COMAddIns collection of the host application. In VSTO add-ins, this is done by overriding the RequestComAddInAutomationService method:

public partial class ThisAddIn

{

internal IDocumentCommands documentCommands;

public IAddInCommands addInCommands;

protected override object RequestComAddInAutomationService()

{

if (addInCommands == null)

{

addInCommands = new AddInCommands(this.Application);

}

return addInCommands;

}

When the document loads (at some point after the add-in is loaded), it gets hold of the application’s COMAddIns collection, and the specific COMAddIn object that represents the add-in it wants. From this, it gets the add-in’s exposed object that implements IAddInCommands. The first thing it does with this object is to call back on its RegisterDocument method. This is the method that allows the doc code to pass an arbitrary object to the add-in code, thereby establishing the two-way communication:

public partial class ThisDocument

{

public IDocumentCommands documentCommands;

internal IAddInCommands addInCommands;

private void ThisDocument_Startup(object sender, System.EventArgs e)

{

SimpleControl simpleControl = new SimpleControl();

this.ActionsPane.Controls.Add(simpleControl);

try

{

documentCommands = new DocumentCommands(this.Application);

object addInProgId = "IntegrationTestAddIn";

addInCommands =

(IAddInCommands)

this.Application.COMAddIns.Item(ref addInProgId).Object;

addInCommands.RegisterDocument(documentCommands);

simpleControl.btnCallAddIn.Enabled = true;

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

Note that the code above assumes we have a SimpleControl custom UserControl that we’re placing in the doc-level Actions Pane. This SimpleControl offers a button that the user can click.

The doc object implements another known interface (IDocumentCommands) which has one method, InsertText. This object will be used via remoting, so we’ll make it MBRO:

internal class DocumentCommands :

System.MarshalByRefObject, IDocumentCommands

{

private Word.Application wordApplication;

public DocumentCommands(Word.Application w)

{

wordApplication = w;

}

public void InsertText(string s)

{

object missing = Type.Missing;

Word.Range r = wordApplication.ActiveDocument.Range(
ref missing, ref missing);

r.InsertAfter(

String.Format("Document.InsertText: {0}{1}",
s, Environment.NewLine));

}

At some point later on, the user interacts with the doc customization code and also with the app-level add-in code, in no particular order. Here’s what happens when they interact with the custom CommandBars or Ribbon (which are implemented in the add-in)… They click a button (in the Ribbon/CommandBar) to insert some text in the document. This button handler uses the cached IDocumentCommands object to invoke the InsertText method implemented in the doc code:

public void btnCallDocument_Click(Office.IRibbonControl control)

{

Globals.ThisAddIn.documentCommands.InsertText("Add-in invokes Doc");

}

Conversely, when the user interacts with the doc-level custom ActionsPane, the Click handler for the button on the UserControl uses the cached IAddInCommands object to invoke the InsertText method implemented in the add-in code:

private void btnCallAddIn_Click(object sender, EventArgs e)

{

Globals.ThisDocument.addInCommands.InsertText("Doc invokes Add-in");

}

To sum up: most of the time, you can simply pick one or other of the two main Office client customization technologies to meet your solution requirements – and you should strive to keep things simple wherever possible. On the other hand, sometimes you need to build a more complex solution that uses both technologies. This is particularly true if you need to span multiple Office versions, each of which supports different extensibility mechanisms. If you take this approach, you’ll want to connect the components together in some sensible fashion. Going from add-in to doc customization, you can use the CLR’s standard COM interop. Going from doc customization to add-in, you can use remoting. In both directions, you should use a defined set of interfaces.

VSTO Add-ins, COMAddIns and RequestComAddInAutomationService

andreww — Tue, 16 Jan 2007 03:05:00 GMT

The COMAddIns property is a collection of COMAddIn objects exposed by Office applications that support COM add-ins. The COMAddIn interface defines a small number of methods/properties, such as the ProgId of the add-in and the Connect state. It also defines an Object property. By default, the value of the Object property is null. An add-in can set this value itself, and the purpose is to expose this add-in’s functionality to external callers. VSTO supports this mechanism through a new virtual method on the AddIn base class, RequestComAddInAutomationService. Most developers will never use this service, and its an example of one of the little things that VSTO does to support the widest range of add-in developers. Here’s how it works.

In your VSTO add-in class, you decide which methods you want to expose to external callers, and wrap these methods in a ComVisible class. Then, you override the RequestComAddInAutomationService virtual method to return an instance of this class. For example, we’ll expose a DisplayMessage method. The calls to this method will be made via automation, so I’m defining an automation (dual) interface to define the method:

[ComVisible(true)]

[Guid("B523844E-1A41-4118-A0F0-FDFA7BCD77C9")]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddinUtilities

{

void DisplayMessage();

}

I can also define a class that will implement the interface to perform some suitable operation in the method:

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities : IAddinUtilities

{

public void DisplayMessage()

{

MessageBox.Show("Hello World");

}

Then, in my add-in class, I override RequestComAddInAutomationService to return an instance of this class. As you can see, the programming model for this method is very similar to the generic RequestService method that VSTO uses for the new extensibility interfaces (although of course the underlying mechanism is completely different):

public partial class ThisAddIn

{

private AddinUtilities addinUtilities;

protected override object RequestComAddInAutomationService()

{

if (addinUtilities == null)

{

addinUtilities = new AddinUtilities();

}

return addinUtilities;

}

Then, I can create a suitable Office document and insert some VBA to call this exposed method. So, if my add-in is an Excel add-in, I can create an XLSM (macro-enabled) workbook and Alt-F11 to get the VBA editor up. I’ll put a CommandButton on the worksheet, and code it to call the DisplayMessage method:

Private Sub CommandButton1_Click()

Dim addin As Office.COMAddIn

Dim automationObject As Object

Set addin = Application.COMAddIns("ExcelAddinService")

Set automationObject = addin.Object

automationObject.DisplayMessage

End Sub

From the VBA code, you can see that my add-in is registered as “ExcelAddinService”. All I’m doing is fetching the COMAddIn object that represents this particular add-in in the COMAddIns collection (specified by ProgId). Then, I’m fetching the Object property of this add-in, and invoking the exposed method. If you’re following along, joining the dots as it were, you can infer that the VSTO runtime takes the return value from the RequestComAddInAutomationService method in the add-in to set the COMAddIn::Object property to the instance of the AddinUtilities class defined in the add-in.

Note that my VBA is using late binding – I don’t have a reference to the add-in at design-time. If the add-in exposed many methods with varying signatures, it might be worth adding a reference to it in the VBA editor.

So, to show this, I’ll expand my add-in to expose a second method, this one takes a couple of parameters and uses them to interact with the active Worksheet.

[ComVisible(true)]

[Guid("B523844E-1A41-4118-A0F0-FDFA7BCD77C9")]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddinUtilities

{

void DisplayMessage();

void SetCellValue(String cellAddress, object cellValue);

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities : IAddinUtilities

{

public void DisplayMessage()

{

MessageBox.Show("Hello World");

}

public void SetCellValue(String cellAddress, object cellValue)

{

Excel.Worksheet sheet = (Excel.Worksheet)

Globals.ThisAddIn.Application.ActiveSheet;

Excel.Range cell = sheet.Cells.get_Range(

cellAddress, Type.Missing);

cell.Value2 = cellValue;

}

In my VBA, I can add a reference to the AddinService add-in, so that I get design-time intellisense. I’ll put a second CommandButton on the worksheet, and code it to call the SetCellValue method:

Private Sub CommandButton2_Click()

Dim addin As Office.COMAddIn

Dim utilities As ExcelAddinService.addinUtilities

Set addin = Application.COMAddIns("ExcelAddinService")

Set utilities = addin.Object

Call utilities.SetCellValue("a1", 456.78)

End Sub

I can even write a Windows Forms app to automate Excel externally, and invoke the exposed add-in methods. For example, this is a Windows Forms app with 2 buttons – I launch Excel when the form loads, and cache the Application and the add-in Object. Then, I call one of the exposed methods in each button Click handler:

public partial class WinTestAddinServiceForm : Form

{

public WinTestAddinServiceForm()

{

InitializeComponent();

}

private Excel.Application excel;

private ExcelAddinService.IAddinUtilities utils;

private void WinTestAddinServiceForm_Load(object sender, EventArgs e)

{

// Launch Excel, make it visible, and ensure there is

// at least one sheet.

excel = new Excel.Application();

excel.Visible = true;

excel.Workbooks.Add(Excel.XlSheetType.xlWorksheet);

// Fetch the add-in we want to exercise, and cache

// its exposed object.

object addinName = "ExcelAddinService";

Office.COMAddIn addin = excel.COMAddIns.Item(ref addinName);

utils = (ExcelAddinService.IAddinUtilities)addin.Object;

}

private void WinTestAddinServiceForm_FormClosed(

object sender, FormClosedEventArgs e)

{

// Clean up all Excel object references.

utils = null;

excel = null;

GC.Collect();

GC.WaitForPendingFinalizers();

GC.Collect();

GC.WaitForPendingFinalizers();

}

private void displayMessage_Click(object sender, EventArgs e)

{

utils.DisplayMessage();

}

private void setCellValue_Click(object sender, EventArgs e)

{

utils.SetCellValue("a1", 123.45);

}

As you can see, I’ve obviously got a reference to the ExcelAddinService assembly in this project – that’s only so that I can use the IAddinUtilities interface. Realistically of course, the interface would be best defined in an assembly separate from the add-in.

This feature seems like a small thing, but actually its part of a wider strategy to support the idea of Office as a true development platform. That idea implies at least some minimal level of interconnectivity support between various custom pieces in a solution.

UPDATE NOTE: See here for an update to this post: http://blogs.msdn.com/andreww/archive/2008/08/11/why-your-comaddin-object-should-derive-from-standardolemarshalobject.aspx