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:

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="https://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;

Also declare some variables in the Add-in Module:

        private UserForm form;
        private Outlook.OlkTextBox OlkTextBox1;
        private Outlook.OlkCommandButton CommandButton1;

9. 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.

10. 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