Ryan's Look at Outlook Programmability : .NET

Application Shutdown Changes in Outlook 2007 Service Pack 2 Beta

rgregg — Mon, 27 Oct 2008 22:17:36 GMT

As part of the performance improvements we’ve made for Outlook 2007 SP2 beta, we’ve changed the way Outlook manages the lifecycle of the application. In the past, Outlook followed the best practices for Component Object Model (COM) servers and allowed clients of the Outlook server to control the lifecycle of Outlook. This caused a significant end-user side effect: often the user could not close Outlook because of lingering external references. This is confusing and frustrating for our users, and many users would often use Task Manager to terminate the Outlook process.

As a result of strong and long-standing customer feedback about the need to close Outlook and have Outlook stop running, Service Pack 2 changes the way Outlook closes, ensuring that the user’s intent to close Outlook is respected. These changes mean the way the Outlook COM server shuts down has changed significantly, which may impact solutions using the Outlook object model outside of the Outlook process.

Impact for Add-ins: None

If you’ve written an in-process add-in for Outlook this change does not affect you. The lifecycle of in-process add-ins and in-process COM references in Outlook 2007 has always been the same as the lifecycle of the application. When the user closes the last Outlook window and Outlook starts to shut down, add-ins are disconnected and references are released.

Add-ins can use the Quit event on the Application object to determine when Outlook will be closing down. After the Quit event is raised, add-ins will have their OnDisconnection method called, and then the add-in and Outlook will close.

Impact for Cross Process Solutions

Before Outlook 2007 SP2, Outlook would check for external (out of process) references on the COM Server objects and wait for those references to be released before Outlook would close. This would enable solutions that were depending on Outlook data to keep Outlook running until the references were released. This is common behavior for COM servers, but is unexpected behavior for end users, who expect that an application will close when they close the last window of the application (or at least reasonably soon after they close the last window).

Starting with Outlook 2007 Service Pack 2, Outlook will ignore external COM references when determining if Outlook should exit. When a user closes the last Outlook window, Outlook will start exiting the process: this involves raising the Quit event on the Application object, disconnect all add-ins, disconnecting external references, persisting in-memory changes to the disk, and then exiting. All external COM references will be disconnected immediately after the Quit event is raised on the Application object.

Because of the way COM works, when Outlook releases the external references, those objects become disconnected objects in cross process solutions. When a solution attempts to use the disconnected reference, an error will result from any call to the object (RPC_E_DISCONNECTED). Solutions that are not designed to handle this error may crash or otherwise misbehave. This will occur any time a solution attempts to use an object reference after Outlook has closed.

To work correctly with the new behavior in Outlook, your solution should listen for the Quit event on the Application object. When that event is raised, stop any work in progress using Outlook data, and release all Outlook references. Any remaining references after the solution returns from the Quit event will be disconnected.

While handling the Quit event, a solution should return from the event as quickly as possible. While a solution is working in the Quit event, Outlook may appear hung to the user and the operating system and the user may forcibly terminate Outlook instead of waiting for it to finish closing.

If your solution needs to access data from Outlook after the process has shutdown, it can do so by starting the process up again in UI-less mode by calling CoCreateInstance(). However, you should attempt to design your solution such that data from Outlook is only collected while Outlook is running. I’ll be blogging about an example of how to design a solution that works this way in an upcoming blog post.

Special Cases

While the text above describes the default, we realize that there are customers and solutions which will be negatively impacted by this change until the solution can be updated. To restore the old behavior, administrators can set a registry key to force Outlook to wait for all external references to be released before closing.

This registry key applies to Outlook 2007 SP2 beta, the registry key may change for the final release of SP2.

[HKEY_CURRENT_USER\Software\Microsoft\Office\12.0\Outlook\Options\Shutdown]
“AllowShutdownWithExternalReferences”=dword:00000000

We’ve also done work to ensure that when a solution uses CoCreateInstance and Outlook isn’t running, the right things happen. In those cases, Outlook will remain running in “headless mode” without any visible user interface. If the user launches Outlook, a new Outlook window will appear in the same session Outlook was already using. If the user closes that window, even though the process was started by a solution, Outlook will exit in the same manner as it would if the application was started by the user.

Summary

As part of a larger overall performance improvement effort in Outlook 2007 Service Pack 2, the team has invested a significant amount of time to improve the experience around closing Outlook. We’ve also made changes to ensure that Outlook boots faster and is more responsive all around.

I’m interested in your feedback on this new shutdown logic, and any thoughts or questions about how we can continue to improve this experience in the next Outlook release. Please leave a comment on this post and let me know what you have to say.

Common Properties on Outlook Controls

rgregg — Tue, 02 Oct 2007 03:12:56 GMT

If you’ve started to take advantage of the new Outlook controls on form regions in Outlook 2007, you may have noticed something strange. None of the controls have common properties you would expect all controls to have: Visible, Width, Height, Top, Left, etc. You might be thinking we missed some obvious test case here, but you’d be wrong.

These properties do in fact exist on the controls. However, because of a complexity of COM and Office dependencies, the properties do not show up in the type library exposed by Outlook.

Each of the Outlook controls (they all start with Olk in the type library) also implement the Control interface from fm20.dll. This interface includes all common properties, including Height, Width, Top, Left, Name, Parent, TabIndex, TabStop, Visible and more.

If you are using a language that supports late binding for COM objects, you can just reference the property directly and everything will work as expected.

If you’re writing managed code, or other code which requires explicit definitions of the properties, you will need to cast the control object to the Control interface from fm20.dll to read or write these properties. For example, if you’re writing in C#, you would need to do something like the following:

using Outlook = Microsoft.Office.Interop.Outlook;
using MSForms = Microsoft.Vbe.Interop.Forms;

public void BeforeFormRegionShow(Outlook.FormRegion FormRegion)
{
    // Find OlkButton1 and make it invisible
    MSForms.UserForm canvas = FormRegion.Form as MSForms.UserForm;
    Outlook.OlkCommandButton button1 =
        canvas.Controls.Item("OlkButton1") as Outlook.OlkCommandButton;
    //button1.Visible = false; // can't do this, it doesn't compile
    MSForms.Control ctrlButton1 = (MSForms.Control)button1;
    ctrlButton1.Visible = false; // this works!
}

We tried to find a way to combine these two interfaces together, but because Outlook doesn’t have a dependency on the Microsoft Forms library, it wasn’t feasible to make it work right. There is at least a work-around for developers who need to access these properties.

You can also access additional Outlook-specific properties on controls by casting the control to the OlkControl interface in Outlook. This interface provides you with the ability to control layout settings for how the control will behave on the form. These properties can be set either at runtime or design time, as long as you set them before the layout is calculated (which occurs just after BeforeFormRegionShow).

Why does my Outlook event seem to stop working

rgregg — Wed, 04 Jul 2007 18:39:46 GMT

Wes has a good post over on his blog explaining another common problem that a lot of Outlook solution developers run into:

Imagine we have some code in an Outlook addin that looks similar to code below. Does anyone see anything wrong with it? It simply places a button on the menu bar and shows a message box when the button is clicked. The code works for sometime but then all of a sudden the button mysteriously stops working. What gives?
using Office = Microsoft.Office.Core;
using Outlook = Microsoft.Office.Interop.Outlook;
...
void SetupCommandBar(Outlook.Application application)
{
    Office.CommandBar menu = 
       application.ActiveExplorer().CommandBars.ActiveMenuBar;

    Office.CommandBarButton button = menu.Controls.Add(
        Office.MsoControlType.msoControlButton,
        Type.Missing, Type.Missing, Type.Missing, true) 
        as Office.CommandBarButton;

    button.Caption = "Click Me!";
    button.Click += 
      new Office._CommandBarButtonEvents_ClickEventHandler(button_Click);
}
void button_Click(Microsoft.Office.Core.CommandBarButton Ctrl,
ref bool CancelDefault)
{
    System.Windows.Forms.MessageBox.Show("Clicked Button!");
}
The button stops working due to the mystical powers of the .Net garbage collector. If we look closely we notice that the button object is locally scoped in the SetupCommandBar function, thus once we execute that function the button object is free to be cleaned up. However, until the button object is actually destroyed by the garbage collector the button click event will fire and the button will work. Due to the non-deterministic nature of the garbage collector we have no idea how long the button will work. In my simple testing it seemed to work for a little while but if you want to speed up the process add a call go GC.Collect in the button_Click callback.
The easiest fix for this problem is to change the scope of the button object to be a member variable of enclosing class. By doing this we ensure that the button object stays alive and works until we are ready for it to stop working.

Mysterious Errors When Using Form Regions from Managed Code Add-ins

rgregg — Fri, 22 Jun 2007 00:35:00 GMT

I've been noticing some feedback lately where a number of developers were having problems working with the controls on their form region. Usually, these problems manifested as Outlook's object model returning null values back when trying to access the Controls collection of the UserForm object in the Microsoft Forms 2.0 library (which was accessed from the FormRegion.Form property).

This can be especially frustrating, because it looks like you've done everything right, and Outlook is just giving you back something that is totally wrong. Turns out, that isn't quite the case.

If you've added a reference to the 'Microsoft Forms 2.0' type library, you might have added the wrong reference to your project. On some computers, you'll find two different listings for the forms type library in the Add Reference dialog:

Depending on which reference you select, you'll either get a reference properly associated with the Primary Interop Assembly provided by Office, or you'll get a reference with a Visual Studio generated interop assembly. Unfortuatnely, the VS generated interop assembly incorrectly maps some elements of the type library to elements in the interop assembly. This ultimately means that when you are using this reference, you'll end up calling into a different property or method than your code appears to be calling, which causes various strange exceptions and errors.

You can easily determine which reference you are using by selecting the reference and looking at the properties of the reference. If you've added the self-generated IA reference, the properties will look like this:

Notice that the reference has "Copy Local" set to True, and that the Path is not pointing at the Global Assembly Cache (GAC) but rather to the location of my solution. This indicates that I'm using a self-generated interop assembly, and that I may be running into issues.

If you've added the correct reference to the PIA, then you'll see properties that look like this instead:

This time around, you'll see the Path is pointing into the GAC, and the "Copy Local" property is False. This indicates the PIA is being used, and everything should work normally.

If you find your project is using the incorrect reference, you should remove the reference and add a new reference. Unforutnately, there is no way to determine which reference is the "right" reference from the Add References dialog. You'll simply need to use trial and error and double check after adding the resource to make sure you've picked the right one.

The Take-away: Make sure you are using the right interop assembly when working with custom forms or form regions from your managed code solution. Using the Visual Studio generated interop assembly can cause mysterious errors in your solution that you may not catch right away.

PDF Preview Handler for Outlook/Vista

rgregg — Sun, 18 Mar 2007 06:29:54 GMT

If you're running Windows Vista, or Outlook 2007 on either Vista or Windows XP, you're probably wondering just how long you have to wait until you can use the preview capabilities of your new operation system or Outlook client to view PDF documents.

While I still haven't seen an official solution to the problem from Adobe or any of the other typical PDF reader component companies, I have found a few answers online. There are a couple of different downloads that will solve your problems, depending on the PDF reader you favor.

Foxit: Tim Heuer has partnered with Foxit software to create Foxit PDF Preview Handler, which works with Foxit Reader.
Acrobat: I've created a similar freeware component that works with Adobe Acrobat Reader 7.x or later. If you favor using Adobe Acrobat, take a look at my PDF Preview Handler.

If you know of another solution to the problem, add a comment here so other users can find a solution for their PDF previewing problems.