This documentation is archived and is not being maintained.

Outlook Form Regions Overview

Visual Studio 2005

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005


    Visual Studio Team System


    Visual Studio 2005 Professional Edition

  • VSTO 2005 SE installed in the development environment

  • 2007 Microsoft Office system

Use form regions to add custom functionality to standard Microsoft Office Outlook 2007 forms.

Form regions provide a range of options for presenting your custom user interface (UI):

  • Customize the default page of any standard form.

  • Add up to 30 extra pages to any standard form.

  • Replace or enhance any standard form.

  • Display custom UI in the Reading Pane in addition to the Inspector.

For more information, see "Customizing Form Pages and Form Regions" in 2007 Office System: Updated Developer Content.

Design the layout of a form region by using the Form Region Designer in Outlook 2007. You can then import the form region into an application-level add-in project and use managed code to handle events in the form region. To finish the form region, define form region properties and associate the form region with an Outlook message class.

For a step-by-step guide, see Walkthrough: Creating an Outlook Form Region.

Designing the Layout of the Form Region

Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE) does not have a form region design surface. As a result, you design the layout of a form region using the Form Region Designer in Outlook 2007. The Form Region Designer generates an Outlook Form Storage (OFS) file. This file describes the controls on the form region, and the positions of those controls.

Reference this file in your Outlook 2007 add-in project to define event handlers for controls on the form region.

Adding Managed Code Behind a Form Region

To add managed code behind a form region, create an Outlook 2007 add-in project. Add a custom class that implements the Microsoft.Office.Interop.Outlook.FormRegionStartup interface. This custom class is called the form region class. Within the form region class, implement methods to perform the following actions:

  • Return the OFS file to Outlook.

  • Handle events raised in the form region.

You must then create an instance of the form region class and pass that new object to Outlook. For more information, see Returning the Form Region Class to Outlook.

Returning the OFS file to Outlook

Outlook calls the FormRegionStartup.GetFormRegionStorage method to obtain the OFS file that describes the form region. To return the OFS file to Outlook, override the FormRegionStartup.GetFormRegionStorage method in the form region class.

When you create an Outlook add-in, you can add the OFS file to the resource collection of the Outlook add-in project. If you do this, you can return the contents of the OFS file to Outlook as a byte array. The following example overrides the FormRegionStartup.GetFormRegionStorage method and returns the contents of an OFS file that is named TaskFormRegion from the resource collection of an add-in project.

public object GetFormRegionStorage(string FormRegionName, object Item, int LCID,
    Outlook.OlFormRegionMode FormRegionMode, Outlook.OlFormRegionSize FormRegionSize)
    switch (FormRegionName)
        case "TaskFormRegion":
            byte[] ofsBytes = Properties.Resources.TaskFormRegion;
            return ofsBytes;
            return null;

If the OFS file is not a resource in your Outlook 2007 add-in project, return the string path of the OFS file. This path can contain environment variables, but the file must be local. The path can be either absolute or relative to the location of the form region manifest. The form region manifest is discussed later in this topic.

Handling Events Raised in the Form Region

Outlook calls the FormRegionStartup.BeforeFormRegionShow method before it displays the form region. Override this method in the form region class to handle events raised by user actions in the form region. Use the FormRegion parameter to obtain the controls defined in the form region.

The following example overrides the BeforeFormRegionShow method. The code in this method assigns controls from the form region to fields defined in the add-in. This code also registers an event handler for a command button on the form region.

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

public void BeforeFormRegionShow(Outlook.FormRegion FormRegion)
    this.FormRegion = FormRegion;
    this.UserForm = FormRegion.Form as UserForm;

        OlkTextBox1 = UserForm.Controls.Item("OlkTextBox1") as Outlook.OlkTextBox;
        CommandButton1 = UserForm.Controls.Item("CommandButton1") as Outlook.OlkCommandButton;
        CommandButton1.Click += new Outlook.OlkCommandButtonEvents_ClickEventHandler(CommandButton1_Click);
    catch (Exception ex)

Returning the Form Region Object to Outlook

Outlook queries the add-in to find objects that implement the Microsoft.Office.Interop.Outlook.FormRegionStartup interface. To return one of these objects to Outlook, override the RequestService method of the ThisAddIn class. If you do not return an object that implements the Microsoft.Office.Interop.Outlook.FormRegionStartup interface in this method, Outlook will not locate the form region.

The following example overrides the RequestService method and returns the form region class to Outlook.

protected override object RequestService(Guid serviceGuid)
    if (serviceGuid == typeof(Microsoft.Office.Interop.Outlook.FormRegionStartup).GUID)
        return new FormRegionHookup();
        return base.RequestService(serviceGuid);

Defining Form Region Properties Using a Form Region Manifest

To define the properties of a form region, create a form region manifest.

A form region manifest is an XML file that contains information that Outlook must have to load the form region.

Use the manifest to define properties such as these:

  • Display titles.

  • Form region type.

  • Display conditions.

  • Localization information.

For a step-by-step guide that shows how to create a form region manifest, see Walkthrough: Creating an Outlook Form Region. For details about the schema, see 2007 Office System: XML Schema Reference.

Associating the Form Region with an Outlook Message Class

An Outlook message class identifies a standard Outlook form. To specify when the form region appears, associate the form region with one or more message classes. For instance, you might want to display a form region when a user opens a mail item in Outlook. To do this, associate that form region with the IPM.Note message class. Create this association by adding entries to the registry. For more information about message classes, see "Item Types and Message Classes" in 2007 Office System: Updated Developer Content.

A quick way to add entries is to put them in a registry file and then run the file. For an example, see Walkthrough: Creating an Outlook Form Region.

The registry modifications must include the following items:

  • A key for each Outlook message class that is associated with one or more form regions.

  • An entry for each form region and an associated value that represents the location of the form region manifest.

The following example shows the contents of a registry file. These entries associate an Outlook message class with a form region.

Windows Registry Editor Version 5.00

You can associate one Outlook message class with several form regions. You can also associate one form region with several Outlook message classes.

You can also create a new custom message class that is based on an existing message class. A new custom message class inherits all the form regions that are associated with the base message class. This also works for end users who create forms by using the form designer in Outlook, if they base the new form on a customized form. Their new forms will inherit the custom form regions that are associated with the base form.

See Also