Andrew Whitechapel : COM add-ins

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.

Launching Office Apps Programmatically

andreww — Mon, 01 Dec 2008 01:17:00 GMT

There are at least 9 different ways to start or connect to an Office app programmatically in managed code, as summarized in this table:

PIA Interop	Using the Office PIAs is the most RAD approach, with the greatest level of design-time and compile-time support. This has to be the preferred approach for almost all scenarios. A variation of this is the use of embedded PIA types using ComImport, as described here and here.
Process.Start	The simplest fire-and-forget approach, useful if you want to launch any executable but don’t need to interact with the app’s OM afterwards.
Activator.CreateInstance	Internally, this uses reflection to find and execute an appropriate constructor for the specified object. This can be slow, but useful if you intend to continue using reflection to work with the app – which you might do if you want to eliminate use of the PIAs altogether.
Marshal.BindToMoniker	Internally, this p/invokes to the Win32 BindToMoniker API. Useful if you have a narrow interest in the app’s exposed object that deals with a particular file type. In other words, if you want to work with a particular doc/workbook/presentation/etc using only a limited subset of the OM.
Marshal.GetActiveObject	Internally, p/invokes to the Win32 GetActiveObject. This will throw an exception if the object’s server is not already running, as it looks up the target ProgID in the ROT. One of the classic uses of this API is to determine whether or not the target app is already running.
VisualBasic.CreateObject	A compatibility API, which internally calls Activator.CreateInstance.
VisualBasic.GetObject	A compatibility API, which internally calls either Activator.CreateInstance or Marshal.BindToMoniker. In other words, it will connect to an already-running instance of the app if it finds one, otherwise it will create a new instance.
ActivateMicrosoftApp	This is a method exposed from the Excel Application object (and only the Excel Application object), used for activating or starting other Office apps (specifically, Access, FoxPro, Outlook, PowerPoint, Project, or Word). This approach does not give you access to the target app’s OM, so its effect is very similar to Process.Start.
AccessibleObjectFromWindow	Given the HWND for the target app (which you can find using FindWindowEx), this gets you access to the app’s OM. This is useful if your starting point is an HWND, or if you’re specifically focused on the app’s IAccessible implementation, and only minimally interested in the rest of the OM.

Here’s some code that illustrates each of these approaches – this is implemented in an Excel add-in, where each of the “launch/connect” methods is invoked via a Ribbon button click handler. The comments should make it clear enough what's going on, and you can see the full source-code in the attached solution zip:

public partial class ThisAddIn

{

private string pptxFile;

private PowerPoint.Application ppt;

private PowerPoint.Presentation pptx;

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

{

Uri codeBaseUri =
new Uri(Assembly.GetExecutingAssembly().CodeBase);

pptxFile = Path.Combine(

Path.GetDirectoryName(codeBaseUri.AbsolutePath), "Test.pptx");

}

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

{

// Make sure to release any references to COM objects.

ppt = null;

pptx = null;

GC.Collect();

GC.WaitForPendingFinalizers();

GC.Collect();

GC.WaitForPendingFinalizers();

}

// Use the PIAs to interop with PowerPoint.

internal void InteropCreate()

{

ppt = null;

pptx = null;

ppt = new PowerPoint.Application();

ppt.Visible = Office.MsoTriState.msoTrue;

pptx = ppt.Presentations.Open(

pptxFile,

Office.MsoTriState.msoFalse,

Office.MsoTriState.msoTrue);

}

// Use Process.Start to start a PowerPoint process. This does not

// give you access to the target app's OM.

internal void ProcessStart()

{

ProcessStartInfo si = new ProcessStartInfo();

si.FileName =
@"C:\Program Files (x86)\Microsoft Office\Office12\Powerpnt.exe";

si.Arguments = pptxFile;

Process.Start(si);

}

// Internally, Activator.CreateInstance uses reflection to find and

// execute an appropriate constructor for the specified object.

internal void CreateInstance()

{

Type t = Type.GetTypeFromProgID("PowerPoint.Application");

object o = Activator.CreateInstance(t);
// Note: we could cast the return from Activator.CreateInstance

// to the PIA type that we expect, if we wanted to use the PIAs.

t.InvokeMember(

"Visible", BindingFlags.Public | BindingFlags.SetProperty,

null, o, new object[] { true }, null);

object p = t.InvokeMember(

"Presentations",
BindingFlags.Public | BindingFlags.GetProperty,

null, o, null, null);

Type t2 = p.GetType();

t2.InvokeMember("Open",
BindingFlags.Public | BindingFlags.InvokeMethod,

null, p, new object[] { pptxFile }, null);

}

// Internally, Marshal.BindToMoniker p/invokes to Win32 BindToMoniker.

internal void BindToMoniker()

{

ppt = null;

pptx = null;

pptx = (PowerPoint.Presentation)Marshal.BindToMoniker(pptxFile);

pptx.Application.Visible = Office.MsoTriState.msoTrue;

}

    // Internally, Marshal.GetActiveObject p/invokes to Win32
    // GetActiveObject. This will throw an exception if the object's
    // server is not already running. Win32 GetActiveObject looks up the
    // target ProgID in the Running Object Table.

internal void GetActiveObject()

{

ppt = null;

pptx = null;

try

{

ppt = (PowerPoint.Application)

Marshal.GetActiveObject("PowerPoint.Application");

ppt.Visible = Office.MsoTriState.msoTrue;

pptx = ppt.Presentations.Open(

pptxFile,

Office.MsoTriState.msoFalse,

Office.MsoTriState.msoTrue);

}

catch (COMException cex)

{

            // If the target app is not already running, GetActiveObject
            // will throw a COMException (0x800401E3): Operation
            // unavailable (Exception from HRESULT: 0x800401E3
            // (MK_E_UNAVAILABLE)).

Debug.WriteLine(cex.ToString());

}

// Internally, CreateObject calls Activator.CreateInstance - that is,

// it creates a new instance of the target application (if the app is

// single-use).

internal void CreateObject()

{

ppt = null;

pptx = null;

// GetObject requires the object class name, plus optionally a

// machine server name.

ppt = (PowerPoint.Application)

Microsoft.VisualBasic.Interaction.CreateObject(
"PowerPoint.Application", "");

ppt.Visible = Office.MsoTriState.msoTrue;

pptx = ppt.Presentations.Open(

pptxFile,

Office.MsoTriState.msoFalse,

Office.MsoTriState.msoTrue);

}

// Internally, GetObject calls either Marshal.BindToMoniker or

// Activator.CreateInstance - that is, it either uses an existing
// instance of the target app, or creates a new instance.

internal void GetObject()

{

ppt = null;

pptx = null;

// GetObject requires either the executable filename or the object

// class name.

ppt = (PowerPoint.Application)

Microsoft.VisualBasic.Interaction.GetObject(
"", "PowerPoint.Application");

ppt.Visible = Office.MsoTriState.msoTrue;

pptx = ppt.Presentations.Open(

pptxFile,

Office.MsoTriState.msoFalse,

Office.MsoTriState.msoTrue);

}

// ActivateMicrosoftApp activates a Microsoft application if it is

    // running or starts a new instance of it if it is not. Restricted
    // to these apps: Access, FoxPro, Outlook, PowerPoint, Project, Word.
    // Note that this does not give you access to the target app's OM.

internal void ActivateMicrosoftApp()

{

this.Application.ActivateMicrosoftApp(

Excel.XlMSApplication.xlMicrosoftPowerPoint);

}

[DllImport("User32")]

public static extern int GetClassName(

int hWnd, StringBuilder lpClassName, int nMaxCount);

// Callback passed to EnumChildWindows to find any window with the

// registered classname "paneClassDC" - this is the class name of

// PowerPoint's accessible document window.

public bool EnumChildProc(int hwnd, ref int lParam)

{

StringBuilder windowClass = new StringBuilder(128);

GetClassName(hwnd, windowClass, 128);

if (windowClass.ToString() == "paneClassDC")

{

lParam = hwnd;

}

return true;

}

public delegate bool EnumChildCallback(int hwnd, ref int lParam);

[DllImport("User32")]

public static extern bool EnumChildWindows(

int hWndParent, EnumChildCallback lpEnumFunc, ref int lParam);

[DllImport("User32")]

public static extern int FindWindowEx(

int hwndParent, int hwndChildAfter, string lpszClass,

int missing);

// AccessibleObjectFromWindow gets the IDispatch pointer of an object

// that supports IAccessible, which allows us to get to the native OM.

[DllImport("Oleacc.dll")]

private static extern int AccessibleObjectFromWindow(

int hwnd, uint dwObjectID,

byte[] riid,

ref PowerPoint.DocumentWindow ptr);

// Get the window handle for a running instance of PowerPoint.

internal void GetAccessibleObject()

{

ppt = null;

pptx = null;

try

{

// Walk the children of the desktop to find PowerPoint’s main
// window.

int hwnd = FindWindowEx(0, 0, "PP12FrameClass", 0);

if (hwnd != 0)

{

// Walk the children of this window to see if any are
// IAccessible.

int hWndChild = 0;

EnumChildCallback cb =
new EnumChildCallback(EnumChildProc);

EnumChildWindows(hwnd, cb, ref hWndChild);

if (hWndChild != 0)

{

// OBJID_NATIVEOM gets us a pointer to the native
// object model.

uint OBJID_NATIVEOM = 0xFFFFFFF0;

Guid IID_IDispatch =

new Guid("{00020400-0000-0000-C000-000000000046}");

PowerPoint.DocumentWindow ptr = null;

int hr = AccessibleObjectFromWindow(

hWndChild, OBJID_NATIVEOM,
IID_IDispatch.ToByteArray(), ref ptr);

if (hr >= 0)

{

ppt = ptr.Application;

ppt.Visible = Office.MsoTriState.msoTrue;

pptx = ppt.Presentations.Open(

pptxFile,

Office.MsoTriState.msoFalse,

Office.MsoTriState.msoTrue);

}

catch (Exception ex)

{

Debug.WriteLine(ex.ToString());

}

Now, wasn’t that exciting? Note that in almost all circumstances, you’ll want to use PIA interop (or the embedded types variation) rather than any of the other approaches. Note that the basic functionality of the embedded types approach is greatly enhanced in .NET CLR 4.0 as described by Misha here and here.

Passing Objects to Exposed Add-in Methods

andreww — Mon, 01 Dec 2008 01:13:00 GMT

I’ve posted a few times on the best way to expose methods from an add-in to automation clients – for example, here, here and here. So far, in my examples, I’ve described very simple exposed methods that take no parameters – but what happens if you want to expose a method that does take one or more parameters? The answer depends on the type of the parameter(s).

If you want to pass some simple type – a value type or a string – there’s nothing extra you need to do. So, let’s suppose your interface and exposed object look like this:

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddinUtilities

{

void DoSomething(string s);

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities :

StandardOleMarshalObject,

IAddinUtilities

{

public void DoSomething(String caption)

{

Globals.ThisAddIn.CreateNewTaskPane(caption);

}

…and your add-in class looks implements a custom CreateNewTaskPane method like this:

public partial class ThisAddIn

{

…

internal void CreateNewTaskPane(string caption)

{

Microsoft.Office.Tools.CustomTaskPane taskPane =

this.CustomTaskPanes.Add(new UserControl(), caption);

taskPane.Visible = true;

}

…then, your automation client can call into the exposed object like this:

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

excel.Visible = true;

object addinName = "ComServiceOleMarshal";

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

ComServiceOleMarshal.IAddinUtilities utils = null;

while (utils == null)

{

utils = (ComServiceOleMarshal.IAddinUtilities)addin.Object;

System.Threading.Thread.Sleep(100);

}

utils.DoSomething("Hello");

So far, so good. But, suppose that instead of a simple value type or string, you want to pass some reference type object to the exposed method. Let’s say you have some class like this:

public class SomeObject

{

public int Number;

public string Name;

public SomeObject(int n, string s)

{

Number = n;

Name = s;

}

…and your interface defines a method that takes an object of this class as a parameter, like this:

[ComVisible(true)]

[InterfaceType(ComInterfaceType.InterfaceIsDual)]

public interface IAddinUtilities

{

//void DoSomething(string s);

void DoSomething(SomeObject o);

}

[ComVisible(true)]

[ClassInterface(ClassInterfaceType.None)]

public class AddinUtilities :

StandardOleMarshalObject,

IAddinUtilities

{

//public void DoSomething(String caption)

public void DoSomething(SomeObject o)

{

string caption = String.Format("{0}={1}", o.Number, o.Name);

Globals.ThisAddIn.CreateNewTaskPane(caption);

}

…and you want to invoke this in your automation client like this:

ComServiceOleMarshal.SomeObject o =

new ComServiceOleMarshal.SomeObject(123, "Hello");

//utils.DoSomething("Hello");

utils.DoSomething(o);

If you try this, you’ll get an exception like this:

System.InvalidCastException: Unable to cast object of type 'System.__ComObject' to type 'ComServiceOleMarshal.SomeObject' at ComServiceOleMarshal.IAddinUtilities.DoSomething(SomeObject o)

What’s happening is that the runtime is attempting to marshal the custom object across the 2 processes, and failing because the object is not marshalable. The simplest solution to this is to mark the custom class as Serializable, then it will be marshaled by simply serializing it (and deserializing it) via a memory stream:

[Serializable()]

public class SomeObject

{

Implementing IMessageFilter in an Office add-in

andreww — Thu, 20 Nov 2008 07:01:00 GMT

First a warning: this is an advanced scenario, and you should not attempt to use this technique unless you’re sure you know what you’re doing. The reason for this warning is that while the technique described here is pretty simple, it’s also easy to get wrong in ways that could interfere significantly with the host application.

Problem description: you build an Office add-in that periodically makes calls back into the host object model. Sometimes the calls will fail, because the host is busy doing other things. Perhaps it is recalculating the worksheet; or (most commonly), perhaps it is showing a modal dialog and waiting for user input before it can continue.

If you don’t create any background threads in your add-in, and therefore make all OM calls on the same thread your add-in was created on, your call won’t fail, it simply won’t be invoked until the host is unblocked. Then, it will be processed in sequence. This is the normal case, and it is recommended that this is how you design your Office solutions in most scenarios – that is, without creating any new threads.

However, if you do create additional threads, and attempt to make OM calls on any of those threads, then the calls will simply fail if the host is blocked. You’ll get a COMException, typically something like this: System.Runtime.InteropServices.COMException, Exception from HRESULT: 0x800AC472.

To fix this, you could implement IMessageFilter in your add-in, and register the message filter on your additional thread. If you do this, and Excel is busy when you make a call on that thread, then COM will call back on your implementation of IMessageFilter.RetryRejectedCall. This gives you an opportunity to handle the failed call – either by retrying it, and/or by taking some other mitigating action, such as displaying a message box to tell the user to close any open dialogs if they want your operation to continue.

Note that there are 2 IMessageFilter interfaces commonly defined. One is in System.Windows.Forms – you don’t want that one. Instead, you want the one defined in objidl.h, which you’ll need to import like this:

[StructLayout(LayoutKind.Sequential, Pack = 4)]

public struct INTERFACEINFO

{

[MarshalAs(UnmanagedType.IUnknown)]

public object punk;

public Guid iid;

public ushort wMethod;

}

[ComImport, ComConversionLoss, InterfaceType((short)1),
Guid("00000016-0000-0000-C000-000000000046")]

public interface IMessageFilter

{

[PreserveSig, MethodImpl(MethodImplOptions.InternalCall,
MethodCodeType = MethodCodeType.Runtime)]

int HandleInComingCall([In] uint dwCallType, [In] IntPtr htaskCaller,
[In] uint dwTickCount,

[In, MarshalAs(UnmanagedType.LPArray)] INTERFACEINFO[]
lpInterfaceInfo);

[PreserveSig, MethodImpl(MethodImplOptions.InternalCall,
MethodCodeType = MethodCodeType.Runtime)]

int RetryRejectedCall([In] IntPtr htaskCallee, [In] uint dwTickCount,
[In] uint dwRejectType);

[PreserveSig, MethodImpl(MethodImplOptions.InternalCall,
MethodCodeType = MethodCodeType.Runtime)]

int MessagePending([In] IntPtr htaskCallee, [In] uint dwTickCount,
[In] uint dwPendingType);

}

Then, implement this interface in your ThisAddIn class. Note that IMessageFilter is also implemented on the server (that is, in Excel, in our example), and that the IMessageFilter.HandleInComingCall call is only made on the server. The other 2 methods will be called on the client (that is, our add-in, in this example). We’ll get MessagePending calls after an application has made a COM method call and a Windows message occurs before the call has returned. The important method is RetryRejectedCall. In the implementation below, we display a message box asking the user whether or not they want to retry the operation. If they say “Yes”, we return 1, otherwise -1. COM expects the following return values from this call:

· -1: the call should be canceled. COM then returns RPC_E_CALL_REJECTED from the original method call.

· Value >= 0 and <100: the call is to be retried immediately.

· Value >= 100: COM will wait for this many milliseconds and then retry the call.

public partial class ThisAddIn : ExcelAddInMessageFilter.IMessageFilter

{

#region IMessageFilter Members

public uint HandleInComingCall(

uint dwCallType, IntPtr htaskCaller, uint dwTickCount,

INTERFACEINFO[] lpInterfaceInfo)

{

return 1;

}

public uint RetryRejectedCall(
IntPtr htaskCallee, uint dwTickCount, uint dwRejectType)

{

int retVal = -1;

Debug.WriteLine("RetryRejectedCall");

if (MessageBox.Show("retry?", "Alert", MessageBoxButtons.YesNo)

== DialogResult.Yes)

{

retVal = 1;

}

return retVal;

}

public uint MessagePending(
IntPtr htaskCallee, uint dwTickCount, uint dwPendingType)

{

Debug.WriteLine("MessagePending");

return 1;

}

#endregion

}

Finally, register your message filter with COM, using CoRegisterMessageFilter. Message filters are per-thread, so you must register the filter on the background thread that you create to make the OM call. In the example below, the add-in provides a method InvokeAsyncCallToExcel, which will be invoked from a Ribbon Button. In this method, we create a new thread and make sure this is an STA thread. In my example, the thread procedure, RegisterFilter, does the work of registering the filter – and it then sleeps for 3 seconds to give the user a chance to do something that will block – such as pop up a dialog in Excel. This is clearly just for demo purposes, so that you can see what happens when Excel blocks just before a background thread call is made. The CallExcel method makes the call on Excel’s OM.

public partial class ThisAddIn : ExcelAddInMessageFilter.IMessageFilter

{

#region IMessageFilter Members

…

#endregion

[DllImport("ole32.dll")]

static extern int CoRegisterMessageFilter(

IMessageFilter lpMessageFilter,
out IMessageFilter lplpMessageFilter);

private IMessageFilter oldMessageFilter;

internal void InvokeAsyncCallToExcel()

{

Thread t = new Thread(this.RegisterFilter);

t.SetApartmentState(ApartmentState.STA);

t.Start();

}

private void RegisterFilter()

{

CoRegisterMessageFilter(this, out oldMessageFilter);

Thread.Sleep(3000);

CallExcel();

}

private void CallExcel()

{

try

{

this.Application.ActiveCell.Value2 =
DateTime.Now.ToShortTimeString();

}

catch (Exception ex)

{

Debug.WriteLine(ex.ToString());

}

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.

AddInSpy - Diagnosing/Troubleshooting Office Add-ins

andreww — Wed, 01 Oct 2008 07:06:00 GMT

AddInSpy is a new diagnostic tool for reporting the maximum possible information about all Office add-ins registered on a machine. This is a free (unsupported) download, available on MSDN Code Gallery here. Covering article on MSDN here.

In fact, there are 2 tools: AddInSpy, which is a WPF GUI application, and AS, which is a scriptable console application. They both use the same scanning engine, so results are identical. Both tools allow you to produce an XML report of add-ins, and AddInSpy additionally displays the scan results in a convenient grid.

The tool discovers and reports a lot more information than is available through the Office UI natively, and will report on all registered add-ins, for all Office client applications that support COM add-ins, that is: Access, Excel, FrontPage, InfoPath, Outlook, PowerPoint, Project, Publisher, SharePoint Designer, Visio and Word. The tool covers native add-ins, managed shared add-ins and VSTO add-ins. It does not report on other extensions (Smart Tags, automation add-ins, and the like). The reported information includes the following:

ú The type of each add-in: VSTO, managed non-VSTO, native.

ú FriendlyName, ProgID, CLSID and LoadBehavior of the add-in.

ú For managed add-ins, the manifest path, assembly path, and assembly strongname, and the CLR version the add-in was built against.

ú The registry hive (HKCU or HKLM) where the add-in is registered.

ú For VSTO add-ins, the VSTO runtime version used by the add-in.

ú Installed date, and publish version, where applicable.

ú Which extensibility interfaces the add-in implements (IRibbonExtensibility, ICustomTaskPaneConsumer, FormRegionStartup, IBlogExtensibility, IBlogPictureExtensibility, EncryptionProvider, SignatureProvider or IDocumentInspector).

ú Whether the add-in uses any of the VSTO wrappers for Ribbon, custom taskpane, or custom form region.

ú Whether the add-in exposes itself for automation through the COMAddIns collection of the host application.

ú Whether the host application is running, and whether the add-in is loaded.

ú Whether the add-in is in the disabled items list (aka “blacklist”) for the current user, for each selected Office host application.

ú Context information: machine name, user/domain name, OS details, VSTO environment variables.

Both AddInSpy and AS support comprehensive configuration, allowing you to specify what type of scan to perform, and what types of data to include in the report. AddInSpy reports are configurable via the UI, whereas AS reports are configurable via command-line switches. Here’s a screenshot of the main AddInSpy window (made small so it fits on this blog):

You can also drill down on individual add-ins if you want, and get a dialog with the data for just one add-in of interest:

Note: this tool is a work in progress. Please download it, use it, and send me feedback. You can provide feedback (and report any bugs) on the Code Gallery site for the tool, or by posting comments to this blog post. Give it a work-out, and let me know what you think.

COM Shim Wizard 2.3.1.0

andreww — Wed, 27 Aug 2008 20:36:00 GMT

We’ve released a slight update to the COM Shim Wizard. This is available as a free download here, and the covering article is on MSDN here. The differences Between v2.3.0.0 and v2.3.1.0 are summarized below.

Setup

The major difference between v2.3.0.0 and v2.3.1.0 is that v2.3.0.0 was built to install with Visual Studio 2005, whereas v2.3.1.0 installs with either Visual Studio 2005 or Visual Studio 2008, or both. The setup for the COM Shim Wizard now gives you the option to choose which version or versions of Visual Studio to install for. There are 3 additional enhancements to the setup for the COM Shim Wizard v2.3.1.0:

1. The setup disables installation on a per-user basis. This is because installing per-user (and therefore registering to HKCU) causes problems on Vista with UAC turned on, or when running Visual Studio in an elevated process.

2. The custom actions are set to NoImpersonate, so that they work correctly on Vista with UAC on.

3. The setup is formatted so that any error messages are displayed (otherwise they are not visible in Vista, the user just sees Error 2869).

CLR Start Bug

I documented this fix as a community comment added to the MSDN documentation for the COM Shim Wizard v2.3.0.0. Part of what the shim does is to load the CLR: it does this by calling CorBindToRuntimeEx. We test the return from CorBindToRuntimeEx, and if it's S_FALSE, this indicates that the CLR has already been loaded. In the released version of the shim, if we get S_FALSE, we simply return.

However, there is a scenario where the CLR could already have been loaded but not started. It's an unusual scenario: it could happen if some other managed code was loaded into the process but never executed. The problem is that the shim code assumes that if the CLR is loaded it is not necessary for us to start it. Of course, if the only other things in the process that load the CLR are all shims created with the COM Shim Wizard, then this assumption would be true – because the first one to load would have loaded the CLR and started it. However, this assumption doesn't hold if there are other native components that load the CLR but don't start it.

We fixed this in the code generated by v2.3.1.0 of the wizard by simply removing the test for S_FALSE – this works because we do call Start later on.

Post-build step to copy ManagedAggregator.dll

In v2.3.0.0, a post-build step in the generated shim project copies the ManagedAggregator.dll from the \bin\debug folder unconditionally. We changed this in v2.3.1.0 to copy the dll from the target folder for each project configuration. For example, for a standard debug configuration, it will copy from \bin\debug; but for a release configuration, it will copy from \bin\release.

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.

Demand-Loading VSTO Add-ins

andreww — Tue, 15 Jul 2008 06:24:00 GMT

In an earlier post, I talked about how you could delay (or prevent) the loading of managed code using a native add-in. In that post I also listed the standard LoadBehavior settings, and I was assuming that everyone knows how these apply, but I got a couple of follow-up questions that prompted me to clarify the normal (LoadBehavior-based) demand-loading mechanism, and how it applies to VSTO add-ins.

It’s pretty simple: you can set up any Office COM add-in (native, managed, VSTO) for demand-loading in a standard way, that is by setting the LoadBehavior in the registry to 0x10 (16 dec). For versions of Office prior to 2007 (and for those Office apps that don’t yet support the Ribbon), the typical pattern is to create some custom CommandBar control in your add-in at startup. Office will load the add-in the first time it boots after the add-in is registered, call your add-in code to set up the custom UI, and cache this information so that when the user clicks the control, this will load the add-in.

In the case of add-ins that implement custom Ribbons, the behavior is essentially the same: Office will load the add-in the first time it boots after the add-in is registered, call GetCustomUI and cache the ribbon XML. Then, Office resets the LoadBehavior value to 8. Subsequently, when the user clicks one of the ribbon controls, this will load the add-in and set LoadBehavior to 9. This works with both a low-level IRibbonExtensibility implementation and with the VSTO designer-generated ribbon wrappers.

If you want to set LoadBehavior in your project for testing during development, you could create a regedit script, eg:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Office\Excel\Addins\MyAddIn]

"Description"="MyAddIn"

"FriendlyName"="MyAddIn"

"LoadBehavior"=dword:00000010

"Manifest"="c:\\Temp\\MyAddIn\\bin\\Debug\\MyAddIn.vsto|vstolocal"

...and then add this to the project properties as a post-build step:

regedit /s "$(SolutionDir)$(SolutionName).reg"

When it comes time to deploy the solution, if you’re using a setup project, you’ll have to set the LoadBehavior by setting the value in the registry editor in your setup project.

If you’re using ClickOnce publishing, you’ll need to edit the loadBehavior attribute value manually in the application manifest (and then re-sign the manifest).

That’s it. There’s nothing else you need to do. You create your custom Ribbon either using a low-level implementation or using the VSTO designer wrappers – all in the normal way.

Add-ins for Multiple Office Versions without PIAs (Pt2), or _VtblGap

andreww — Tue, 24 Jun 2008 21:50:00 GMT

In my last post, I discussed how you could avoid any dependency on the Office PIAs by using ComImport to redefine the host application’s OM interfaces. Someone (A Developer) pointed out that I had actually omitted the trailing 2 members of the IRibbonControl interface – and I mentioned that this wouldn’t stop the code working. I also mentioned that omitting interface members is a valid technique, so today I’ll explain what I mean by this.

I’m attaching the sample solution to this post – and you can compare it with the sample solution I attached to the previous post – you’ll see that the solutions are identical except that in this one I’m omitting selective interface members in my ComImport declarations. The idea is that I don’t want to include definitions of interface members that I’m not using. You might think that I could simply omit these members altogether – and this is true for trailing members, but it’s not true for non-trailing members. Strictly speaking, even for trailing members, it’s not good practice.

The reason is that these are COM interfaces, and the number and position of methods defined in a COM interface is paramount. At runtime, the methods are represented by a virtual function table (vtable), which contains slots that correspond to the methods, in the order of their declaration in the interface. Because calls into COM interfaces are implemented as calls to offsets from the start of the interface’s vtable (or the vtable for the object that implements the interface), it means that the order/position and number of the members is significant.

This ordering and numbering must be maintained when you redefine a COM interface using ComImport, and the .NET Framework provides member syntax to support this. In order to preserve vtable order, you use the special _VtblGapXX_YY method syntax to indicate missing members, where XX signifies the position in the vtable, and YY signifies the number of vtable members to be omitted from this position. For example, in the _CustomTaskPane interface, from position 1, you can omit 2 vtable members using this declaration:

void _VtblGap1_2();

This syntax allows me to preserve vtable slots for members I’m not defining, such that the subsequent members are still correctly positioned. Here’s the set of selectively ComImport-ed interfaces for custom task panes. Note that by omitting the DockPosition and DockPositionRestrict members, I can also avoid having to declare the MsoCTPDockPosition and MsoCTPDockPositionRestrict enums:

//public enum MsoCTPDockPosition

//{

// msoCTPDockPositionLeft,

// msoCTPDockPositionTop,

// msoCTPDockPositionRight,

// msoCTPDockPositionBottom,

// msoCTPDockPositionFloating

//}

//public enum MsoCTPDockPositionRestrict

//{

// msoCTPDockPositionRestrictNone,

// msoCTPDockPositionRestrictNoChange,

// msoCTPDockPositionRestrictNoHorizontal,

// msoCTPDockPositionRestrictNoVertical

//}

[ComImport, Guid("000C033B-0000-0000-C000-000000000046"), TypeLibType((short)0x10c0), DefaultMember("Title")]

public interface _CustomTaskPane

{

[DispId(0)]

string Title { [return: MarshalAs(UnmanagedType.BStr)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(0)] get; }

// From position 1, we omit 2 vtbl members.

void _VtblGap1_2();

//[DispId(1)]

//object Application { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)] get; }

//[DispId(2)]

//object Window { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(2)] get; }

[DispId(3)]

bool Visible { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(3)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(3)] set; }

[DispId(4)]

object ContentControl { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(4)] get; }

// From position 5, we omit 1 vtbl member.

//void _VtblGap5_1();

void _VtblGap_1();

//[DispId(5)]

//int Height { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(5)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(5)] set; }

[DispId(6)]

int Width { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(6)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(6)] set; }

// From position 7, we omit 3 vtbl members.

void _VtblGap7_3();

//[DispId(7)]

//MsoCTPDockPosition DockPosition { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(7)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(7)] set; }

//[DispId(8)]

//MsoCTPDockPositionRestrict DockPositionRestrict { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(8)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(8)] set; }

//[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(9)]

//void Delete();

}

[ComImport, Guid("000C033B-0000-0000-C000-000000000046")]

public interface CustomTaskPane : _CustomTaskPane

{

}

[ComImport, Guid("000C033D-0000-0000-C000-000000000046"), TypeLibType((short)0x10c0)]

public interface ICTPFactory

{

[return: MarshalAs(UnmanagedType.Interface)]

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)]

CustomTaskPane CreateCTP([In, MarshalAs(UnmanagedType.BStr)] string CTPAxID, [In, MarshalAs(UnmanagedType.BStr)] string CTPTitle, [In, Optional, MarshalAs(UnmanagedType.Struct)] object CTPParentWindow);

}

[ComImport, Guid("000C033E-0000-0000-C000-000000000046"), TypeLibType((short)0x10c0)]

public interface ICustomTaskPaneConsumer

{

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)]

void CTPFactoryAvailable([In, MarshalAs(UnmanagedType.Interface)] ICTPFactory CTPFactoryInst);

}

As you can see from the listing above, from position 5, I used a simpler form of the _VtblGap syntax to omit one vtable member. Note that it's enough to specify the number of vtable slots to reserve - it's not necessary to specify the position, because the position is taken from the position of the _VtblGap_YY declaration itself.

//void _VtblGap5_1();

void _VtblGap_1();

Note also that just because I can specify the position in the XX component, this does not allow me to rearrange the position of the _VtblGap declarations themselves. Given this, you might wonder why I bother with the XX in _VtblGapXX_YY, since it’s not necessary for the purposes of reserving correctly ordered vtable slots. The answer is that these _VtblGap entries all count as method declarations, and if I only use the YY component, there’s a good chance I’ll end up with a name conflict and the code will fail to compile. Using the XX component is just a convenience to avoid this problem. The _VtblGap syntax is documented in the Common Language Infrastructure Annotated Standard.

The pattern is similar for the Ribbon interfaces. Note that (as in the example in my previous post), I could simply omit the trailing members, but in this example I’ve chosen to explicitly reserve vtable space even though I’m not using these members and there are no members after these ones in the interface. The reason that preserving overall vtable size is encouraged is because there could theoretically be a consumer of the interface written in such a way that is dependent on the overall size of the vtable. This is pretty far-fetched these days – and in this specific example I’m ComImport-ing these interfaces in my own project which is not designed to be re-used by any other consumer. Nonetheless, it’s probably good practice, and does no harm.

[ComImport, Guid("000C0396-0000-0000-C000-000000000046"), TypeLibType((short)0x1040)]

public interface IRibbonExtensibility

{

[return: MarshalAs(UnmanagedType.BStr)]

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)]

string GetCustomUI([In, MarshalAs(UnmanagedType.BStr)] string RibbonID);

}

[ComImport, Guid("000C0395-0000-0000-C000-000000000046"), TypeLibType((short)0x1040)]

public interface IRibbonControl

{

[DispId(1)]

string Id { [return: MarshalAs(UnmanagedType.BStr)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)] get; }

// From position 2, we omit 2 vtbl members.

void _VtblGap2_2();

//[DispId(2)]

//object Context { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(2)] get; }

//[DispId(3)]

//string Tag { [return: MarshalAs(UnmanagedType.BStr)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(3)] get; }

}

The end-result of all this member omission is smaller code, which means a smaller working set, and likely better performance as a result. It also means less chance for bugs to be introduced and less code maintenance going forward.

The Case For Shared Add-ins

andreww — Sat, 10 May 2008 02:36:00 GMT

People have been building native shared add-ins for Office (and related apps) since their introduction in Office 2000. People have been building managed shared add-ins since the introduction of .NET in 2002. VSTO support for managed add-ins was introduced in 2005. It is clear that the strategic technology choice is managed code, and for Office add-ins it is VSTO. For a discussion of the main reasons why traditional managed add-ins (aka shared add-ins) are problematic – and how VSTO add-ins address these problems – see this MSDN article on the architecture of the original VSTO 2005 Outlook add-in support.

So, are shared add-ins dead? Not really: you still need shared add-ins in the following cases:

1. If you want (or need) a single add-in that targets multiple apps directly.

2. If you want (or need) to build in native code.

3. If you’re targeting Office versions prior to Office 2003.

4. If you’re targeting Office apps that VSTO doesn't support.

5. If you’re targeting non-Office apps that support the same COM add-in model (such as MapPoint).

6. If you want a very minimal runtime dependency apart from the CLR (and specifically want to avoid the overhead of the VSTO runtime).

Let’s examine each of these in turn. For #1, you can easily satisfy the requirement to target multiple hosts with VSTO add-ins by building simple app-specific shell add-ins which delegate all the real work to some common DLLs. This is likely to be a better architecture anyway – in terms of simplification of design, logical abstraction of functionality, functional separation of components, and component re-use.

For #2, it is true that developing in a native language such as C/C++ is more difficult (and more error-prone) than building in a managed language – and this is a significant factor in the success of VSTO, which only supports managed add-ins. However, there are several reasons why native code is often preferred, notably:

ú The organization may already have a large library of native domain-specific code that will be called by the add-in, and they don’t want to take the dev/test cost of calling out through p/invoke. The most commonly-quoted example is quants libraries used in Excel add-ins.

ú If the organization can completely control which add-ins are installed in the enterprise, they have the option to eliminate managed code from Office hosts. They might want to do this to avoid the admin overhead of deploying/managing the CLR, additional admin for managed code, and the perf (and working set) hit of loading the CLR into an Office process.

ú Apart from the up-front perf hit from loading the CLR, managed add-ins will generally perform slower than native add-ins – especially if they make chatty calls to the native host OM via the PIAs, because of the overhead inherent in COM interop.

You could argue that #3, #4 and #5 are really variations of the same constraint – the need to build an add-in for (a particular version(s) of) some (Office or non-Office) application that VSTO does not support. As we know (see here and here), you can morph a VSTO project for a supported application into a project for an unsupported one – but the key is that this is unsupported – and most enterprises and ISVs are justifiably reluctant to wander into unsupported territory.

#6 is almost a circular argument: you want to use a shared add-in because you don’t want to use the alternative (VSTO) add-in type. Nonetheless, it is a valid requirement. The VSTO runtime is relatively small (about 0.5 Mb runtime), but still bigger than the alternative. (The alternative “runtime” for managed add-ins is the COM shim, which is tiny in comparision to the VSTO runtime).

So, while issue #1 is not really a problem, the remaining 5 are. In mitigation, the landscape is changing. Specifically, you can expect to see VSTO supporting more and more applications in the future – certainly within the Office suite, and potentially outside also. Note, however, that this will not be retrospective – you’ll likely never see VSTO supporting apps prior to 2003, for example (this might technically work, but it wouldn’t be supported – because it is untested). Bottom line: there are cases where you cannot use VSTO and you must therefore use shared add-ins, and this will likely always be true.

Delay-loading the CLR in Office Add-ins

andreww — Sat, 19 Apr 2008 21:53:00 GMT

Suppose you control your enterprise desktops to the extent that you control which add-ins are installed. Suppose, further, that you want to avoid the hit of loading the CLR at application startup. One way is to delay-load your managed add-ins. The registered LoadBehavior for an Office add-in governs how the add-in is loaded (surprise). Note these values are in decimal:

LB	Meaning	Status in COM Add-ins Dialog	Behavior Description
0	Unloaded	Disconnected, Unloaded	The add-in is not loaded when the application starts. It can be loaded through the COM Add-ins dialog box or programmatically, but reverts to “Unloaded” when the application closes.
1	Loaded	Disconnected, Loaded	The add-in is not loaded when the application starts (despite the status of “Loaded”). It can be loaded through the COM Add-ins dialog box or programmatically, but reverts to “Loaded” when the application closes.
2	Boot-Loaded	Disconnected, Load at Startup	The add-in is not loaded when the application starts. It can be loaded through the COM Add-ins dialog box or programmatically. Once the add-in is loaded, it remains loaded until it is explicitly unloaded, that is LoadBehavior is set to 3, and this status is persisted in the registry across sessions.
3	Boot-Loaded	Connected, Load at Startup	The add-in is loaded when the application starts. It remains loaded until it is explicitly unloaded.
8	Demand-Loaded	Disconnected, Load on Demand	The add-in will be loaded and connected when the host application requires it, eg, when a user clicks on a button that uses functionality in the add-in, that is LoadBehavior is set to 9.
9	Demand-Loaded	Connected, Load on Demand	The add-in will be loaded and connected when the host application requires it, eg, when a user clicks on a button that uses functionality in the add-in.
16	Connect First Time	Connected, Load on Demand (currently loaded)	The add-in loads as soon as the application starts the first time after the add-in is registered. Typically, the add-in creates a button or menu item for itself. The next time the user starts the application, the add-in is loaded on demand (LB=8), that is, it doesn't load until the user clicks the button or menu item associated with the add-in. This sets the LoadBehavior to 9.

Let’s say you have a number of managed add-ins, and you want to be able to defer (or even completely avoid) loading them until you’re sure that they are needed in the current session. For example, let’s say that your Excel users sometimes work with workbooks that you care about – perhaps these workbooks have some custom property that identifies them as being part of some solution. Sometimes the users work on workbooks that are not part of any enterprise solution. If, during a session, the user only works on workbooks you don’t care about, you want to avoid loading any managed add-ins. In this way, the users avoid the perf hit of loading the CLR unless the custom functionality in your managed add-ins is actually required.

You can use the standard Office delay-load mechanism as noted in the LoadBehavior table above. The constraint here is that you’re dependent on some user action to notify Office that it needs to load the add-in, and that might not fit your requirements.

Another way you could achieve this is to build a native add-in that performs the test of whether or not to load the managed add-ins (and therefore, the CLR). For example, this could examine each workbook (or document in Word, presentation in PowerPoint, etc) that the user opens, to decide whether or not to load the managed add-ins.

The required operations for this mechanism are pretty simple. Each Office application exposes its collection of registered add-ins in a COMAddIns collection. In this collection, each add-in is represented by a COMAddIn object – this is true for all registered add-ins, regardless of whether the add-in is actually loaded or unloaded (and regardless of its LoadBehavior value). The COMAddIn interface exposes a number of properties, of which two are particularly interesting in this context:

· The Object property, which represents any arbitrary object that your add-in wants to expose for external automation. See my post on RequestComAddInAutomationService for more details of this.

· The Connect property, which represents the connected state of the add-in: true=connected, false=registered but disconnected. Note that for VSTO add-ins, if the add-in is not connected it’s also not loaded (and the runtime has not created an appdomain for it).

So, to defer or avoid loading the CLR, you can build a native add-in that conditionally sets the Connect property on your managed add-in(s).

To test this out, I created a Shared Add-in in C++. In the stdafx.h, I added #imports for the Office and Excel typelibs (my add-in targets Excel):

// Import the latest Office type library based on its registration.

#import "libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52" \

named_guids, auto_search, auto_rename, \
rename("_IID_Adjustments", "Office_IID_Adjustments")

using namespace Office;

// Latest registered Excel typelib.

#import "libid:00020813-0000-0000-C000-000000000046" \

auto_search, auto_rename

using namespace Excel;

Then, I replaced the declaration of the generic IDispatch smart pointer that the shared add-in project gives you for the application object with an Excel-OM Application smart pointer, that is, changed this:

CComPtr<IDispatch> m_pApplication;

…to this:

Excel::_ApplicationPtr m_spExcel;

…and initialized it in the OnConnection method from the incoming IDispatch* (the smart pointer assignment performs a QI for me):

m_spExcel = pApplication;

Note that I could have used the IDispatch pointer and late binding to get the COMAddIns collection, but it’s just easier to use strong typing. The only other significant task was to provide behavior to connect and disconnect my target VSTO add-in(s). In this example, the VSTO add-in I want to control has a registered ProgID of “VstoExcelAddIn”:

// Get the VstoExcelAddIn from the COMAddIns collection.

Office::COMAddInPtr spCOMAddIn;

CComVariant vtItem("VstoExcelAddIn");

spCOMAddIn = m_spExcel->COMAddIns->Item(&vtItem);

// Toggle the connected state of the add-in.

VARIANT_BOOL bOldState = spCOMAddIn->Connect;

if (bOldState == VARIANT_TRUE)

{

spCOMAddIn->Connect = VARIANT_FALSE;

}

else

{

spCOMAddIn->Connect = VARIANT_TRUE;

}

Of course, you still have to write the code that determines whether or not you want to connect/disconnect the add-in (and potentially, which add-in or add-ins you want to control). You might do this based on some custom document property – and that would require you to sink the WorkbookOpen/WorkbookBeforeClose events, and possibly the WindowActivate/Deactivate events. Or, it might be based on the current user account name and/or domain. Or, on the day of the week, or any other arbitrary condition.

So, if you want to control VSTO add-ins, you can simply build a native add-in to control them, as described above. If, on the other hand, you want to control non-VSTO managed add-ins, you could eithr use a native add-in in the same way – or alternatively, you could build this controlling functionality into your native shim. Note that this technique is not restricted to add-ins – you can build the same functionality into any of the native shims that the COM Shim Wizard supports – including managed smart tags, real-time data components, and automation add-ins.

Implement ICustomTaskPaneConsumer in C++

andreww — Wed, 05 Dec 2007 08:04:00 GMT

The new extensibility interfaces introduced in Office 2007 are implementable via add-ins. Add-ins can be managed or unmanaged (native). If you're using VSTO, development is greatly simplified. However, if you want to build a native add-in to implement one of these interfaces, life is a little more complex – and there doesn't seem to be any documentation on how to do this. What follows here is an exploration of how to build a native (C++ ATL) "shared" COM add-in that implements a custom task pane. You'll see that it's pretty straightforward.

Note: I used VS 2008 to build this example, but the same approach will work with VS 2005.

To start, create a new Shared Add-in project, and select Visual C++/ATL as the target language. Specify a suitable Office host(s) for your add-in (I used Excel) – the remaining wizard options are self-explanatory. The interesting work comes after you've finished the wizard and you have a skeleton add-in project. The tasks required are:

· Use the Implement Interface Wizard to implement the ICustomTaskPaneConsumer interface.

· Clean up the wizard-generated implementation slightly.

· Add an ActiveX control to your project, for use in the task pane.

· Implement ICustomTaskPaneConsumer::CTPFactoryAvailable to create the task pane, using the specified ActiveX control.

The first thing to do is to implement the ICustomTaskPaneConsumer interface. To do this, in Class View, right-click on the CConnect class, and select Add | Implement Interface. In the Implement Interface Wizard, select the Microsoft Office 12.0 Object Library <2.4> from the list of available type libraries. If this typelib doesn't show up in the list, you can choose to implement interfaces from a specific file instead – and specify the path to the Office 2007 version of MSO.DLL as the location:

From the list of interfaces exposed in the Office typelib, select ICustomTaskPaneConsumer (double-click it, or select it and click the ">" arrow to add it to the list). This will update your CConnect class to implement ICustomTaskPaneConsumer, as shown below:

class ATL_NO_VTABLE CConnect :

public CComObjectRootEx<CComSingleThreadModel>,

public CComCoClass<CConnect, &CLSID_Connect>,

public IDispatchImpl<AddInDesignerObjects::_IDTExtensibility2, &AddInDesignerObjects::IID__IDTExtensibility2, &AddInDesignerObjects::LIBID_AddInDesignerObjects, 1, 0>,

public IDispatchImpl<ICustomTaskPaneConsumer, &__uuidof(ICustomTaskPaneConsumer), &LIBID_Office, 2, 4>

{

public:

CConnect()

{

}

DECLARE_REGISTRY_RESOURCEID(IDR_ADDIN)

DECLARE_NOT_AGGREGATABLE(CConnect)

BEGIN_COM_MAP(CConnect)

COM_INTERFACE_ENTRY2(IDispatch, ICustomTaskPaneConsumer)

COM_INTERFACE_ENTRY(AddInDesignerObjects::IDTExtensibility2)

COM_INTERFACE_ENTRY(ICustomTaskPaneConsumer)

END_COM_MAP()

DECLARE_PROTECT_FINAL_CONSTRUCT()

HRESULT FinalConstruct()

{

return S_OK;

}

void FinalRelease()

{

}

public:

//IDTExtensibility2 implementation:

STDMETHOD(OnConnection)(IDispatch * Application, AddInDesignerObjects::ext_ConnectMode ConnectMode, IDispatch *AddInInst, SAFEARRAY **custom);

STDMETHOD(OnDisconnection)(AddInDesignerObjects::ext_DisconnectMode RemoveMode, SAFEARRAY **custom );

STDMETHOD(OnAddInsUpdate)(SAFEARRAY **custom );

STDMETHOD(OnStartupComplete)(SAFEARRAY **custom );

STDMETHOD(OnBeginShutdown)(SAFEARRAY **custom );

CComPtr<IDispatch> m_pApplication;

CComPtr<IDispatch> m_pAddInInstance;

// ICustomTaskPaneConsumer Methods

public:

STDMETHOD(CTPFactoryAvailable)(ICTPFactory * CTPFactoryInst)

{

return E_NOTIMPL;

}

};

Depending on whether you imported the typelib based on its registration or its path, the Wizard will also add one of the following two lines to your stdafx.h (ignore the text wrapping here – each #import statement is all on one line without linebreaks):

// Import the Office 12 type library based on its path.

#import "C:\Program Files (x86)\Common Files\microsoft shared\OFFICE12\MSO.DLL" raw_interfaces_only, raw_native_types, no_namespace, named_guids, auto_search

// Import the Office 12 type library based on its registration.

#import "libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52" version("2.4") lcid("0") raw_interfaces_only raw_native_types, no_namespace, named_guids, auto_search

For consistency, change the wizard-generated full function implementation in the .h file, from this:

STDMETHOD(CTPFactoryAvailable)(ICTPFactory * CTPFactoryInst)

{

return E_NOTIMPL;

}

… to a simple declaration, like this:

STDMETHOD(CTPFactoryAvailable)(ICTPFactory * CTPFactoryInst);

... and add the skeleton implementation to the .cpp file instead:

STDMETHODIMP CConnect::CTPFactoryAvailable (ICTPFactory * CTPFactoryInst)

{

return E_NOTIMPL;

}

Also, you might need to modify the #import statement to avoid some name clashes, as shown below. Note: because the list of clashes can be quite long, I've put line breaks in the #import statement in this example:

#import "libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52" version("2.4") lcid("0") \

raw_interfaces_only raw_native_types, no_namespace, named_guids, auto_search \

rename("DocumentProperties", "msoDocumentProperties") \

rename("RGB", "msoRGB") \

rename("IAccessible", "msoIAccessible")

Before you can instantiate a custom task pane, you need a control to put in it. You can use any registered ActiveX control. For simplicity, you can define a new one in your add-in project. To do this, in Class View, right-click on the add-in project, and select Add | Class. From the Add Class dialog, select ATL Control. In the ATL Control Wizard, type in a suitable name (eg, SimpleControl):

When you click Finish, the wizard will generate all the necessary code for a simple ActiveX control. Note the OnDraw implementation, which draws a rectangle and displays a simple string:

HRESULT OnDraw(ATL_DRAWINFO& di)

{

…

LPCTSTR pszText = _T("ATL 8.0 : SimpleControl");

TextOut(di.hdcDraw,

(rc.left + rc.right) / 2, (rc.top + rc.bottom) / 2,

pszText, lstrlen(pszText));

…

}

With a suitable ActiveX control, you can now implement the CTPFactoryAvailable function to create a new custom task pane using the control. The first parameter to CreateCTP is the ProgId or CLSID of the ActiveX control. The second parameter is the title to use for the task pane. The third parameter is the IDispatch interface pointer of the parent window. The parent window is only useful in the case of Outlook, where it is the window for the Inspector or Explorer where you want the task pane to appear. In the simple case, you can 'omit' the parent window argument. To 'omit' the arg, you can't just pass NULL. Instead, you should set up a VARIANTARG of type VT_ERROR, with its value set to DISP_E_PARAMNOTFOUND. The fourth parameter is the address of the _CustomTaskPane interface pointer to be filled in by the call:

STDMETHODIMP CConnect::CTPFactoryAvailable (ICTPFactory * CTPFactoryInst)

{

_CustomTaskPane* pTaskPane = NULL;

HRESULT hr = S_OK;

VARIANTARG vargParentWindow;

vargParentWindow.vt = VT_ERROR;

vargParentWindow.scode = DISP_E_PARAMNOTFOUND;

hr = CTPFactoryInst->CreateCTP(

CComBSTR(L"NativeTaskpaneAddIn.SimpleControl"),

CComBSTR(L"Contoso"), vargParentWindow, &pTaskPane);

if (SUCCEEDED(hr))

{

hr = pTaskPane->put_Visible(TRUE);

}

return hr;

}

Set the debug properties of the add-in to specify the path to the Office host application to use as the debug command, and press F5 to build and run:

With the increasing coverage of VSTO for add-ins of all types and for most Office applications, the need to build Shared add-ins is lessening. However, if you need to build an unmanaged add-in, this is still your only option.

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