Ryan's Look at Outlook Programmability : Object Model

Additional Shutdown Changes for Outlook 2010 Beta

rgregg — 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

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.

Use the Right Events for the Right Cases

rgregg — 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.

Why are you still using ECEs?

rgregg — 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

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.

Updated Samples for Outlook 2007 Developers

rgregg — Wed, 14 Feb 2007 20:25:13 GMT

Last week we uploaded revised versions of our sample code for Outlook 2007 add-ins. The biggest change to these samples is that they are now provided as both a shared add-in project and VSTO 2005 SE project, so that you can see how add-in development would work using either technology.

These samples should give you a good basis for working with form regions, custom task panes, rules, the Table and PropertyAccessor objects, Ribbon extensibility and context menu customization.

You can download the latest samples from the following links:

Post B2TR Changes for Form Regions

rgregg — Thu, 12 Oct 2006 19:06:16 GMT

Shortly after we released Outlook 2007 beta 2 technical refresh to the world, we took a change on the Outlook platform to enable a new method of retrieving manifest and icon information for Outlook form regions. The reason for this change was partially due to customer feedback we received during the beta, that add-in developers didn't like needing to write some files to the disk, while others could be included as resources.

Unfortunately, this change required adding two additional methods to the FormRegionStartup interface defined in the Outlook type library. The end result of this change is that when the final version of Outlook 2007 is released, some solutions that compiled and ran against Outlook 2007 B2TR may need to be updated before they will compile against Outlook 2007 RTM.

While you will need to update any solution that uses form regions in order to compile it against Outlook 2007 RTM, existing solutions that were previously compiled should continue to run successfully on the RTM build even with this change. The additional functions were added to the end of the interface VTable and thus won't interfere with the existing methods provided in B2TR.

Using the New Methods

The two new methods added in the RTM builds are:

public object GetFormRegionManifest(string FormRegionName, int LCID)
public object GetFormRegionIcon(string FormRegionname, int LCID, Outlook.OlFormRegionIcon Icon)

GetFormRegionManifest expects a string containing the manifest XML to be the return value. If anything else is provided, the form region will not load.

GetFormRegionIcon can return either a byte-array that represents the original bytes of the image file, or an IPictureDisp object. For more information on how to convert a .NET Image or Bitmap over to IPictureDisp, check out this article on the VSTO blog.

Outlook will only call these methods on the interface if we find a the registry entry that previously was required to point to a file path or include inline XML now contains the ProgID of an add-in installed in Outlook, prefixed with an equal sign (=). For example, if your add-in was named "OutlookAddin1.Connect", you could write the following value in the registry: "=OutlookAddin1.Connect" and Outlook would then call these functions to request the manifest information for the form region.

These are a few changes worthy of pointing out when using this method:

The <name>, <layoutFile>, and <addin> elements of the form region manifest are ignored when provided via GetFormRegionManifest. The form region name is the name of the registry value for the form region, and we already know the ProgID of the add-in.

Child elements of the <icons> element should either be empty elements (like <page/>) or should contain the word "addin" if Outlook should call GetFormRegionIcon for that icon. When the add-in provides the manifest, all icons must be provided via GetFormRegionIcon and cannot be pointers to a file path.

If you have any questions about the behavior of these new methods, please comment on this post. I'd like to make sure that this isn't a big surprise for anyone working in the form region space when we ship Outlook 2007. I'll also be updating our form region samples to implement and use this new method when we release the RTM versions of our sample code.

Third Party Add-ins and Outlook 2007

rgregg — Mon, 11 Sep 2006 23:38:03 GMT

While we spend a great deal of time and effort to ensure that the Outlook platform is 100% backwards compatible with previous versions of Outlook, occasionally add-ins do something unexpected, or use the platform in an unexpected or undocumented way. These add-ins can misbehave and cause problems when running against a new version of Outlook (such as Outlook 2007) where they have not been fully tested by the software developer.

Many beta testers found this out the hard way during the Office beta 2 release when some very popular add-ins caused Outlook to crash unexpectedly while sending mail or performing other common tasks.

I've been working closely with a number of ISVs and software developers to ensure that these problems are fixed correctly. Sometimes we've broken the way something works and we have to fix it on the Outlook side. Sometimes the problem lies in the way the add-in works and the add-in needs to be updated. Often this means that the end user needs to disable the add-in until a new version is available.

Because add-in release cycles are not necessarily tied to Office/Outlook releases, this can cause a problem for some users. In the interim between when a new version of Outlook is released and add-ins are updated, you may need to disconnect an add-in to continue to use Outlook effectively.

To Disconnect an Misbehaving Add-in:

Start Outlook. If you cannot start Outlook because an add-in is causing it to crash immediately, you should be prompted to disable the add-in (in B2TR or later builds), otherwise use the command line outlook.exe /safe to boot in safe mode.
From the Outlook window, select the Tools menu, and then Trust Center.
Click on the Add-ins tab, and then click the Go button at the bottom of the page.
Disable one or more third party add-ins listed in the dialog. If you were directed here from a crash report, you should have seen information on which add-in was responsible for the crash. Find that add-in and uncheck the box next to the add-in.
Click OK.
Restart Outlook.

To Enable a Disabled Add-in:

If you're a developer working on an add-in, and Outlook has disabled it, or you are a user who wants to try an add-in again that was previously disabled, you need to access the Disabled Items dialog to enable the add-in. While you can access this from the Trust Center via the Add-ins tab, the easiest way in Outlook is to select the Help menu, then Disabled Items. Find the add-in on the list of disabled items, select it, and click the Enable button to enable the add-in again.

Keep in mind that if the add-in was disabled, it's likely because Outlook believes the add-in is misbehaving. There are some add-ins that are disabled immediately when Outlook is installed, and others that are disabled because Outlook detected a problem. In all cases, you should only enable an add-in again if you are sure that it is not causing any problems in Outlook.

Technical Details for Changes in Beta 2 Technical Refresh

If you aren't a developer or a technophile, I suggest you skip this part.

In response to a number of third party problems we've seen during the Beta 2 release of Outlook, we've made a change to the add-in resiliency logic that Outlook uses. Early in the Outlook 2007 release cycle, we decided to make a change to the way Outlook handles errors from installed add-ins. Previously Outlook would catch exceptions from add-ins and silently ignore them. This prevented Outlook from crashing immediately, but Outlook usually would crash later because memory somewhere had become corrupted, and it was just a matter of time before this caused a problem. For Outlook 2007, we now crash immediately when the add-in throws an error, allowing us to better understand the root cause of the failure. Instead of crashing later in some random code, we now crash at the actual cause. However, this change caused Outlook to crash a lot more frequently due to a number of add-ins that expected to be able to throw exceptions without consequence (which is a really bad expectation).

Previously in Outlook 2003, if an add-in caused Outlook to crash while the add-in was being initialized (OnConnection) or disconnected (OnDisconnection), then the add-in could be added to the disabled items list, which prevents the add-in from being loaded or running. If an add-in crashed later, say in an event handler (the most common place we saw crashes in beta 2), then Outlook would crash, and the add-in would not be disabled. This meant that it was possible to have a very bad experience in Outlook where every time Outlook boots, it crashes due to a misbehaving add-in. The only recourse was to use safe mode to disable the add-in, which most users would not immediately discover.

Now, in B2TR Outlook will also perform the same resiliency action if the add-in causes Outlook to crash during an event handler. Outlook will still crash, but upon the next boot of Outlook, you will be presented with a dialog asking if you want to disable the add-in. This way, users who are seeing a large number of add-in related crashes in beta 2 should only see a couple of crashes in beta 2 technical refresh because the add-in can be disabled easily by the user (and we default to disable if the user accepts the prompt defaults).

Blog Q&A

rgregg — Sun, 03 Sep 2006 01:43:26 GMT

A while back while I was taking about forms, I got a number of questions from readers out there in web land who wanted to know more detailed answers to some questions. I haven't been ignoring you, I promise, but we've been super busy getting Office 2007 beta 2 technical refresh ready for public consumption. Now that the B2TR bits are basically done, I've got a few free minutes to get back to answering questions and blogging in general.

Previously I was discussing some of the new forms technologies in Outlook we've dubbed 'form regions'. Form regions are designed to make it easier to do the kinds of UI customizations most developers have been trying to accomplish without the overhead involved in redesigning an entire Outlook form and worrying about how to publish it to Outlook. While I was on that subject, I got a number of questions, which I will now answer.

[Note, some of these questions have been edited to be more concise (or to actually be questions)]

Q: Is there a future for the Outlook view control (OVC)? If there is, include it with Outlook and make it easier to work with.

Well, the short answer here is that the control is of course still shipping in Outlook 2007. However, we did not make any significant investments to the OVC for this release. The OVC has been included as part of the Outlook installation since Outlook XP (for Outlook 2000 it was a web download). We are evaluating the needs of our platform and how we can improve the OVC, so if you have any scenarios you are trying to accomplish today where the OVC is falling short, please let us know.

Q: Have the form controls been improved?

Totally. We realized very early on in the 2007 release that our forms were starting to look dated and we needed to clean up their appearance. As part of the form region effort we created new Outlook controls (Olk* in the type library) that are more modern versions of the form controls previously available for custom forms. We also created a bunch of new controls that provide functionality available in Outlook, like the business card preview, date/time pickers, info bar, category, and page controls. These new controls when used on form regions enable a form designer/developer to really replicate the look and feel of the Outlook interface without needing to clone the interface in your own custom controls.

Q: Is the IDE for form script any better?

While we haven't improved or changed the script editor component that is used for 'legacy' custom forms, form regions are built using a whole new model. Instead of writing code inside Outlook that is embedded as part of the form, form regions rely on an add-in to provide the business logic behind a form region. This means that you can use your favorite programming language and IDE as long as they support building a COM add-in. With form regions you can use whatever language you prefer to back your form. You can read more about how to make this happen in my MSDN article "Building an Outlook 2007 Form Region with a Managed Add-In". We're also working closely with the Visual Studio Tools for Office (VSTO) team to further improve the story for the Orcas release, but details of what may be available in this release are still TBD.

Q: How do you envision people debugging code on forms?

Script debugging has been a painful process for forms developers. Fortunately, since Outlook 2007 form regions no longer use script, but instead use an add-in, the debugging experience is much improved. You can debug a form region in exactly the same way you would debug an Outlook COM add-in, using Visual Studio or another IDE. Just attach to Outlook (or just run your project if you are using a VSTO-based add-in), insert breakpoints, watches, etc, and wait for an error to occur. If you're using Visual Studio 2005 and managed code for your add-in, you can even do edit-and-continue, just like with other managed code.

Q: Do you see people continuing to use Public folders?

I think it should be clear that public folders will continue to play a role in the short term future. However, if you look at the direction Exchange 12 is moving, you'll see public folders are now an optional component to the Exchange system. For Outlook 2007 we've converted a lot of features that used to rely on public folders over to using web services or found other mechanisms for replacing the functionality of public folders. Custom solutions that depend on public folders will need to start being migrated over to other technologies as well, because public folders are a legacy technology that are on the way out. Using SharePoint may be one good way of migrating a solution, but other alternatives as also available. One of the reasons we developed the form region technology was to allow organizations to have form solutions that didn't depend on the Organizational Forms Library (which uses public folders) and still be able to relatively easily deploy forms across an organization.

Q: Was work put into improving custom forms management/deployment?

Outlook 2007 maintains the functionality provided by Outlook 2003 for custom forms management and deployment via Outlook. However, our form regions are designed to work differently. Instead of using a forms library that needs to managed inside Outlook, form regions are registered via the Windows registry and XML-based manifest files. For deployment, form regions are designed to use any installer technology you might use for an Outlook add-in, such as Windows Installer (MSI) or ClickOnce deployment. Since form regions are tied closely with add-ins, they do not live in the forms cache and are not subject to the issues around forms cache corrupt that occasionally caused issues for our custom forms in the past.

Q: OWA/Mobile. Design once, run everywhere is a definite necessity, will this story be improved?

For Outlook 2007 this story remains unchanged. There are some big issues to face, like how a form that looks good for a desktop client can be useful on a mobile device with a much smaller screen or as a web form. There are also issues around the replication of properties between desktop Outlook and mobile devices. However, I believe these are solvable problems, and for the next release of Outlook I hope we can spend some time in this space and improve the story over what we currently offer.

Q: Is WYSIWYG forms printing supported in Outlook 2007?

Outlook 2007 still maintains the status quo for printing support of custom forms. However, there are a few third party solutions available for Outlook 2003 that provides this support, and it's definitely something that a form developer can implement using a few Windows APIs. I hope for the next release that we can address this concern and improve the support for printing custom forms.

Q: Progress and Excitement. Do you think there is a REAL commitment within the Outlook team for extensibility?

There is a very real commitment on the Outlook team for extensibility. For Outlook 2007 we've actually doubled the number of classes defined in the Outlook type library, flushing out a huge range of new functionality that previously wasn't available. For the next release we're already looking into how we can continue to expand on what we've done in this release and make the platform easier to work with and friendly for developers, and also allow developers to do more with Outlook. For Outlook 2007 we've had two program managers and a team of developers and testers working to improve the object model, so we are definitely committed to improving extensibility. Randy Byrne and I are also working on a new Outlook programmability book which we hope to have available close shortly after Office 2007 is available.

Q: Other questions relating to Exchange extensibility.

Unfortunately I'm rather disconnected from what is going on over in Exchange extensibility. I'll have to follow up in another post on these questions. In the mean time, readers may want to direct those questions to the Exchange team blog, "You had me at EHLO".

That's it for the questions I have right now. I've got a few other blog topics I hope to get to shortly, but as usual my time is scarce. I hope to be more prolific with my posts in the near future, especially as the beta 2 technical refresh becomes available. In the mean time, I hope you have a great Labor Day weekend!

Outlook Shutdown and COM Add-ins

rgregg — Tue, 27 Jun 2006 18:20:00 GMT

Depending on how familiar you are with Outlook development, you may have seen previous versions of Outlook occasionally had a problem shutting down. Often there could be a catch-22 situation, where the add-in was waiting to hear from Outlook that it should clean up its references, and Outlook was waiting for these references to be released before notifying the add-ins that it was shutting down. In previous versions, Outlook only paid attention to the number of references for the OM objects, and not if those references were held by add-ins.

For Outlook 2007, our developers spent time investigating the problem, and came up with a fix that has caused the shutdown issues for Outlook to largely disappear, even when running managed code add-ins. There are, of course, a few limitations to what can be done, so it's important that Outlook add-in developers understand what this work buys them and what they still need to do to ensure an add-in solution doesn't keep Outlook alive.

Outlook now keeps track of references which it knows were handed out to an Outlook add-in. References provided to an add-in and those derived from objects provided to an add-in are tagged as belonging to that particular add-in. When the UI is closed and the only remaining references are tagged as blonging to add-ins, Outlook will shutdown. If a reference tagged for an add-in is marshaled out to another process, these references can be disconnected from under the application when Outlook shuts down.

There are a few scenarios through which Outlook can lose track of an add-in reference on an object. For instance, accessing Outlook objects through non-Outlook libraries, such as returning a reference to the Application object through the command bars OM (accessing properties like Application or Parent), can cause the context to be lost. We've done work to improve the way this works with some new Office APIs to make sure that the context is not lost. For example, when working with the ribbon UI integration, objects provided in ribbon callback methods will still be in the context of the add-in. Likewise, using the new Custom Task Pane OM provided by Office will not get you in trouble either.

Another possible scenario is if the add-in creates a new instance of the Application object (new Application() or calling CoCreateInstance) and then marshal this object (or derived objects) to another process or thread. Outlook will be unable to track these objects as belonging to an Outlook add-in. When the reference is marshaled to become a strong external reference, Outlook will not shut down properly until the reference is cleaned up. Technically speaking, Outlook will remain alive if there are external connections registered through the IExternalConnection interface of COM on any OM objects.

These changes to our shutdown logic apply only to add-ins and internal references. The behavior for COM callers outside of the Outlook process space hasn't changed. Programs that CoCreateInstance the Outlook Application object can expect that Outlook will remain alive, even if the user attempts to quit the process, until those references are released as long as these references appear to be external connections to Outlook.

The benefit of these changes should be pretty clear: COM add-ins will no longer need to implement some kind of shut down workaround which was previously a popular sight in any Outlook add-in code. The change also lowers the bar to writing a COM add-in that doesn't break Outlook. New Outlook developers won't need to know about any sort of hacks or workarounds to make sure Outlook shuts down in the appropriate way. They can rely on seeing the OnBeginShutdown and OnDisconnection methods be called as Outlook prepares to shutdown and actually shuts down.

Final note: Developers shouldn't use this as an opportunity to be lazy though. You should continue to write clean code that properly cleans up and releases your references whenever the add-in has finished using that object. Cleaning up references to Outlook objects is important for memory utilization and performance implications. Each OM object reference kept alive also requires Outlook to keep the internal representation of that item alive, including any server connections required by that object. This can produce exceptions under unexpected conditions that can be avoided by properly releasing these objects when the add-in is finished with the object.

Using VSTO v3 CTP with Outlook 2007

rgregg — Wed, 05 Apr 2006 23:26:00 GMT

If you are excited about managed add-in development and Outlook 2007, you've no doubt heard about the CTP release for VSTO v3 (VSTO is Visual Studio Tools for Office). This release enables developers to start working with managed code add-ins using the VSTO environment and targeting Outlook 2007.

Of course, this VSTO release is very early in the cycle and not all of the features are code complete or event included yet. This release is primarily targeting the runtime environment and making sure that things work. The side effect of this is that some extra "glue" is required to use some features. Andrew has a nice post over on his blog about how to use Form Regions with VSTO v3, so if you are interested I'd suggest you take a look.

Outlook form regions

rgregg — Sun, 26 Mar 2006 19:54:22 GMT

Outlook 2007 includes a new way of customizing the Outlook user interface for data in Outlook. If you have used previous versions of Outlook and had a need to customize our forms, you know that in the past custom forms in Outlook were a bit of a challenge.

If you were interested in working with any built-in form other than the mail, post, or contact forms, you were limited to adding additional tab pages to the standard page. Even if you were interested in customizing the contact form, you couldn't replicate the look and feel of the standard Outlook form. Custom forms were also never displayed in the Reading Pane, which is how a lot of users work in their mailbox. Additionally, once you had a form designed, to write code behind the form for business logic and validation you were stuck using notepad. Finally, after the form was working just the way you wanted, the Outlook forms cache could swallow the form and Outlook would end up just using the standard form anyway.

An adjoining region in a mail note

Because of these issues, for Outlook 2007 we introduced a new mechanism for form customization we've named "form regions". Our goal was pretty simple: reduce the difficulty for doing simple customizations on the one hand, while ensuring that rich integrations could reproduce the look and feel of Outlook built-in forms without major compromises. To this end, Outlook 2007 supports two types of form region customizations: adjoining regions and separate regions:

Adjoining regions enable you to provide purely additive "regions" to the bottom of the first tab of an existing form (custom or built-in). These regions are also, optionally, displayed in the Reading Pane of Outlook. For instance, if you want to add a few additional fields to a built-in Outlook form, an adjoining region would be a good approach.
Separate regions can either be added to an existing form, or they can replace one or all of the tabs on an existing form. If the solution requires that the entire form be customized, or if you would like to add data into the middle of an existing form, or on a separate form page, then separate regions are a good choice. Separate regions that replace the first form page are also displayed in the Reading Pane of Outlook.

Form regions work in the reading pane as well

Outlook 2007 also includes a number of new form controls that provide the business logic and behavior users expect from Outlook forms. We've included a contact photo control, date and time picker controls, Electronic Business Card preview control, and several others so that custom forms can finally have parity with our built-in forms. We've also made sure that all of the included forms controls support Windows themes. No longer will your custom forms look like they were made in 1995.

Another benefit of Form Regions is that instead of writing your code in notepad and VBScript, form regions are designed to be driven with an add-in. Thus, you can work in your favorite development environment and take advantage of all the features it provides. You just implement a new interface, FormRegionStartup, and your form will be off and running in no time. You can listen for a full range of events on the controls, monitor other Outlook data and respond accordingly, and retrieve data from non-Outlook sources for displaying on your form region, all from the comfort of your favorite programming language.

Because of the close connection to an add-in, Outlook form regions are installed as part of your add-in, thus simplifying the deployment model for Outlook customizations. Your add-in setup project just needs to write an XML manifest that describes the region to the registry or the local disk, and then register that manifest with Outlook. When Outlook is ready to display your form region, it will call back on the FormRegionStartup interface to ask your add-in for all the details. Installing your form locally with the add-in also means that form regions will continue to work in the same way even when running against an Exchange server without public folders.

With beta 1 and beta 1 technical refresh, the Outlook team has released a sample named "Travel Agency" which provides an example of a separate form region customizing the Outlook contact form with an additional form page. These samples have been posted on Beta Place for you to download and try out. Starting with beta 2, we will have an updated sample that includes an adjoining region as well.

I'd really encourage the developers out there to try out this new UI customization. Download the samples and check out what you can do. If you caught some of the MIX06 conference, you may have noticed the Outlook/EBay add-in, which was also built using Outlook form regions.

New code samples available for download

rgregg — Tue, 17 Jan 2006 22:06:00 GMT

If you’re an Outlook developer who has been excited to hear about all of the cool new work done for Outlook 12 but didn’t know where to begin, I now have an answer for you. We’ve finally (sorry for the delay) posted 3 sample add-ins to BetaPlace. These add-ins will help you learn by example how to use some of the great new extensibility features of Outlook 12. All three add-ins are written in managed code, but without using VSTO as an Office 12 compatibility version of VSTO has not yet been released.

We took the extra step of releasing all three add-ins in both C# and VB based on feedback from the labs at PDC indicating samples in C# weren’t helpful for those VB developers out there. We plan to continue releasing the sample code in both languages.

These three add-ins were available on BetaPlace starting on Monday:

Prepare Me Add-in
The Prepare Me add-in showcases the new Custom Task Pane technology that has been included as part of Outlook 12. The Prepare Me add-in provides a task pane to help prepare for meetings on your calendar by showing information about the attendees, recent mail items from each attendee, and quick links to related meetings and items assigned to the same categories. If you did the PDC 2005 hands on lab for Outlook this add-in should be familiar to you. For Beta 1 we’ve updated the add-in to include support for the new UI in Outlook inspector windows. Prepare Me also demonstrates the usage of the table, property accessor, context menu customization, programmatic search, categories, and exchange user.

Rules Add-in
The Rules add-in show how easy it can be to replace Outlook UI to provide a custom experience for a user. In this case the add-in repurposes the “Create Rule” context menu entry point with a WinForms dialog that supports creating custom rules for the selected item. This add-in makes use of the rules object model, property accessor, context menus, and the select names dialog.

Travel Agency Add-in
The Travel Agency add-in is an example solution demonstrating Outlook’s new Form Regions. This add-in displays adds a “Booking” page to the contact inspector that allows travel preference information to be associated with each contact. Additional the extra tab allows for viewing and creating new travel itineraries for the selected contact. Behind this region business logic and itinerary processing code lives in a Outlook add-in running behind the form.

I hope all the Outlook developers out there take a look at these samples and start to learn how to use the next extensibility features of Outlook 12. There is a lot more still available that we haven’t shown off yet, so please play around too. If you have any questions about the samples or getting them to work, post on the Office 12 beta newsgroups or send me a comment here.