Ryan's Look at Outlook Programmability

Office 2010 Released to Manufacturing!

Ryan Gregg — Mon, 19 Apr 2010 19:31:48 GMT

On Friday we signed off on all of the Office 2010 products, including Outlook 2010 and have released them to manufacturing! A journey we started 3.5 years ago is complete! Outlook 2010 is the best version of Outlook ever, including a number of great new features and some exciting platform changes as well.

Stop by the Outlook Developer Center for access to a number of different Outlook development resources (soon to be updated to include Outlook 2010 resources, stay tuned!).

Another good stop for the Outlook developer is to check out the Office Client Developer blog, including a new post from Angela with managed code samples for Outlook 2010.

If you’re interested in developing a provider for the Outlook Social Connector, don’t miss the content all about how to do that.

Outlook Social Connector and Developers

Ryan Gregg — Fri, 20 Nov 2009 01:04:51 GMT

Hopefully you caught the news yesterday at PDC09 that Microsoft Office 2010 beta is now available for download! One of the cool new features added in the beta for Outlook 2010 is the Outlook Social Connector, which connects social network data into Outlook and displays relevant information to you based on the current context.

This is a great feature, and will enable all sorts of great scenarios. Even cooler, it’s a new platform that can be leveraged by developers looking to integrate with Outlook. Today Randy Byrne posted details over on the Outlook blog about how to integrate with the OSC.

Out of the box, Outlook will connect to SharePoint 2010, and we’ve announced a partnership with LinkedIn to connect with as well. However, anyone can build a provider to plug into the OSC and provide data from any data source. Some examples we’ve been thinking of include connecting to an internal CRM system, to show the latest updates about a customer when you receive an e-mail.

If you’re interested, make sure you download the beta and try building an OSC Provider. Click through to Randy’s post for more information.

Additional Shutdown Changes for Outlook 2010 Beta

Ryan Gregg — Sat, 03 Oct 2009 00:46:00 GMT

As part of Outlook 2010 and Outlook 2007 SP2, the Outlook team has taken a new and harder stance on performance. We strived to make these versions of Outlook the fastest, most performant versions released. To accomplish this, we’ve been making some significant changes to the way Outlook works across the board and in shutdown specifically. Over the course of the last year, we’ve focused on ensuring Outlook shuts down properly when the user closes the application.

Background

Outlook often has issues shutting down on command. Even when it did shutdown, it often took much longer than expected. Our goal for this release is to ensure Outlook always shuts down and put this issue to rest. With this release we want to put this issue to rest. To facilitate that, we started making a series of changes that ensure Outlook shuts down quickly and consistently.

In Outlook 2007 SP2, we added a new design to MAPI providers where we only do the minimal work necessary to prevent data loss before Outlook exits and will sidestep some of the normal shutdown logic. Outlook SP2 also prevents external COM add-ins from keeping Outlook running after the user closed Outlook. The big pain point was that all MAPI Providers had to opt-in to the design and support the new behavior because of compatibility concerns of this change in a service pack.

In Outlook 2010 Technical Preview, the design was modified so that a MAPI provider needed to opt-out of the new shutdown method. If a MAPI provider does not implement the fast shutdown API, Outlook 2010 will still shut down using the fast method.

These changes have done a lot to ensure that Outlook always shuts down and is able to shut down quickly, as the user intended. Since the technical preview release, we continued to monitor the feedback from beta testers and users to determine how effective these changes have been. Looking through the data we’ve collected, it’s become clear that there is another significant source of shutdown pain: Outlook add-ins. We found that add-ins would perform expensive operations and network I/O during shut down events. Because of that impact, we expanded our investment in improving Outlook’s shutdown behavior by creating a fast shutdown model for add-ins as well.

Add-in Shutdown Changes in Outlook 2010 Beta

Starting with the Outlook 2010 Beta, Outlook, by default, will not signal add-ins that it is shutting down. Specifically, the beta version will no longer call OnBeginShutdown and OnDisconnection methods of the IDTExtensibility2 interface when Outlook is shutting down with fast shutdown. If you have a Visual Studio Tools for Office (VSTO) add-in, you will not see the ThisAddin_Shutdown method called.

The impact to an add-in from this change depends on what the add-in was doing during these events. In most add-ins, these events are used to release references to Outlook COM objects and clean memory that was allocated during the session. In these cases, the impact to the add-in will be minimal. Outlook will release the remaining COM object references and shutdown, and Windows will reclaim the allocated memory when the process exits.

For some add-ins, the change is more impactful. If an add-in uses these events to commit data (for example, storing user settings or reporting usage to a web server) this will no longer occur. Depending on the scenario, this may or may not have a user visible impact. Add-ins will either need to be modified to be compatible with this new behavior, or an IT administrator will need to use group policy to restore the original behavior for the specific add-in.

These methods can and will be called in other scenarios, such as if the add-in is manually disconnected or if slow shutdown is enabled through group policy, so it is important that developers continue to code as though these methods would be called. More information about best practices is listed below.

Reasons for this Change

This change has a pretty significant impact and is not a change we made lightly. Looking over the data we’ve collected in the last year, it became clear we needed to do more to help shutdown faster. The data from Outlook 2007 SP2 indicated that if the user had “misbehaving” add-ins installed, the average delay to shutdown was 13 seconds. For Outlook 2010 technical preview, the data shows an average delay of 15-20 seconds.

As part of our add-in compatibility testing, we’ve examined what add-ins are doing in their shutdown/disconnect events. While a majority of add-ins are performing simple tasks like releasing references, several add-ins we’ve identified are making web service calls or other “long running” operations synchronously during these events.

The benefit of making this change is that for the majority of add-ins and customers, Outlook will work significantly better than it has in the past when shutting down. This change improves our ability to respond to the user’s intent and exit quickly, letting the user move on to the next task or shutdown their computer.

For Developers: Best Practices for Add-in Shutdown

For add-in developers, the new world of Outlook shutdown can seem a little tricky to operate in. It is important that developers follow the best practices for add-in shutdown to ensure that our shared users continue to benefit from a fast and responsible Outlook shutdown experience.

Practice #1: Continue to Release References in OnDisconnection

It is important that you continue to write code in OnDisconnection or ThisAddin_Shutdown to release any remaining COM references to Outlook objects. In Outlook 2003 and Outlook 2007 pre-SP2, these references can prevent Outlook from shutting down. Even in Outlook 2010 you should continue to release references and allocated memory in these events because there are scenarios where slow shutdown will be used or the user could manually disconnect your add-in through the COM Add-ins dialog.

Practice #2: Detecting when Outlook is shutting down

If you need to detect that Outlook is shutting down, you can use the Application.Quit event in the Outlook object model to receive a notification that the process is shutting down. You should respond quickly to this event and return control back to Outlook as quickly as possible. Add-ins should focus on not having a perceivable impact on Outlook shutdown when compared with shutdown when the add-in is not running.

If you have long running or indeterminate length running operations to perform at shutdown, consider the following questions:

Does this need to happen when Outlook shuts down? What happens if Outlook crashes and this code doesn’t run?
Can the operation be made to be “pay for play” where changes are committed when the user makes the change instead of being saved for later?
Can the work be done on a background thread instead of synchronously during a quit event? (Note: you cannot make OM calls from a background thread, but can use MAPI directly if properly initialized)

Explicitly, you should not do network I/O during any quit event. This includes saving data to a network share, writing data to an Outlook online-mode store, or calling web services during Application.Quit, OnBeginShutdown or OnDisconnection.

In using the Application.Quit event, you should not perform any release of Outlook COM objects or allocated memory in the Outlook process space. This will be done for you by Outlook and Windows when the process exits.

One case we’ve seen internally as we started looking at what add-ins were doing during shutdown was where an add-in was reporting usage information back to a web service in the shutdown events. Instead of recording this data directly to the web service during shutdown, we altered the code to instead report the previous session usage information on a background thread sometime during the next Outlook boot. This way the data can still be uploaded, but Outlook is never blocked by the work.

Another alternative, if you have another executable that is already part of your solution, is to move work out of the add-in and into your executable. This way the work can be done regardless of if Outlook is running, and without blocking Outlook’s ability to start up or shut down quickly.

Practice #3: Test shutdown using both the fast and old methods

As a developer, you should ensure that your add-in has a negligible impact on Outlook’s user experience. This includes testing the impact your add-in makes to Outlook’s boot time, the general user experience while using Outlook, common scenarios (like composing a new message, replying to a message, folder switch, sending mail, etc) and shut down. Specifically, developers should test the difference between the shutdown times of outlook when changing the registry settings for the add-in that control how Outlook shuts down.

For IT Administrators

If you have internal add-ins or solutions that cannot be updated to support the new design, you can deploy group policy to your users to revert the behavior. There are two methods for enabling shutdown notifications to Outlook add-ins in Outlook 2010 Beta:

Selectively for individual add-ins (the preferred approach): While this cannot be deployed through group policy, it can be enabled as part of add-in deployments and is useful if backwards compatibility is required for specific add-ins.
Globally for all add-ins: this is recommended for organizations with a large number of internal solutions or desktops that need to deploy this setting to ensure compatibility during a rollout of Outlook 2010.

Individual Add-in Setting

By using this setting Outlook will selectively provide shutdown notifications to the specified add-in without notifying all add-ins. This setting is configured per add-in through the add-in registration in either HKCU or HKLM registry hives, by adding an additional value to the add-in registration:

HKCU\Software\Microsoft\Office\Outlook\Add-ins\<ProgID>
[RequireShutdownNotification]=dword:0x1

Setting this value to 0x1 will enable the add-in to receive the blocked callbacks during Outlook shutdown. This will have an impact to the performance of Outlook shutdown that should be evaluated as part of a deployment. This setting should only be used if an add-in has significant compatibility issues with Outlook 2010’s new shutdown design.

Global Setting

This setting can be used to change the new shutdown design to match the design used by Outlook 2007. This setting can be deployed through group policy either per user or per machine.

HKCU\Policies\Microsoft\Office\Outlook\14.0\Options\Shutdown
[AddinFastShutdownBehavior]=dword:0x1

Setting AddinFastShutdownBehavior to 1 will enable shutdown notifications for all add-ins. Setting the value to 0 will use the default behavior.

These two settings provide administrators complete control over the effect this new behavior has on custom solutions and add-ins used in the enterprise. During evaluation of Outlook 2010 beta, it is important that organizations test any custom solutions using Outlook add-ins to ensure compatibility with this change.

Application Shutdown Changes in Outlook 2007 Service Pack 2 Beta

Ryan Gregg — 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.

Use the Right Events for the Right Cases

Ryan Gregg — Wed, 27 Aug 2008 21:25:00 GMT

One of the problems I often hear about from Outlook developers is that the sequencing of a particular event isn’t ideal for what they are trying to do. While sometimes this can be a hole in the Outlook platform, more often than not it’s because the developer isn’t using the best event for the scenario they are trying to build. Outlook often has multiple events that fire related to particular actions in the UI, and choosing the right event is important to ensure data consistency.

For example, recently I was helping a partner team who wanted to examine the contents of a meeting request when the user has actually sent the request. During this event, they would compare the state of the meeting in their system against the meeting that the user was sending, and fix up any inconsistencies in their database. The developer had found the AppointmentItem_Send event in the object model, and naturally presumed that was the right event to use. However, they started to notice that inconsistencies were occurring between items in Outlook and their database. Multiple-client issues aside, the problem is because of the event they used.

The Item_Send event fires when the user clicks the Send button on sendable items (Meeting requests, e-mail messages, etc). However, there are cases where the user can back out of sending the item after they click the send button. In this particular case, when a meeting is changed, the user is sometimes given a choice to send the updates to added/removed recipients, or to all recipients. If the user clicks cancel on this dialog, the send is canceled even though the Send event has fired.

To work around this issue, I instructed the developer to listen for the Application_ItemSend event instead. This event fires after the user has committed to sending the message and ensures that the recipients on the item reflect the state of the item after the inspector has been closed.

Likewise, there is a Close event on each of the item classes, as well as a Close event on the Inspector object. To ensure that you inspect the contents of the item after all edits have occurred, catching the Inspector_Close event will provide you with the best chance to see that information. After Item_Close has fired, there is still a chance the user will back out of the changes (for example, if they click No to save their changes).

There are times where using the Item_Close and Item_Send events are very useful though. For example, if you want to be able to cancel the event and prevent the item from being closed or sent, these events have a Cancel parameter which can be set to True to prevent the action from occurring. The more deterministic events on the Inspector and Application object are not cancelable, because that would affect their determinism.

Using WPF in Outlook Folder Home Pages

Ryan Gregg — Tue, 15 Jan 2008 02:33:23 GMT

One common question developers have asked is how they can extend the view area of Outlook to display additional information related to the contents of a folder. Our solution to this problem is to use a Folder Home Page along with the Outlook View control to enable you to customize the look and feel of a folder, while still displaying folder information.

One example of an Outlook folder home page that ships with Outlook is the Outlook Today page, which is accessible by clicking on the top most folder in your default store.

Lately, developers have been interested in how they can leverage some of the new .NET Framework 3.5 enhancements like WPF in this space. Hülya Pamukçu has recently posted an article over on the CSD End-to-End Team Blog about this very subject. In the article Hülya covers how to host WPF controls inside a folder home page and how to leverage the Outlook View Control in the space at the same time.

Command Line Parameter Changes in Outlook

Ryan Gregg — Mon, 03 Dec 2007 19:00:18 GMT

As part of SP3 for Outlook 2003 (and included in ~~SP1 for~~ Outlook 2007) we’ve made a change to the way command line parameters are parsed to ensure Outlook is always doing the right thing. As part of this change, a less common way of attaching files to new e-mail messages through command line parameters with Outlook may be broken in some solutions.

Previously, Outlook under some circumstances would handle an implicit command line parameter without a switch. For example, if a command line argument was provided without a switch, and was a path to a folder in the file system, Outlook would treat the argument with an implicit /select switch flag, displaying that folder in the Explorer window. If the argument was a path to a file on the file system, Outlook would use an implicit /a switch and attach the file to a new message.

As part of making sure that our command line parameters were handled in a predictable manner, we removed the implicit logic in these service packs. You must now explicitly specify the appropriate switch before the path to a folder to display or file to attach. If a solution calls Outlook using an argument without a switch or with an invalid set of switches, the following error is displayed:

For more information on the valid command line switches that are supported by Outlook, take a look at our online documentation for command line switches.

There are a few applications that I’m aware of that have already run into this problem. I wanted to blog about it and make sure everyone knew what was going on and how to fix a solution that no longer works as expected. Command line parameters should always be preceded by a command line switch specifying what to do with the parameter.

Edit: This change was included as part of Outlook 2007 RTM, not just SP1 as I originally stated.

Why are you still using ECEs?

Ryan Gregg — Sat, 13 Oct 2007 01:35:13 GMT

Stephen Griffin is asking this question over on his blog. If you're using Exchange Client Extensions and haven't been able to port your solution over to an add-in (for a reason other than budget concerns or legacy support), now would be a good time to chime in and let him know why.

Common Properties on Outlook Controls

Ryan Gregg — 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).

Microsoft Office System Developer Conference 2008

Ryan Gregg — Mon, 17 Sep 2007 20:51:32 GMT

I just noticed that the official site for the 2008 Microsoft Office System Developer Conference has gone live. For the first time this year, the conference is open to the public, so any and all Office System developers can attend. The conference will be in sunny San Jose, Feb 10-13, 2008 (and the weather should be a welcome change from Seattle's rainy Feburary weather).

The converence will provide an oppertunity for architects, developers, industry experts, and Microsoft insiders to come together to discuss developing solutions around the Office System. Should be a good event for everyone with an interest in developing solutions for the current and next generations of the Office System.

Registration will open in October. For more details about the event, check out www.odc2008.com.