Andrew Whitechapel : VSTO

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.

Carter-Lippert VSTO Book Updated

andreww — Sat, 14 Mar 2009 04:40:00 GMT

The eagerly-awaited update to Eric Carter and Eric Lippert’s VSTO book has been released this week. This is the definitive guide to Visual Studio Tools for Office, and this edition targets development for Excel, Word and Outlook 2007 using Visual Studio 2008. Eric and Eric have done another excellent job, and the book weighs in at 1055 pages – jam-packed with in-depth insights into VSTO development. The ToC looks like this:

Part I – An Introduction to VSTO

1. An Introduction to Office Programming

2. Introduction to Office Solutions

Part II – Office Programming in .NET

3. Programming Excel

4. Working with Excel Events

5. Working with Excel Objects

6. Programming Word

7. Working with Word Events

8. Working with Word Objects

9. Programming Outlook

10. Working with Outlook Events

11. Working with Outlook Objects

Part III – Office Programming in VSTO

12. The VSTO Programming Model

13. Using Windows Forms and WPF in VSTO

14. Working with Document-Level Actions Panes

15. Working with Application-Level Custom Task Panes

16. Working with Outlook Form Regions

17. Working with the Ribbon in VSTO

18. Working with Smart Tags in VSTO

19. VSTO Data Programming

20. Server Data Scenarios

21. ClickOnce Deployment

…what are you waiting for – go get a copy!

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

{

Using Managed Controls as ActiveX Controls

andreww — Tue, 25 Nov 2008 10:31:00 GMT

Can you use a managed usercontrol in an Office document in the same way that you can use a native ActiveX control – all without using VSTO? Some time ago, I posted about how to use native ActiveX controls within a doc-level VSTO solution, by wrapping them in managed usercontrols. A reader (Casey) asked the question, “what about going the other way?” The answer is “maybe”. Or, to be more precise, “up to a point, but the technique is unsupported and probably won't work in most scenarios”. If you still want to play with this a bit, here’s how to start…

First, create a managed usercontrol project – either a Windows Forms class library or control library project. Use the usercontrol designer to design your custom usercontrol the way you want it (using any standard controls you like).

Second, in the project properties, on the Build tab, select the “Register for COM interop” option. This will register any COM-visible classes in the project when you build it, and will also build a COM typelib and register it.

Third, attribute your usercontrol class to make it COM-visible. Also, specify a GUID, to avoid getting a fresh one on each build; and specify that you want the compiler to generate a dispatch class interface for the control.

[ComVisible(true)]

[Guid("0F2A2E9D-C79E-4b1b-9AF7-2D1487F29041")]

[ClassInterface(ClassInterfaceType.AutoDispatch)]

public partial class ManagedOcx : UserControl

{

Next, we need to provide some additional registry entries: Control, MiscStatus, TypeLib and Version. You can do this with a .REG script, but it’s generally better to write functions that will be called on registration/unregistration (attributed with ComRegisterFunction/ComUnregisterFunction).

Control is an empty subkey. TypeLib is mapped to the GUID of the TypeLib (this is the assembly-level GUID in the assemblyinfo.cs). Version is the major and minor version numbers from the assembly version. The only mildly interesting subkey is MiscStatus. This needs to be set to a value composed of the (bitwise) values in the OLEMISC enumeration, documented here. To make this enum available, add a reference to Microsoft.VisualStudio.OLE.Interop (and a suitable ‘using’ statement for the namespace).

[ComRegisterFunction]

static void ComRegister(Type t)

{

string keyName = @"CLSID\" + t.GUID.ToString("B");

using (RegistryKey key =

Registry.ClassesRoot.OpenSubKey(keyName, true))

{

key.CreateSubKey("Control").Close();

using (RegistryKey subkey = key.CreateSubKey("MiscStatus"))

{

// 131456 decimal == 0x20180.

long val = (long)

( OLEMISC.OLEMISC_INSIDEOUT

| OLEMISC.OLEMISC_ACTIVATEWHENVISIBLE

| OLEMISC.OLEMISC_SETCLIENTSITEFIRST);

subkey.SetValue("", val);

}

using (RegistryKey subkey = key.CreateSubKey("TypeLib"))

{

Guid libid =

Marshal.GetTypeLibGuidForAssembly(t.Assembly);

subkey.SetValue("", libid.ToString("B"));

}

using (RegistryKey subkey = key.CreateSubKey("Version"))

{

Version ver = t.Assembly.GetName().Version;

string version =

string.Format("{0}.{1}", ver.Major, ver.Minor);

subkey.SetValue("", version);

}

[ComUnregisterFunction]

static void ComUnregister(Type t)

{

// Delete the entire CLSID\{clsid} subtree for this component.

string keyName = @"CLSID\" + t.GUID.ToString("B");

Registry.ClassesRoot.DeleteSubKeyTree(keyName);

}

Build the project, then run Excel. From the Developer tab, go to the Controls group, and click the Insert button. This drops down a little gallery of available controls. The one in the bottom right-hand corner pops up the More Controls dialog, which offers a list of all suitably-registered ActiveX controls. You should find your custom control in this list.

Note: this seems to work OK for Excel (with the very limited testing I've done), partly works with PowerPoint, but fails miserably with Word. Possibly, some more of the OLEMISC values might improve this; possibly there are some messages we need to hook; possibly there are some more interfaces we need to implement – I haven’t tried. Of course, the VSTO runtime has a nice set of hosting controls that enable this behavior for Excel and Word, but these are not usable outside the context of a VSTO solution. As I said, this is an entertaining avenue to explore, but it remains unsupported. The fact that I’ve only barely got it to work in a very limited way should tell you that this is probably not a technique you want to use in any serious way.

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

}

Advances in .NET Type System

andreww — Tue, 28 Oct 2008 21:35:24 GMT

Here at PDC, Misha Shneerson has just delivered a talk on a couple of very interesting new features provided by .NET 4.0. He did explain up front that these features have very broad applicability, but reading the session evals it's pretty obvious that a lot of people didn't get it. Probably this is because Misha explained the first feature in the context of COM interop - and this gave the impression that the whole talk would be about COM interop. Not so - and he went on to show how you can achieve loose type coupling and version resiliency in a completely managed context.

The two major features are Type Embedding and Type Equivalence. These are changes in both the CLR and in the C# and VB compilers. Using the new features, you can achieve true version independence. This means that you can build composable applications where your add-ins can run against any version of the host application – giving you backward and forward compatibility. Anyone who builds shared libraries (which is, basically, everyone) can take advantage of this.

Think about it: you can now identify managed types by GUID.

Do yourself a favor and read up on Misha's blog posts on these features. The first one is here.

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.

Exciting PDC Session

andreww — Tue, 07 Oct 2008 02:17:00 GMT

Under the Hood: Advances in the .NET Type System
This is one session you absolutely must not miss. It looks pretty innocuous, but it's actually a very big deal. This talk is an in-depth examination of some of the enhancements we're making in CLR v4.0 (and in the C# and VB language compilers) to support shared-type scenarios. These include scenarios where you have multiple managed assemblies that need to talk to each other through some shared interfaces, as well as native-managed interop scenarios - the classic example of which is managed add-ins to Office applications. We'll look at how these changes help to simplify versioning and deployment of components targeting either COM based and/or fully managed applications. For Office developers, this provides the ability to eliminate the need to redistribute PIAs. The speaker is everyone's favorite VSTO developer, Misha Shneerson. As always, PDC is the place to go for information that you cannot get anywhere else. It's likely Misha will post some sample code on his blog after the event - but if you really want to get the inside scoop, please sign up for PDC!

You can look up the session on the PDC site here. Note that the final schedule for all sessions is not yet available, but should be published early next week. Look out for it here.

[Updated Oct-07]

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.

Activating a Custom Tab on the Ribbon When a Document Is Opened

andreww — Wed, 20 Aug 2008 05:23:00 GMT

Harry 'Play It Again Sam' Miller has posted a wonderfully funny video on this topic - with a serious message. You've got to check this one out: http://blogs.msdn.com/vsto/archive/2008/08/12/activating-a-custom-tab-on-the-ribbon-when-a-document-is-opened.aspx.

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.