Andrew Whitechapel : PIAs

Version-Specific UI in Add-ins

andreww — Wed, 03 Sep 2008 03:12:00 GMT

Continuing on from my earlier posts on building add-ins for multiple versions of Office, avoiding the PIA version conflict, and add-ins for multiple versions without PIAs, a reasonable way to design your solution would be to use the lowest-common-denominator PIAs (let’s say, the Office 2003 PIAs) and then use ComImports for any additional features introduced in later versions of Office. This way, you avoid having to declare ComImports for the vast majority of the Office and Office app object models, since you can generally rely on Office maintaining close to 100% backward compatibility within the core features. The changes in the Office OMs, as new versions are released, tend to be almost completely additive.

This model also means that even though you reference say the Office 2003 PIAs in your solution at design-time, when it comes to runtime, your add-in will run against whatever PIAs are registered on the machine. In other words, you can expect that on an Office 2003 machine, your add-in will run with the Office 2003 PIAs – and on an Office 2007 machine, your add-in will run with the Office 2007 PIAs. This is, of course, exactly the behavior you want. Moreover, it doesn’t require you to stray into unsupported territory by deploying multiple PIA versions on a machine with only one Office version, or building an Office 2003 add-in that references the Office 2007 PIAs, or any other dodgy behavior.

I’m attaching the sample solution to this post, and here’s what it looks like in VS:

As you can see, I have 3 projects:

- An Excel 2003 add-in.

- A class library that implements Office 2003 UI (CommandBar-based features), and that references the Office 2003 PIA.

- A class library that implements Office 2007 UI (custom task pane and Ribbon-based), and that does NOT reference the Office PIA, but instead uses ComImports to declare the Office interfaces I’m using (ICustomTaskPaneConsumer, IRibbonExtensibility, etc).

Here’s how they fit together:

As before, the ThisAddIn class is split into 4 partial classes:

- The “hidden” wizard-generated part of the partial class (in ThisAddIn.designer.cs), that you don’t normally want to edit.

- The usual “visible” part of the class (in ThisAddIn.cs). In this example, this contains code commonly shared regardless of Office version, specifically the Startup and Shutdown behavior.

- A part of the class containing code specific to Office 2003 (in ThisAddIn2003.cs). This uses the Ui2003 class library to implement custom CommandBar-based UI.

- A part of the class containing code specific to Office 2007 (in ThisAddIn2007.cs). This uses the Ui2007 class library to implement custom task pane and Ribbon UI.

When the add-in is loaded, in ThisAddIn_Startup, it checks to see which version of the Office host it is running in: if it’s running in Office 2003, it branches out to initialize the CommandBar-based UI.

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

{

// 2003: If we're running in 2003, setup a custom commandbar menu.

if (Application.Version == "11.0")

{

Initialize2003Ui();

}

The part of the partial class in ThisAddIn2007.cs contains an override of RequestService, which will not be called in Office 2003. Therefore, if RequestService is called, we can assume we’re running in Office 2007 (or later), and can therefore set up custom task pane and Ribbon UI.

So, the solution only references one version of the Office PIAs (the LCD version), and uses ComImport declarations for the OM features that are not in that version. Then, at runtime, the correct version of the PIAs are loaded that match the running version of Office. I could take this further, and dispense with the PIAs altogether, using ComImports for everything – but that’s normally unnecessary, as you can generally rely on the PIAs being installed, or you can pre-req them as part of the install for your solution. Plus, I don’t really want to re-declare vast tracts of the Office OM unless I really have to. This model provides an optimal solution: using the PIAs for the core Office behavior that does not change between versions, and using ComImports for the additional features added in later versions.

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.

Add-ins for Multiple Office Versions without PIAs

andreww — Tue, 03 Jun 2008 19:47:00 GMT

In a previous post, I discussed how you could build an add-in for multiple versions of Office, and explained the problems in this approach (and why it is not officially supported). One of the reasons this is not supported is because you end up building an add-in which has dependencies on a later version of the Office PIAs, even though your add-in is sometimes deployed to a machine with an earlier version of Office. The canonical example is where you build an add-in that conditionally uses both Office 2003 (and earlier) CommandBar technology and Office 2007 (and later) Ribbon and task pane technologies, as described in my earlier post. This add-in would normally have a dependency on the Office 2007 PIAs (where the IRibbonExtensibility and ICustomTaskPaneConsumer types are declared). When deployed to an Office 2007 machine, all is good, because the Office 2007 PIAs are present. However, when deployed to an Office 2003 machine – even though the Ribbon and task pane functionality is not used, it is still in the add-in code, and therefore still requires the Office 2007 PIAs. Is there a way around this problem?

Of course, one solution is to deploy the Office 2007 PIAs to the machine with Office 2003, but you then have the follow-on problems of registering multiple versions of the PIAs, and of loading the Office 2007 PIAs into an Office 2003 process. Not good.

Another way around this problem is to remove the dependency on the later PIAs. Because of the high degree of backwards compatibility in Office, you can safely assume that if your add-in works on Office 2003 (with the Office 2003 PIAs), then it should also work on Office 2007 (with the Office 2007 PIAs). So, the only issue is how to get it to work on an Office 2003 machine with only the Office 2003 PIAs present, even though your code uses types such as IRibbonExtensibility that are not present in Office 2003 or the Office 2003 PIAs. So, the question becomes, How can you write a solution which uses types defined in an assembly (the Office 2007 PIA) that is not referenced by the solution?

The answer, of course, is ComImport. For documentation on ComImport, see here and here. PIAs, and interop assemblies generally, can be created by using the Tlbimp.exe utility, which reads a type library and outputs an interop assembly, containing metadata that is the managed equivalent of the COM typelib. ComImport is a pseudo-custom attribute that indicates that a type has been defined in a previously published type library. You can apply this attribute when you want to generate interop metadata manually in source code that simulates the metadata produced by Tlbimp.exe.

Here’s an example. Note that I’m declaring an inner namespace “Office”, so that I can refer to the task pane and Ribbon types as if they were declared in the same namespace as the real Office types – that is, assuming the standard using statement with an alias, eg: using Office = Microsoft.Office.Core;.

Taking custom task panes first, note that ICustomTaskPaneConsumer has a member that takes an ICTPFactory object as a parameter. I therefore have to define ICTPFactory as well. ICTPFactory in turn has a member that takes a CustomTaskPane object, and this derives from _CustomTaskPane, so I need to define these two interfaces also. With Ribbons, the IRibbonExtensibility interface is straightforward, but the signatures of the callback methods that I must define for Office to use for my Ribbon controls tend to take IRibbonControl objects as parameters, so I need to define this interface also.

namespace MyOffice2003AddIn

{

namespace Office

{

#region Custom Task Pane

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; }

[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)]

[DispId(4)]

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

[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)]

[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)]

}

[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);

}

#endregion

#region Ribbon

[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; }

}

#endregion

}

How do I arrive at these ComImport declarations? One way is to use the ildasm.exe utility to read the Office 2007 PIA (that is, Office.dll) to get the metadata, although this approach requires you to do further work to massage the metadata into the appropriate code definitions. Another way is to use Lutz Roeder’s Reflector, and this approach pretty much provides you the code definitions without any further work. It should go without saying that it is essential to get the correct GUIDs on each of the types.

With these interface type definitions in place, I can use normal expressions in my add-in code to implement custom task panes and Ribbons. For example, I can implement ICustomTaskPaneConsumer like this:

public class TaskPaneImpl : Office.ICustomTaskPaneConsumer

{

private Office.ICTPFactory ctpFactory;

internal Office.CustomTaskPane ctp;

public void CTPFactoryAvailable(Office.ICTPFactory CTPFactoryInst)

{

try

{

ctpFactory = CTPFactoryInst;

ctp = ctpFactory.CreateCTP(

"MyOffice2003AddIn.SimpleControl",

"SimpleControl", Type.Missing);

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

...and I can implement IRibbonExtensibility as shown below. Note that I have to add the Ribbon customization code manually – because this is an Office 2003 add-in, and Visual Studio won’t allow me to add a wizard-generated Ribbon item to an Office 2003 project. This code assumes I have a simple RibbonX.xml resource which defines one ToggleButton.

[ComVisible(true)]

public class RibbonX : Office.IRibbonExtensibility

{

public string GetCustomUI(string ribbonID)

{

return Properties.Resources.RibbonX;

}

public void OnToggleTaskPane(

Office.IRibbonControl control, bool isPressed)

{

Globals.ThisAddIn._taskPane.ctp.Visible = isPressed;

}

..and then I can use these implementations in my add-in like this:

public partial class ThisAddIn

{

internal TaskPaneImpl _taskPane;

private RibbonX _ribbon;

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.ICustomTaskPaneConsumer).GUID)

{

if (_taskPane == null)

{

_taskPane = new TaskPaneImpl();

}

return _taskPane;

}

else if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)

{

if (_ribbon == null)

{

_ribbon = new RibbonX();

}

return _ribbon;

}

return base.RequestService(serviceGuid);

}

Using this approach means that I no longer need to reference the Office 2007 PIAs in my add-in, which allows my add-in to work on an Office 2003 machine as well as on an Office 2007 machine, without having to deploy Office 2007 PIAs to the Office 2003 machine.