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.
Comments
Anonymous
October 15, 2006
There have been some changes to the programming model for Outlook 2007 Form Regions. Full details...Anonymous
October 25, 2006
Ryan, when you refer to "a registry entry" above, is that the entry for the form's message class under the OutlookFormRegions key?Anonymous
October 25, 2006
The comment has been removedAnonymous
October 27, 2006
Form Regions look awesome but I've only seen mention of C#/VB in relation to them. Can you only use Form Regions in managed code? What about Exchange Client extensions that access OOM via IOutlookExtCallback?Anonymous
October 27, 2006
Murray, You can use form regions from any COM add-in, it doesn't need to be managed code. You can't use them via an ECE however. Solutions that use ECEs should be closely examined in the Outlook 2007 time frame to determine if they can be migrated over to COM add-ins.Anonymous
October 29, 2006
Ryan, We will be stuck with ECEs for quite some time, we need to support Outlook 2000/2002/2003 as well (2000 will be dropped soon). Up until know, ECEs where the most flexible, you had access to MAPI and to OOM. So to clarify, even though we can access OOM from our ECE, we can't use form regions. I'm assuming we could create a COM add-in that communicates to our ECE if necessary.Anonymous
October 29, 2006
Murray, Yes, if you need to continue using ECEs for your particular scenario, then you can certainly create a COM add-in to host form regions, and communicate between your ECE and the COM add-in.Anonymous
October 30, 2006
Ryan, If you implement use of these 2 new methods does GetFormRegionStorage still fire? What about BeforeFormRegionShow? In what order do these methods fire?Anonymous
October 30, 2006
Ken, Yes, the two other methods still fire. The sequence depends on when Outlook fires GetFormRegionManifest, which is fired the first time Outlook "needs" the form region details. This happens when an item with that message class scrolls into view, or is opened, or the user drops the Actions menu or the New Form dialog. The general sequence however will be: GetFormRegionManifest -> GetFormRegionIcon -> GetFormRegionStorage -> BeforeFormRegionShow.Anonymous
October 30, 2006
Ryan, one other question. I see no way to expand a form region in code or to force it to be not expanded. Is there some way to do that or plans to make IsExpanded read/write in the future or provide some other way of controlling the expansion of a form region?Anonymous
October 30, 2006
Ken, We don't have any plans to do that in Outlook 2007, although there is polciy around enforcing adjoining regions to be visible. I feel that the visibility of these reagions is a user preference, and not necessarily something that the solution should be able to force on the user. However, I'd be interested to hear more about the scenarios where you want to be able to control the state of the adjoining region.Anonymous
November 01, 2006
Hi Ryan, I can see if a form region required large amounts of processing or something that could take some time, such as retrieving data from a Web service, that the programmer might want to always have the form region open not expanded and let the user expand it if they needed access to it. Also, if code provided multiple form regions for different purposes it might be good to have them all not expanded on loading an item until a specific one was needed. KenAnonymous
November 01, 2006
Hi Ryan, You mention an OlFormRegionIcon enum. Can you provide the enum? It's not in the current tlb. Also, you mention that GetFormRegionIcon receives an Icon paramter. What's the purpose of passing that parameter to the event handler? Thanks, KenAnonymous
November 01, 2006
The enum OlFormRegionIcon looks like this: olFormRegionIconDefault = 1
olFormRegionIconEncrypted = 9
olFormRegionIconForwarded = 5
olFormRegionIconPage = 11
olFormRegionIconRead = 3
olFormRegionIconRecurring = 12
olFormRegionIconReplied = 4
olFormRegionIconSigned = 8
olFormRegionIconSubmitted = 7
olFormRegionIconUnread = 2
olFormRegionIconUnsent = 6
olFormRegionIconWindow = 10 These map directly to the values that can be defined in the form region manifest file. The method is called once per icon that is listed in the manifest file provided by GetFormRegionManifest. Outlook will only call for icons that are listed in the manifest, and not for all icon files to save time making useless calls. The value of the icon parameter in the method tells the add-in which icon is being requested. This enumeration will be in the RTM type library.Anonymous
November 02, 2006
Thanks.Anonymous
November 07, 2006
Hi Ryan, A question about some of the new Olk controls. If I use an OlkBusinessCardControl, OlkContactPhoto, OlkInfoBar or OlkSenderPhoto control (there may be a few others) in a form region, how can I get/set values for those controls? Or can I? For example, say I want to add a custom infobar control to a form region. Is there any way I can set the text content of that control? Or set/get the contents of the other controls I listed? Thanks, KenAnonymous
November 13, 2006
Hi Ryan, I've installed the release of the Office 2007 and the form region code that I was developing has stopped working. The RequestService never called for my region GUID. I've implemnted the new methods GetFormRegionManifest and GetFormRegionIcon but they never called. Is there anything else that have been changed in the release bits?Anonymous
November 13, 2006
Ken: Most of the Outlook controls are designed only to replicate the Outlook UI. You need to set the underlying properties on the item to affect the control, or in some cases you cannot modify the display of the control at all. In particular there is still no way to modify the text displayed on the InfoBar in 2007.Anonymous
November 13, 2006
Alex: If your solution worked properly in pre-RTM bits of Outlook, it should continue to work in RTM. Are you using VSTO 2005 SE to develop the add-in?Anonymous
November 13, 2006
Thx, Ryan, I've fixed the problem: http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=919135&SiteID=1Anonymous
November 14, 2006
Hi Ryan, when do you think the samples will be updated? I'm having a real hard time getting this to work on the RTM. After returning the manifest as a string in GetFormRegionManifest nothing happens?!? GetFormRegionStorage is never called?!? /SteenAnonymous
November 15, 2006
OK, thanks Ryan. Put that in the request bin then for OL13, the ability to modify values for the controls (along with the ability to expand/contract the form region from code). KenAnonymous
November 15, 2006
Hi Ryan, when do you think the samples will be updated bacuase I have a hard time getting this to work. /SteenAnonymous
November 20, 2006
I don't have an ETA on the samples, other than ASAP. We want to make sure the final version of the samples published for RTM are the highest quality we can provide, and so it's taking a little bit of extra time to get them out the door.