Post B2TR Changes for Form Regions

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.