Eugene Astafiev

How To: Design Outlook form regions with Add-in Express 2010

Today I want to show you how to use Outlook Form Regions that were introduced in Outlook 2007 with Add-in Express based add-ins. In my sample projects I will use Outlook 2010 as its popularity grows up with the oncoming release date. Also, I will use Add-in Express 2010 to demonstrate that our team do not go round in circles from year to year. We move forward together with Office developers ;-)

Sometimes you may not want to use Add-in Express Advanced Outlook Regions for various reasons. For example, imagine the following: you migrate from VSTO to the Add-in Express framework, you are happy with the GUI and don't want to change anything, you just want to leave it as is. The solution is to use the standard Outlook Form Regions. I have to admit that I have never used standard Outlook form regions in my add-ins that I wrote with Add-in Express, I have always used Advanced Outlook Form and View Regions provided by Add-in Express. It saves me from a lot of headache. To start with Microsoft Outlook Form Regions please have a look at the following page. That article gives you a step-by-step guidance on how to create a simple VSTO add-in with an Outlook form region. A bit later, I will also give you a complete list of steps to create a sample add-in based on Add-in Express with a form region embedded. Ok, let's start developing!

You can design form regions only in Microsoft Office Outlook 2007 and 2010, still Beta : ( Later we will import a newly created form region into Visual Studio 2010.

Designing a form region in Outlook 2010

  1. Start Outlook 2010.
  2. Click the New E-mail on the ribbon.
  3. In the newly opened Inspector window, click File | Options | Customize Ribbon. Find the Developer tab in the right-side list of available controls and select it. Click OK. Now you can find the Developer tab in the Inspector ribbon.
  4. Navigate to the Developer tab.
  5. Click the Design a Form button.
  6. In the Design Form dialog, click Message and then click Open.
  7. Find the New Form Region button in the Ribbon and click it. A new form region will open. Also, find the Field Chooser and Control Toolbox buttons on the Ribbon.
  8. Drag the Subject field, for example, from the Field Chooser to the form region (or you can use any e-mail field of your choice).
  9. Drag a CommandButton control from the Toolbox to the form region.
  10. In the Ribbon find the Save Region button and click the Save Form Regions As… Name the form region MyFirstFormRegion and save it to your My Documents directory (you can use any).
  11. Close Outlook 2010.

You can see the result of designing a form region in the screenshot:

Designing a form region

After you designed a form region you can start developing an add-in.

  1. Create a new Add-in Express based add-in for Outlook in your preferred language. You can download the complete sample projects in C# and VB.NET (see the links at the end of the page).
  2. Open the designer of the add-in module and add the Outlook events component there. Use the Add Events item of the module context menu.
  3. Find the Form Regions category in the list of events (see Outlook events component). Generate event handlers for the following events:
    • OnGetFormRegionStorage

    In the OnGetFormRegionStorage event handler, you must return an Outlook form region itself.

    • OnBeforeFormRegionShow

    In the OnBeforeFormRegionShow, you can do any preparations before a form region is shown. In a sample add-in, I just print a debug message.

    • OnGetFormRegionManifest

    In the OnGetFormRegionManifest, you must return a valid manifest file for the form region.

    • OnGetFormRegionIcon

    In the OnGetFormRegionIcon event handler, you can return any icon for the form region. That event handler will be called only if you specified the "addin" value in the <icons> tag of the form region manifest.

  4. In Visual Studio, navigate to the Properties of the project and select the Resources tab. Add the form region created earlier (MyFirstFormRegion.ofs) as a resource.
  5. Create a new string in the Resources of the project and name it Manifest.
  6. Add the following content to the just added string:
    <?xml version="1.0" encoding="utf-8"?>
     
    <FormRegion xmlns="http://schemas.microsoft.com/office/outlook/12/formregion.xsd">
      <name>Eugene Astafiev</name>
      <formRegionType>separate</formRegionType>
      <formRegionName>Eugene Astafiev</formRegionName>
      <showInspectorCompose>true</showInspectorCompose>
      <showInspectorRead>true</showInspectorRead>
      <showReadingPane>true</showReadingPane>
      <icons>
        <default>addin</default>
        <page>addin</page>
        <window>addin</window>
        <unread>addin</unread>
        <read>addin</read>
        <unsent>addin</unsent>
        <submitted>addin</submitted>
        <replied>addin</replied>
        <forwarded>addin</forwarded>
        <signed>addin</signed>
        <encrypted>addin</encrypted>
      </icons>
    </FormRegion>

    Please take notice of the <icons> tag. The "addin" value tells Outlook that the add-in provides an icon for the form region.

  7. Go to the References folder of the add-in project and remove the Interop.Outlook.dll reference. Add a new reference pointing to Outlook using the COM tab of the Add Reference dialog.
  8. Add a new reference (use the COM tab of the Add Reference dialog) to the Microsoft Forms 2.0 library and add the following "using" statements in the code:
    using Microsoft.Vbe.Interop.Forms;
    using Outlook = Microsoft.Office.Interop.Outlook;
  9. Also declare some variables in the Add-in Module:

            private UserForm form;
            private Outlook.OlkTextBox OlkTextBox1;
            private Outlook.OlkCommandB
  10. Now we can fill the event handler within the code.
    • In the OnBeforeFormRegionShow event handler I add just a debug message and add an event handler for the button I added when was designed the form region:
    Outlook.FormRegion region = formRegion as Outlook.FormRegion;
                form = region.Form as UserForm;
     
                try
                {
                    OlkTextBox1 = form.Controls.Item("OlkTextBox1") as Outlook.OlkTextBox;
                    CommandButton1 = form.Controls.Item("btnSayHello") as Outlook.OlkCommandButton;
                    CommandButton1.Click += new Outlook.OlkCommandButtonEvents_ClickEventHandler
                    (CommandButton1_Click);
                }
                catch (Exception ex)
                {
                    System.Windows.Forms.MessageBox.Show(ex.ToString());
                }

    Also I added an event handler for the Click event of the button that I added on the form region:

    void CommandButton1_Click()
            {
                System.Windows.Forms.MessageBox.Show(OlkTextBox1.Text);
            }
    • In the OnGetFormRegionManifest event handler:

    e.Manifest = Properties.Resources.Manifest;

    • In the OnGetFormRegionStorage event handler:

    e.Region = Properties.Resources.MyFirstFormRegion;

    • In the OnGetFormRegionIcon event handler I added a simple debug statement that confirms that the event was fired up. You can use IconObj to set up the icon for the form region:

    System.Diagnostics.Debug.WriteLine(“OnGetFormRegionIcon”);
    BTW, I added such a debug statement in all event handlers.

  11. Our add-in is ready now. You can register it and run the host application (Outlook in our case) to make sure that it works properly.

Oh… I didn't see that my form region and event handlers were not triggered at all. You may ask why? But how can Outlook know about form regions that add-ins provide? The answer is an old fashioned one – windows registry does the trick. Before running Outlook with the registered add-in, which contains a form region, you need to add a windows registry record (it will tell Outlook that a form region for the add-in must be loaded). Navigate to the following hive:

HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions

Create a new subkey IPM.Note (the message class that you want a form region to be shown for) and add the following key with a string value:

The key is "MyFirstFormRegion" and the value – "=MyFirstOutlookFormRegion.AddinModule". As you see, the ProgID of the add-in plays the role of key’s value.

Now if you run Outlook and open a mail item you will see a button in the Ribbon, clicking on it you can see our form region. My article is coming to the end now but I would advise you playing with a manifest text for a while;-)

Good luck with your add-ins and see you later!

Available downloads:

C# sample for Visual Studio 2005
VB.NET sample for Visual Studio 2005

You may also be interested in:

Microsoft Outlook regions
Add-in Express Advanced Outlook Form and View Regions

13 Comments

  • https://secure.gravatar.com/avatar/c88b62ae451a1601feb5243837576ef5?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Eric Legault says:

    Great article Eugene! Quick question: What if you wanted to load multiple form regions for the same item/custom message class? Use multiple elements in a single manifest? Or multiiple entries for the item/custom message class in the FormRegions\ registry key?

  • https://secure.gravatar.com/avatar/bbd979ae5b772d0bc1f82065aa4ba146?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Eugene Astafiev says:

    Hi Eric,

    The technique is common for all Outlook add-ins (it doesn’t matter whether you develop a VSTO or Add-in Express based add-in). You just need to add multiple entries to the windows registry representing a file path to the form manifests and then in the OnGetFormRegionStorage event handler return appropriate .ofs files (see the e.FormRegionName property).

  • https://secure.gravatar.com/avatar/794bf06f1a6a588eeef8ee043bc67e1e?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Mike VE says:

    Hi Eugene
    At first I thought this was just what I needed. I want to use a variant of the standard Appointment form but with all the controls hidden except the category display, the subject and main body. An Outlook .ofs file seemed the only way to do it. However, when you change the reference from the Interop to the COM you loose the ability to support earlier versions. I would like to support all versions from OL2003, though clearly only OL2007 and up could support this particular feature. Is there a way to do it?

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Mike,

    Outlook 2003 does not support native Microsoft Outlook Form Regions, this feature was introduced in Outlook 2007. Please consider using Add-in Express Advanced Form Regions instead.

    Thank you for your comment.

  • https://secure.gravatar.com/avatar/794bf06f1a6a588eeef8ee043bc67e1e?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Mike VE says:

    Hi Eugene
    Can I make a version-neutral add-in with OL2007 base, which I presume means using the Interop reference rather than a COM one which would fail if the right version of Outlook was not present? and use this feature?

    Add-in Express Advanced Form Regions are great but they do not support the Outlook controls I need – in particular the Category Control.

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Mike,

    I doubt that an add-in based on Outlook 2007 Primary Interop Assemblies (or COM references) will work properly in Outlook 2003. Microsoft Outlook Form Regions and Category Control (OlkCategory) definitely will not work.

  • https://secure.gravatar.com/avatar/794bf06f1a6a588eeef8ee043bc67e1e?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Mike VE says:

    Hi Eugene
    I’ll forget Outlook 2003. I want to support OL2007, 2010 & 2013 so I will use the OL2007 Interop redistributable. Is there any way I can use an .OFS file with that configuration? I just can’t get the things I need on an Adx Advanced Form Region, i.e. the action Outlook fields properly bound to the controls – particularly Category (to respond to category choices) and Body (to respond to the Format and Insert ribbons)

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Mike,

    Of course, if you use Outlook 2007 Interop Assemblies you can develop such an add-in. This blog post describes how to do this. If you have any questions or run into troubles feel free to ask me.

  • https://secure.gravatar.com/avatar/794bf06f1a6a588eeef8ee043bc67e1e?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Mike VE says:

    Hi Guys
    I have been exploring this using the VB sample. It all works fine using the manifest as supplied. However, I need to replace the default Outlook form so I tried changing the formRegionType. As supplied this is set to Separate and result is a Show group being displayed in the Ribbon with “Eugene Astafiev” as a button which, when clicked, shows the custom form.
    Changing the formRegionType to Adjoining results in the custom form being displayed below the default form.
    So far so good. However, changing the formRegionType to Replace just does the same as Separate – not what is required.
    If I choose the forth option in the MSDN documentation and set formRegionType to ReplaceAll then I just get an error message saying the xml is invalid and the default form will be used.

  • https://secure.gravatar.com/avatar/794bf06f1a6a588eeef8ee043bc67e1e?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Mike VE says:

    Ignore my last post. The formRegionType Replace is working fine in my own project. I am not sure what the difference is yet – except that it is in VS2008 rather tha VS2010 where I tried your sample. (This particular project I keep in VS2008 for reason to do with compatibility with the version of Crystal Reports most of my users have already.

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Mike,

    Thank you for the update. I am glad to know you got it to work!

  • https://secure.gravatar.com/avatar/f0254dda2c0f98e6d9bf6b8f6ec015ae?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Carson says:

    I have this working great for a set of MessageClasses, but the alpha transparency of my icon is not working.

    Do you know if it is possible to set the IconObj value with something that will honor transparency?

    Currently I’m converting a .ico that has transparency to an IPictureDisp and setting that into the IconObj of the OnGetFormRegionIcon event handler.

    This article shows how to do it for CommandBar buttons, but the ADXOlGetFormRegionIconEventArgs doesn’t expose .Mask:
    http://glassocean.net/how-to-convert-a-system-drawing-image-to-an-ipicturedisp-with-alpha-transparency/

    Any ideas?

    Thank you.

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Carson,

    https://msdn.microsoft.com/en-us/library/microsoft.office.interop.outlook._formregionstartup.getformregionicon.aspx suggests that you can pass an array of bytes representing the actual image.

Post a comment

Have any questions? Ask us right now!