Andrew Whitechapel : VSTO Add-ins

HLSL in Office

andreww — Wed, 22 Jul 2009 23:55:00 GMT

HLSL is the High Level Shading Language for DirectX, documented here. I was wondering the other day how you might use shaders in Office, and this led me to build a little proof-of-concept that allows you to experiment with HLSL within the context of an Office application. I built a PowerPoint add-in that provides a custom task pane which displays a WPF usercontrol. The task pane allows the user to select an image file, type in arbitrary HLSL code to build a shader, and apply that shader to the image before inserting it into the slide. Here’s a screenshot:

The user can type in any HLSL they like, and hit the Run button to apply the resulting shader to the image. My prototype has 2 projects: a WPF UserControl, and a VSTO PowerPoint 2007 add-in. The UserControl visuals are pretty straightforward: as you can see from the screenshot, I have an Image control, a TextBox for the HLSL source-code, 3 Buttons, and another TextBox for any diagnostic output. Note that I wrap my Image control in a Border to workaround the offsetting issue described in Jaime Rodriguez’s post:

</Border>

My 3 Button Click handlers open an image file, compile the HLSL source into a shader, and insert the resulting image into the slide, respectively. The Open handler is very simple – it just displays an OpenFileDialog and then sets the user’s image selection into the Image control:

private void buttonOpen_Click(object sender, RoutedEventArgs e)

{

OpenFileDialog dlg = new OpenFileDialog();

dlg.Filter = "Images|*.jpg;*.png;*.bmp;*.gif|All Files|*.*";

if (dlg.ShowDialog() == true)

{

ImageSource.Source = new BitmapImage(new Uri(dlg.FileName));

}

The Run handler is a little more involved. First, I get the HLSL source-code, and write it out to a temporary file on disk:

private void buttonRun_Click(object sender, RoutedEventArgs e)

{

string codePath = System.IO.Path.GetTempFileName();

using (FileStream stream =

new FileStream(codePath, FileMode.Create))

{

byte[] data = Encoding.ASCII.GetBytes(HlslSource.Text);

stream.Write(data, 0, data.Length);

}

Then, I get the path to the DirectX effect compiler (fxc.exe). To figure out where this is on the filesystem, I have a couple of choices. I could get the InstallPath for the DirectX SDK from the registry, as a versioned sub-key of [HKLM\software\Microsoft\DirectX]. Alternatively (and more simply), I can fetch the DXSDK_DIR environment variable. With this path, I can set up a Process object to launch the compiler, and pass in the path to the new HLSL source file, again saving the output to a temporary file:

string fxcPath = System.IO.Path.Combine(

Environment.GetEnvironmentVariable("DXSDK_DIR"),

"Utilities\\bin\\x86\\fxc.exe");

ProcessStartInfo startInfo = new ProcessStartInfo(fxcPath);

startInfo.CreateNoWindow = true;

startInfo.UseShellExecute = false;

startInfo.RedirectStandardError = true;

string shaderPath = System.IO.Path.GetTempFileName();

startInfo.Arguments = String.Format(

"/T ps_2_0 /E main /Fo\"{0}\" \"{1}\"",

shaderPath, codePath);

When I start the effect compiler process, I’ll handle any error output by displaying it nicely in my diagnostic TextBox. If there were no errors, I can set up a new pixel shader from the compiled HLSL, and apply it to the selected image.

using (Process proc = Process.Start(startInfo))

{

proc.WaitForExit();

StreamReader reader = proc.StandardError;

string errors = reader.ReadToEnd();

if (!String.IsNullOrEmpty(errors))

{

string errorMessage =

errors.Replace(codePath, "Line ");

string[] messageParts = errorMessage.Split(':');

if (messageParts.Length == 3)

{

CompilerOutput.Text = String.Format(

"{1}{0}{2}{0}{3}",

Environment.NewLine,

messageParts[0].Trim(),

messageParts[1].Trim(),

messageParts[2].Trim());

}

else

{

CompilerOutput.Text = errorMessage;

}

else

{

PixelShader pixelShader = new PixelShader();

pixelShader.UriSource = new Uri(shaderPath);

CustomShaderEffect shaderEffect =

new CustomShaderEffect(pixelShader);

ImageSource.Effect = shaderEffect;

CompilerOutput.Text = "Effect applied successfully.";

}

Note that I’m using a custom ShaderEffect class. You can derive from the ShaderEffect class to implement a custom effect based on a single pixel shader, as documented here.

The Insert handler uses RenderTargetBitmap and PngBitmapEncoder to create a bitmap from the image and save it to a PNG-format temporary file on disk:

private void buttonInsert_Click(object sender, RoutedEventArgs e)

{

try

{

RenderTargetBitmap renderTarget = new RenderTargetBitmap(

(int)ImageBorder.ActualWidth,

(int)ImageBorder.ActualHeight,

96, 96, PixelFormats.Pbgra32);

renderTarget.Render(ImageBorder);

PngBitmapEncoder encoder = new PngBitmapEncoder();

encoder.Frames.Add(BitmapFrame.Create(renderTarget));

string imagePath = System.IO.Path.GetTempFileName();

using (FileStream stream =

new FileStream(imagePath, FileMode.Create))

{

encoder.Save(stream);

}

ImageEventArgs ie = new ImageEventArgs(imagePath);

if (ImageSavedEvent != null)

{

ImageSavedEvent(sender, ie);

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

You can see from the foregoing that when I’ve saved the final image, I fire a custom event. This is because I’ll be using my WPF UserControl within the context of an Office custom taskpane, and I want my Office add-in code to be notified when the image has been successfully processed. So, I have a custom ImageEvent event type, and corresponding custom ImageEventArgs type. I declare an ImageEvent as an event field in my UserControl class. Then, at the end of the Insert handler above, I fire this event.

public delegate void ImageEvent(object source, ImageEventArgs e);

public class ImageEventArgs : EventArgs

{

public String ImagePath;

public ImageEventArgs(String name)

{

ImagePath = name;

}

public partial class HlslControl : UserControl

{

public event ImageEvent ImageSavedEvent;

// …etc as above.

Next, I create a VSTO PowerPoint add-in project, and add a reference to my WPF UserControl project. I also add a custom Ribbon with one Button: the Button handler simply toggles the visibility of my custom task pane. To create the custom task pane, I create a (Windows Forms) UserControl in my add-in project, add a Windows.Forms.Integration.ElementHost, fully-docked. I set the ElementHost.Child to a new instance of my WPF UserControl, and sink the custom ImageSavedEvent. In the event handler, I call out to a custom InsertImage method in my main add-in class:

public partial class HlslTaskPane : UserControl

{

WpfControls.HlslControl hlslControl;

public HlslTaskPane()

{

InitializeComponent();

this.hlslControl = new WpfControls.HlslControl();

this.hlslControl.ImageSavedEvent += new WpfControls.ImageEvent(hlslControl_ImageSavedEvent);

this.elementHost.Child = this.hlslControl;

}

void hlslControl_ImageSavedEvent(object source, WpfControls.ImageEventArgs e)

{

Globals.ThisAddIn.InsertImage(e.ImagePath);

}

The custom InsertImage method in my add-in class gets hold of the current presentation, and adds a new slide. Then, I insert the image into the slide:

public void InsertImage(string imagePath)

{

PowerPoint.Slides slides =

this.Application.ActivePresentation.Slides;

PowerPoint.Slide slide = slides.Add(slides.Count + 1,

PowerPoint.PpSlideLayout.ppLayoutBlank);

PowerPoint.Shapes shapes = slide.Shapes;

shapes.AddPicture(

imagePath,

Office.MsoTriState.msoFalse,

Office.MsoTriState.msoTrue,

10, 10, 240, 180);

slide.Select();

}

That’s it. Bear in mind this is a simple proof-of-concept exercise, not production code, and I’ve taken a number of short-cuts. For instance, I’m not too happy about saving temporary files to disk, but this approach is partly forced on me by my choice of technologies (WPF and Windows Forms, managed code and native Office) and tools (fxc.exe). The project also serves as a useful experimentation pad for learning HLSL. If you’re serious about shaders, you’ll probably want to look at the Shazzam tool, the WPF Pixel Shader Effects Library, and the Shader Effects BuildTask and Templates.

MEF in Office?

andreww — Wed, 08 Apr 2009 03:14:00 GMT

In my last post, I looked briefly at MEF, and I’m wondering how this model can be applied to Office add-ins. The Office add-in model itself already achieves a level of dynamic composition, by virtue of the fact that the set of add-ins to be loaded is only discovered at runtime. However, even though the model is similar at a high level, Office itself does not use MEF.

Nonethless, MEF could perhaps be useful in an Office context. For example, suppose you want to build the add-in itself as a composite. That is, suppose your total add-in functionality is made up of components – and furthermore, you want to discover these components at runtime, instead of statically linking them at design-time.

In this post, I’ll translate the simple console MEF app from my previous post to an Office add-in.

This turned out to be remarkably easy. I used the same ‘Interface’ assembly, the same ‘Implementation’ assembly, and the same ‘Alternate’ implementation assembly. The only difference was that I built a VSTO add-in instead of a console app. This is the code in my add-in class:

[Import]

public Interface.ICalculate Calculate { get; set; }

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

{

DirectoryCatalog catalog =

new DirectoryCatalog(

AppDomain.CurrentDomain.BaseDirectory);

CompositionContainer container =

new CompositionContainer(catalog);

CompositionBatch batch = new CompositionBatch();

batch.AddPart(this);

container.Compose(batch);

}

internal void GetCircumference()

{

double d = (double)this.Application.ActiveCell.Value2;

this.Application.ActiveCell.get_Offset(0, 1).Value2 =

Calculate.Circumference(d);

}

As you can see, the code is almost identical to what I had in my console app. The difference here is that I split up the composition from the method invocation. I set up the catalog and CompositionContainer and perform the composition on startup, but I defer actually invoking the imported method until the user clicks my custom Ribbon button:

public partial class RibbonX : OfficeRibbon

{

public RibbonX()

{

InitializeComponent();

}

private void RibbonX_Load(object sender, RibbonUIEventArgs e)

{

}

private void buttonCircumference_Click(

object sender, RibbonControlEventArgs e)

{

Globals.ThisAddIn.GetCircumference();

}

As before, this works with either my first implementation of the contract, or the alternate version.

One obvious question that springs to mind is, “can this model be used to mitigate the versioning problem in Office?”. Specifically, for example, could you use this model to build an add-in that dynamically composes components that implement either 2003-style CommandBar UI or 2007-style Ribbon/TaskPane UI? The answer is, No, probably not in any useful way. If you think about it, at the core of the MEF model is the contract: the model relies on the contract being the ‘fixed’ point in the moving constellation of composable parts. In the CommandBar vs Ribbon scenario, the contract is not fixed – you’re either using CommandBar interfaces or you’re using Ribbon/TaskPane interfaces.

You can perhaps envisage an imaginary IOfficeUi interface, which one component might implement to render commandbars while another component implements the same interface to render ribbons – but this is an imaginary scenario, and it does not map to the reality of Office versioning. Where the Office add-in scenario does map to the MEF model is in the composability of add-ins – because all add-ins must implement IDTExtensibility2, and they can implement it in arbitrarily different ways (within some constraints). However, back to what I said at the top of the post – this is conceptually similar to the MEF model, but does not use MEF.

All right, then, you’re thinking – why can’t we devise such an IOfficeUi interface for use between our add-in and composable parts that implement this differently? Well, of course, we could do this – but not in any useful way. Imagine what you’d need to build… Because of the way Office uses the new optional extensibility interfaces (IRibbonExtensibility, ICustomTaskPaneConsumer, etc), your add-in must advertise that it either does or does not implement these interfaces very early on in its lifetime – very soon after it is loaded. If you don’t tell Office up front that you implement these interfaces, you’ll never get called back on them. So, even if you build an Office 2003 add-in (which does not use these interfaces), you’d still be obliged to implement them in case you’re actually running in Office 2007 or later.

Moreover, the imaginary IOfficeUi interface would probably end up being very generic – plus you’d have the problem of how to communicate between the UI and the business logic in your solution. You’d end up with some hopelessly generic interfaces like this:

public interface IOfficeUi

{

// In Initialize, construct CommandBars or Ribbon/TaskPane.
void Initialize(object addIn);

IBusinessLogic BusinessLogic { get; set; }

}

public interface IBusinessLogic

{

// In InvokeMethod, invoke business logic from the UI event handlers.
object InvokeMethod(string methodID, params object[] args);

IOfficeUi OfficeUi { get; set; }

}

This is not really a workable model. So, for the UI versioning case, the only really workable approach is to componentize along the lines of my post here, using the lowest-common denominator but implementing later interfaces. MEF doesn’t help you in this scenario.

Silverlight Deep Zoom and Office Add-ins

andreww — Sun, 08 Mar 2009 06:04:00 GMT

I had some ‘free’ time today waiting to give a demo at an MVP conference session – the session over-ran, and I found myself sitting in the hallway for an hour. So I got to thinking about Silverlight and Office. If we assume that Silverlight is more or less a subset of WPF, then it makes little sense to build any Silverlight into an Office add-in: you’ve already got the regular CLR loaded, so why would you want to load a second CLR with a subset of the capabilities? Plus, there’s the performance consideration – Silverlight apps are browser-hosted, so communicating between the SL app and the rest of your solution incurs a perf penalty.

Well, I thought of a couple of possible arguments…

If you can do everything you need to do with Silverlight instead of WPF, then you might actually save some working set – since WPF is bigger than SL. Think about it: if you’re not using WPF, then you don’t have the WPF assemblies loaded. Silverlight’s coreclr + agcore + npctl = approx 2.5Mb. On the other hand, WPF’s PresentationCore + PresentationFramework + WindowsBase + WindowsFormsIntegration = approx 3.7Mb. Not a terribly convincing argument, but still.

Then there are some features that Silverlight supports that WPF doesn’t. Deep Zoom, for example. It might be difficult to imagine a use for Deep Zoom in the context of an Office add-in – but not impossible. Excel, for example, has a range of data visualization capabilities (charting, conditional formatting, heat-maps), but wouldn’t it be nice to use some Deep Zoom-like feature for pivot table drill-downs for instance? There are other features in Silverlight (and not currently supported in WPF) that might be more obviously useful in Office (specifically, the DataGrid control and the VisualStateManager), but remember this was a hallway exercise – and I like Deep Zoom.

So, I built a little proof-of-concept managed Office add-in with a custom task pane that hosts a WebBrowser control, which in turn hosts a Silverlight app. I used the Deep Zoom Composer (available for free download here) to generate the image pyramid. The Deep Zoom Composer is a very nice tool that saves an awful lot of effort in building image pyramids. It also has a very handy ‘Export to Silverlight project’ feature, which creates an entire Silverlight app solution complete with the Silverlight project itself plus an ASP.NET web app (in case you want to host the app on a server). It really couldn’t be any easier – all I had to do was build the Silverlight app – the tool even gave me a ‘TestPage.html’ which hosts the Silverlight app, so that I can test it in a browser.

Deep Zoom is documented here and here, and the Expression Blend team (that owns Deep Zoom) has a blog here. Note that the current version of the Composer tool has a maximum document size of 4 billion pixels – that’s the ‘document’ that includes all the layers of all the images in your final image set. You can easily hit this limit with just 3 or 4 images (one per layer) from a compact digital camera, depending on how much you zoom between layers. I haven’t attached a solution to this post because the image set adds up to about 30Mb.

I created a simple custom UserControl (called WebHostControl) with a fully-docked Windows Forms WebBrowser control as its only child. In my add-in class, I initialized this WebBrowser to load the TestPage.html generated by the Deep Zoom Composer. In accordance with Office UI guidelines, I set up a Ribbon customization with a ToggleButton to toggle the visibility of the task pane.

private WebHostControl whc;

private string silverlightHtml;

private CustomTaskPane slTaskPane;

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

{

silverlightHtml = Path.Combine(

AppDomain.CurrentDomain.BaseDirectory, "TestPage.html");

}

internal void ToggleSLTaskPane(bool isVisible)

{

if (isVisible)

{

if (whc == null)

{

whc = new WebHostControl();

}

if (slTaskPane == null)

{

slTaskPane = CustomTaskPanes.Add(whc, "Silverlight Pane");

slTaskPane.Width = 300;

}

whc.webBrowser.Navigate(silverlightHtml);

}

slTaskPane.Visible = isVisible;

}

This gets a Silverlight app running in an Office add-in. That’s a start, but it’s obviously more useful if the add-in code can communicate with the Silverlight code. Superficially, you’d think this would be easy – after all, they’re both managed components in the same process, and one is loaded (through a couple of layers) by the other. Of course, it’s not so simple – don’t forget that even though they’re both in the same process, they’re running on 2 different CLRs. For my simple PoC, I wanted the user to be able to enter a value in a cell, and have that value be used as the zoom factor in a call to zoom the image in my Silverlight app in the task pane.

Fortunately, Silverlight provides an ‘Html Bridge’ capability, documented here, which allows you to integrate script and managed code in a Silverlight app, including the ability to invoke managed code from javascript on the HTML page. So, I can communicate between the add-in code and the Silverlight code via the HTML script. To use this feature, I first changed the modifier on the Zoom method in the Page.cs in my Silverlight project, to make it public. This method is normally invoked via the mouse handlers (which is obviously a more sensible way to manipulate the zoom than using cell values – but remember this was a science experiment conducted in a hallway (without a chair, I might add)).

public void Zoom(double newzoom, Point p)

{

if (newzoom < 0.5)

newzoom = 0.5;

msi.ZoomAboutLogicalPoint(newzoom / zoom, p.X, p.Y);

zoom = newzoom;

}

Next, I created a managed class with a method that invokes the Zoom method. I exposed this method for scripting via the ScriptableMember attribute:

public class ScriptableManagedType

{

private Page thisPage;

public ScriptableManagedType(Page p)

{

thisPage = p;

}

[ScriptableMember]

public void ExposedSilverlightMethod(int cellValue)

{

thisPage.Zoom(cellValue, new Point(0.5, 0.5));

}

I instantiated this class at the end of the Page constructor, and made it available for scripting using the RegisterScriptableObject method. This method takes an arbitrary string identifier for the scriptable object – in my case I used the string “ScriptableSilverlightObject”:

ScriptableManagedType smt = new ScriptableManagedType(this);

HtmlPage.RegisterScriptableObject("ScriptableSilverlightObject", smt);

On the HTML page, make sure the Silverlight object has an explicit ID:

Then I can add some javascript to the HTML page, to get hold of the Silverlight plug-in and invoke the exposed method on the registered scriptable object. Note that the arbitrary identifier is dynamically accessible in the script from the Content property of the Silverlight plug-in:

function InvokeSilverlightMethod(cellValue)

{

var slp = document.getElementById("SLP");

slp.Content.ScriptableSilverlightObject.ExposedSilverlightMethod(
cellValue);

}

Then, in my add-in project, in my custom UserControl code, I can write a method to invoke this script:

public void InvokeScriptMethod(int cellValue)

{

this.webBrowser.Document.InvokeScript(

"InvokeSilverlightMethod", new object[] { cellValue });

}

Finally, in my ThisAddIn class, I can sink the SheetChange event and implement it to invoke the method in my UserControl.

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

{

silverlightHtml = Path.Combine(

AppDomain.CurrentDomain.BaseDirectory, "TestPage.html");

this.Application.SheetChange +=

new Excel.AppEvents_SheetChangeEventHandler(

Application_SheetChange);

}

void Application_SheetChange(object Sh, Excel.Range Target)

{

int cellValue = Convert.ToInt32(Target.Value2);

whc.InvokeScriptMethod(cellValue);

}

So, the sequence of operations is:

- The user changes a value in a cell in the worksheet.

- In the SheetChange event handler, I call the InvokeScriptMethod method on the UserControl that’s hosting the WebBrowser control.

- The InvokeScriptMethod invokes my InvokeSilverlightMethod javascript on the HTML page.

- The javascript method InvokeSilverlightMethod gets hold of the Silverlight object and invokes the scriptable method ExposedSilverlightMethod.

- The ExposedSilverlightMethod calls Zoom to zoom the image.

That seems somewhat painful, but right now it’s the only way (apart from some other possibly even more painful methods involving remoting or WCF or somesuch) – and it’s very nice that there is actually a way to do this kind of communication.

My conclusion here is that if you want sophisticated presentation features in your Office add-in, you’re almost certainly better off using WPF than Silverlight. Even the Deep Zoom functionality could be replicated with WPF, albeit with a lot of effort. Of course, for Deep Zoom or any WPF equivalent to be really useful as a data visualization feature in Office, you’d want to be able to compose the images dynamically – perhaps dependent on the data current in the active document/workbook. Also, the real advantage of Deep Zoom is its intelligent use of network bandwidth – which is not likely to be an issue in an Office add-in if your images are based on data from the current workbook. So, you could build a much simpler image zoom feature with WPF, without the smart download capability, using ScaleTransform. That’s a bit more work than I had time for, but this little exercise pleasantly filled up the hour’s wait in the hallway – and provided some food for thought.

Message Hooks in Add-ins

andreww — Wed, 25 Feb 2009 03:21:00 GMT

Just like my earlier post on message filters, this is an advanced scenario – so be warned: you almost certainly don’t want to do this. However, there are probably some extreme edge-case scenarios where this technique might be useful. For example, Office apps are notoriously parsimonious with their events. I’m sure you can all cite situations where it would be really nice if Office fired an event, but it just doesn’t. In this situation, it might be useful to intercept raw windows messages instead (and it might not – you’d have to think very carefully if this possibility is worth the potential pain of the technique I’m about to describe). Another scenario where this might be applicable is if you want to show modeless managed dialogs and not have the host app process all the keyboard messages.

You can use the SetWindowsHookEx native API to insert your custom method into the hook chain for a given category of windows messages. Note that inserting a hook obviously slows down the whole system slightly. Note also that if you don’t implement your hook methods in a careful and socially-responsible manner, you risk causing far-reaching damage across the whole system.

Windows maintains an independent hook chain for each type of hook. Each chain is a list of pointers to user-defined callback functions called hook procedures. When a message occurs that is associated with a particular type of hook, Windows passes the message to each hook procedure in the chain, one after the other. For some hooks, the hook procedure can only read messages; others can modify messages or prevent them proceeding on through the chain. Here’s a concrete example: suppose you want to prevent your users from invoking the VB Editor in a given Office app? One way you could do this is by inserting a keyboard hook that intercepts the Alt-F11 keystroke message and does not forward the message on down the chain.

Another scenario where a message hook might be useful is where you use modeless dialogs or custom propertysheets in your add-in. In this scenario, the main window (the Office window) still owns the message pump, so, all the keystroke messages are taken by the host application and not dispatched to the modeless dialog box or propertysheet window. (This doesn’t happen with modal dialogs, because these get their own message pump.)

The main MSDN documentation on hooks is here. The basic set of operations is as follows:

· Write a method with the prescribed signature that will handle the messages you’re interested in, including (most often) forwarding the message down the chain with CallNextHookEx.

· Insert your method into the hook chain with SetWindowsHookEx.

· When you’re done, remove your method from the chain, with UnhookWindowsHookEx.

Let’s look at this in more detail with a practical example. First, declare an int to hold the return from SetWindowsHookEx – this will be the global handle to your hook, and we’ll need this later when we want to call UnhookWindowsHookEx. Also declare a delegate type for your callback, and a variable to hold an instance of this type.

private int hookHandle = 0;

private delegate int HookProc(int nCode, IntPtr wParam, IntPtr lParam);

private HookProc messageHookProcedure;

Next, import all the Windows API methods you’ll need, including: SetWindowsHookEx to install the hook; UnhookWindowsHookEx to uninstall the hook; and CallNextHookEx to pass the hook information to the next hook procedure in the chain. Note that SetWindowsHookEx takes a pointer to a callback as one of its parameters – in managed code, of course, this translates to a delegate:

[DllImport("user32.dll", CharSet = CharSet.Auto)]

private static extern int SetWindowsHookEx(

int idHook, HookProc lpfn, IntPtr hInstance, int threadId);

[DllImport("user32.dll", CharSet = CharSet.Auto)]

private static extern bool UnhookWindowsHookEx(int idHook);

[DllImport("user32.dll", CharSet = CharSet.Auto,

CallingConvention = CallingConvention.StdCall)]

private static extern int CallNextHookEx(

int idHook, int nCode, IntPtr wParam, IntPtr lParam);

Also, define the managed equivalent of the MSG struct, and it’s nested POINT type:

[StructLayout(LayoutKind.Sequential)]

private struct POINT

{

public int x;

public int y;

}

[StructLayout(LayoutKind.Sequential)]

private struct MSG

{

internal int hwnd;

internal uint message;

internal uint wParam;

internal int lParam;

internal uint time;

internal POINT pt;

}

To set the hook, instantiate your delegate and call SetWindowsHookEx. You have to specify the type of hook you want to install. In this example, I’m setting a hook for generic windows messages, using the constant WH_GETMESSAGE, defined in winuser.h. When you set up this type of message hook, you have to pass the current thread ID. If this parameter is zero, the hook procedure is associated with all existing threads running in the same desktop as the calling thread, which is not usually what you want. Note that using System.AppDomain.GetCurrentThreadId procudes a compiler warning: “GetCurrentThreadId has been deprecated because it does not provide a stable Id when managed threads are running on fibers. To get a stable Id for a managed thread, use the Thread.ManagedThreadId property.” However, in the context of Office add-ins, we don’t care about fibers, and anyway, passing the Thread.ManagedThreadId to SetWindowsHookEx always fails. (I don’t know why this is.)

internal void SetMessageHook()

{

    const int WH_GETMESSAGE = 3;
    messageHookProcedure = new HookProc(MessageHookProc);
    hookHandle =
        SetWindowsHookEx(WH_GETMESSAGE, messageHookProcedure,
        (IntPtr)0, AppDomain.GetCurrentThreadId());
}

When you instantiate your delegate, you initialize it to your custom callback method. Bear in mind that the types of operation you can legally perform in this callback depend on the type of the message hook. In this case, with a generic message hook, we have a fair amount of leeway, but there are still some restrictions. First, if the first parameter (nCode) < 0, the hook procedure must pass the message to CallNextHookEx without further processing, and should return the value returned by CallNextHookEx. Secondly, we only want to process the message if it has not already been removed from the queue, so we need to compare the wParam against PM_NOREMOVE. For this type of message hook callback, the lParam that Windows passes us is a pointer to a MSG struct, and we can retrieve this by using Marshal.PtrToStructure. In the following example, I’m simply extracting the message values and putting them into a ListBox in a custom taskpane. Finally, make sure we don’t break the hook chain, by calling CallNextHookEx:

private int MessageHookProc(int nCode, IntPtr wParam, IntPtr lParam)

{

if (nCode < 0)

{

return CallNextHookEx(hookHandle, nCode, wParam, lParam);

}

else

{

const int PM_NOREMOVE = 0;

if (wParam.ToInt32() == PM_NOREMOVE)

{

MSG msg =

(MSG)Marshal.PtrToStructure(lParam, typeof(MSG));

listBox.Items.Add(String.Format("{0}: {1},{2}",

(WM)msg.message, msg.pt.x, msg.pt.y));

listBox.SelectedIndex = listBox.Items.Count - 1;

}

return CallNextHookEx(hookHandle, nCode, wParam, lParam);

}

Note that I’m using a custom enum (WM) based on a listing I found on pinvoke.net:

public enum WM : uint

{

NULL = 0x0000,

CREATE = 0x0001,

DESTROY = 0x0002,

MOVE = 0x0003,

SIZE = 0x0005,

//... lots more message IDs

SYSTIMER = 0x118

}

Don’t forget to make sure you remove the hook whenever you don’t need it any more, and before you exit. You could implement a suitable method, and make sure to call it (for instance) in the ThisAddIn_Shutdown method:

internal void ClearHook()

{

if (hookHandle != 0)

{

bool ret = UnhookWindowsHookEx(hookHandle);

if (ret == false)

{

Debug.WriteLine("UnhookWindowsHookEx Failed");

return;

}

hookHandle = 0;

}

That’s pretty much it. The implementation would be very similar for all types of hook, with minor differences. For example, to hook only mouse messages, you’d declare a managed equivalent of the MOUSEHOOKSTRUCT defined in winuser.h – note that this also uses the POINT struct type. You can use the same HookProc delegate type, the same hook handle, and the same ClearHook method to call UnhookWindowsHookEx. To set up the hook, specify WH_MOUSE in the call to SetWindowsHookEx:

[StructLayout(LayoutKind.Sequential)]

private class MouseHookStruct

{

internal POINT pt;

internal int hwnd;

internal int wHitTestCode;

internal int dwExtraInfo;

}

internal void SetMouseHook()

{

    const int WH_MOUSE = 7;
    mouseHookProcedure = new HookProc(MouseHookProc);
    hookHandle =
        SetWindowsHookEx(WH_MOUSE, mouseHookProcedure,
        (IntPtr)0, AppDomain.GetCurrentThreadId());
}

The mouse hook callback is very similar to the generic message callback, except that the lParam that Windows passes us in this case is a pointer to a MOUSEHOOKSTRUCT:

private int MouseHookProc(int nCode, IntPtr wParam, IntPtr lParam)

{

if (nCode < 0)

{

return CallNextHookEx(hookHandle, nCode, wParam, lParam);

}

else

{

MouseHookStruct mouseHookStruct =

(MouseHookStruct)

Marshal.PtrToStructure(lParam, typeof(MouseHookStruct));

// Compose a string that shows the current mouse message Id

// and coordinates.

string mouseMessage = string.Format("{0}: x={1},y={2}",

((WM)wParam.ToInt32()),

mouseHookStruct.pt.x, mouseHookStruct.pt.y);

// Put the mouse message values into the listbox in the

// taskpane, and scroll to the bottom.

listBox.Items.Add(mouseMessage);

listBox.SelectedIndex = listBox.Items.Count - 1;

// Ensure that we don't break the hook chain.

return CallNextHookEx(hookHandle, nCode, wParam, lParam);

}

To hook only keyboard messages, you’d declare a managed equivalent of the KBDLLHOOKSTRUCT defined in winuser.h. Again, you can use the same HookProc delegate type, the same hook handle, and the same ClearHook method to call UnhookWindowsHookEx. To set up the hook, specify WH_KEYBOARD in the call to SetWindowsHookEx. In this case, you pass the module handle for the current process, which you can get with the GetModuleHandle API:

[DllImport("kernel32.dll", CharSet = CharSet.Auto)]

private static extern IntPtr GetModuleHandle(string lpModuleName);

[StructLayout(LayoutKind.Sequential)]

private struct KbDllHookStruct

{

internal int vkCode;

internal int scanCode;

internal int flags;

internal int time;

internal int dwExtraInfo;

}

internal void SetKeyboardHook()

{

const int WH_KEYBOARD_LL = 13;
keyboardHookProcedure = new HookProc(KeyboardHookProc);

using (Process curProcess = Process.GetCurrentProcess())

using (ProcessModule curModule = curProcess.MainModule)

{

hookHandle =

SetWindowsHookEx(WH_KEYBOARD_LL, keyboardHookProcedure,

GetModuleHandle(curModule.ModuleName), 0);

}

The keyboard hook callback is very similar to the generic/mouse message callbacks, except that the lParam that Windows passes us in this case is a pointer to a KBDLLHOOKSTRUCT. In the following implementation, in addition to logging the message information in my ListBox, I’m also trapping specifically Alt-F11 keystrokes – when I get this message, I simply return 1, which prevents the message from being propagated further down the chain:

private int KeyboardHookProc(int nCode, IntPtr wParam, IntPtr lParam)

{

if (nCode < 0)

{

return CallNextHookEx(hookHandle, nCode, wParam, lParam);

}

else

{

if ((wParam == (IntPtr)WM.KEYDOWN)

|| (wParam == (IntPtr)WM.SYSKEYDOWN))

{

KbDllHookStruct kbDllHookStruct =

(KbDllHookStruct)

Marshal.PtrToStructure(lParam, typeof(KbDllHookStruct));

// Put the message values into the listbox in the

// taskpane, and scroll to the bottom.

listBox.Items.Add(String.Format(

"{0}: {1}", (WM)wParam, (Keys)kbDllHookStruct.vkCode));

listBox.SelectedIndex = listBox.Items.Count - 1;

// Supress Alt-F11.

if (wParam == (IntPtr)WM.SYSKEYDOWN

&& kbDllHookStruct.vkCode == (int)Keys.F11)

{

return 1;

}

return CallNextHookEx(hookHandle, nCode, wParam, lParam);

}

That’s it. The sample solution attached to this post includes all 3 hook types described. Drive safe now.

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.

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.

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.

Creating a PivotTable Programmatically

andreww — Sat, 26 Jul 2008 04:57:00 GMT

I received an email from a customer the other day asking how to set up an Excel pivot table programmatically. The Excel OM exposes a number of objects and methods that you can use to create pivot tables, some more sophisticated than others. I wanted the simplest possible way to set up a pivot table from an external data source, and this is what I ended up with...

I used the AdventureWorks SQL database, which you can download from here. In my solution, I first set up a data connection to the database, with a SQL select statement to fetch all the SalesPerson sales records:

string connection =

@"OLEDB;Provider=SQLOLEDB.1;Integrated Security=SSPI;Data Source=MYSERVER\SQLEXPRESS;Initial Catalog=AdventureWorks";

string command =

"SELECT * FROM [Sales].[vSalesPersonSalesByFiscalYears]";

Next, I added a new PivotCache to the PivotCaches collection in the active workbook, and set its data connection and SQL command properties:

Excel.PivotCache pivotCache =

this.Application.ActiveWorkbook.PivotCaches().Add(

Excel.XlPivotTableSourceType.xlExternal, missing);

pivotCache.Connection = connection;

pivotCache.MaintainConnection = true;

pivotCache.CommandText = command;

pivotCache.CommandType = Excel.XlCmdType.xlCmdSql;

I can then add a new PivotTable to the worksheet, based on the PivotCache I’ve just configured:

Excel.Worksheet sheet = (Excel.Worksheet)this.Application.ActiveSheet;

Excel.PivotTables pivotTables = (Excel.PivotTables)sheet.PivotTables(missing);

Excel.PivotTable pivotTable = pivotTables.Add(

pivotCache, this.Application.ActiveCell, "PivotTable1",
missing, missing);

Then, set the PivotTable to use the pivot table stencil outline instead of the default 2x2 cell grid, and format it with grey alternating row shading:

pivotTable.SmallGrid = false;

pivotTable.ShowTableStyleRowStripes = true;

pivotTable.TableStyle2 = "PivotStyleLight1";

Set up the SalesTerritory field as the page field, and FullName as the row field:

Excel.PivotField pageField =
(Excel.PivotField)pivotTable.PivotFields("SalesTerritory");

pageField.Orientation = Excel.XlPivotFieldOrientation.xlPageField;

Excel.PivotField rowField =
(Excel.PivotField)pivotTable.PivotFields("FullName");

rowField.Orientation = Excel.XlPivotFieldOrientation.xlRowField;

Add a data field for the sales for 2004:

pivotTable.AddDataField(

pivotTable.PivotFields("2004"), "Sum of 2004", Excel.XlConsolidationFunction.xlSum);

Done. The end result looks like this:

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.