Creating Outlook Form Regions

You can use form regions to customize Microsoft Office Outlook forms. Visual Studio provides advanced tools that make it easier for you to design, develop, and debug form regions.

Applies to: The information in this topic applies to application-level projects for Outlook 2013 and Outlook 2010. For more information, see Features Available by Office Application and Project Type.

This topic provides the following information:

• Advantages of Using Form Regions

• Adding an Outlook Form Region to Your Project

• Using the Form Region Designer

• Using a Form Region Designed in Outlook

• Adding Custom Code to a Form Region

• Building the Project

• Debugging a Form Region

• Deploying a Form Region

Advantages of Using Form Regions

Form regions offer many enhancements over traditional Outlook forms development:

• Customize the default page of any standard form.

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

• Replace or enhance any standard form.

• Display custom UI in the Reading Pane and in Inspectors.

For more information, see Customizing Form Pages and Form Regions.

Adding an Outlook Form Region to Your Project

You can use the New Outlook Form Region wizard to design a new form region or import a form region that was designed in Outlook. Also, if you have a form region that you used in another Outlook add-in project, you can reuse your existing form region.

Creating a New Form Region by Using the Wizard

To create a form region, add an Outlook Form Region item to an Outlook add-in project. This starts the New Outlook Form Region wizard.

Use the wizard to indicate whether you want to design a new form region or import a form region that was designed in Outlook. For more information about designing a new form region, see Using the Form Region Designer. For more information about using a form region designed in Outlook, see Importing a Form Region Designed in Outlook.

Use the wizard to specify the type of form region you want to create. The following table describes each form region type.

Region type	Description
Separate	Adds the form region as a new page in an Outlook form.
Adjoining	Appends the form region to the bottom of an Outlook form's default page.
Replacement	Adds the form region as a new page that replaces the default page of an Outlook form.
Replace-all	Replaces the whole Outlook form with the form region.

You can also use the wizard to specify display conditions and to select the type of form to extend. For more information, see How to: Add a Form Region to an Outlook Add-in Project.

The selections that you make in the wizard affect the options that are available in other wizard pages. For example, if you select Adjoining or Separate in the Create a New Outlook Form Region page, then the Title and Description fields are unavailable in the Supply descriptive text and select your display preferences page. This is because Outlook does not use these fields when it displays an adjoining or separate form region.

Form Region Files

When you complete the New Outlook Form Region wizard, Visual Studio automatically adds the following files to your project:

• A form region code file. This file has the name that you specify for the Outlook Form Region item in the Add New Item dialog box. Add code to handle form region events to this file.

• A form region designer code file. This file contains code generated by the form region designer and should not be directly edited.

• An Outlook Form Storage (.ofs) file.

  Note

  This file is only added to the project if you import a form region that was designed in Outlook.

Form Region Factory Class

The form region code file contains a partial class that implements the IFormRegionFactory interface. This is the form region factory class. The form region factory class is responsible for creating new instances of the form region.

You can find this class by expanding the Form Region Factory region.

The New Outlook Form Region wizard adds attributes to this class that specify the internal name of the form region and the message classes that display the form region. You can modify these attributes manually after the file has been added to the project.

Most of the form region factory class is implemented in the form region designer file. However, the FormRegionInitializing event handler is exposed in the form region code file. You can use this event handler to specify whether Outlook should display the form region. For more information, see Handling Form Region Events.

Adding an Existing Form Region to Your Project

If you have an Outlook form region that you used in another Outlook project, you can reuse it in your current Outlook add-in project by using the Add Existing Item dialog box.

The existing form region must have a code file (.vb or .cs); you cannot add Outlook Form Storage (.ofs) files by using the Add Existing Item dialog box. However, you can create a new form region by importing an Outlook Form Storage file. For more information, see How to: Add a Form Region to an Outlook Add-in Project.

Using the Form Region Designer

The form region designer helps you to design the layout and appearance of a form region. You can drag managed controls to the surface of the designer, double-click controls to open event handlers, and set properties in the Properties window.

Note

You can find properties that affect the way the form region appears in Outlook beneath the Manifest node in the Properties window.

The form region designer is available only if you select Design a New Form Region in the Select how you want to create the form region page of the New Outlook Form Region wizard.

There are three ways to open the form region designer:

• In Solution Explorer, double-click the form region code file.

• In Solution Explorer, right-click the form region code file, and then click View Designer.

• In Solution Explorer, select the form region code file, and then, on the View menu, click Designer.

The form region designer supports only managed controls. You cannot add native Outlook controls.

Importing a Form Region Designed in Outlook

When you design in Outlook, you can add native Outlook controls to the form region. Native Outlook controls enable you to bind to Outlook data at design time. However, you cannot then use the form region designer to add managed controls or change the design of the form region.

You can import form regions into an Outlook add-in project by using the New Outlook Form Region wizard. On the Select how you want to create the form region page, select Import an Outlook Form Storage (.ofs) file. You can then browse to the location of an Outlook Form Storage file (.ofs) file. (Outlook saves form regions as .ofs files.)

The New Outlook Form Region wizard copies the .ofs file to the project directory and adds control references to the form region designer file. You can then handle control events in the form region code file.

To handle events in a Visual Basic project, select an event from the method name list at the top of the Code Editor.

To handle events in a C# project, subscribe to control events in the FormRegionShowing method. For more information, see How to: Subscribe to and Unsubscribe from Events (C# Programming Guide).

You can change form region properties in the InitializeManifest method of the form region factory class.

Note

To import a form region, you must be working in a project that targets the same version of Outlook that you have installed on the development computer. For example, if you have Outlook 2010 installed, importing a form region will only work in a project was created by using the Outlook 2010 Add-in project template.

Updating an Imported Form Region's Design

You can add, remove, or change controls on the form region. Before you do this, back up any code that you added to the form region code file. Then, open the .ofs file in Outlook, modify the form region, and then save the changes. Use the New Outlook Form Region wizard to import the modified .ofs file. You can then paste your code into the new form region code file.

Adding Custom Code to a Form Region

The Microsoft.Office.Tools.Outlook namespace gives you access to classes that represent the form region, the Outlook item that displays the form region, and other useful items. The Outlook Form Region item automatically adds a reference to this assembly in the project and inserts the appropriate using or Imports statement at the top of the form region code file.

You can use classes, methods, and properties in the Microsoft.Office.Interop.Outlook namespace to accomplish most of your Outlook programming tasks. For more information about the Outlook object model, see Outlook Object Model Overview. For examples of typical tasks that make use of the Outlook object model, see Outlook Solutions.

Handling Form Region Events

The Outlook Form Region item automatically adds the following three event handlers to the form region code file.

Event	Description
FormRegionInitializing	Occurs before the form region is initialized. You can check conditions in this event handler to determine whether Outlook should display the form region. For more information, see How to: Prevent Outlook from Displaying a Form Region.
FormRegionShowing	Occurs after an instance of the form region is created but before the form region appears.
FormRegionClosed	Occurs before the form region is closed.

Building the Project

When you build an Outlook add-in project that contains a form region, Visual Studio adds the following information to the registry:

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

• An entry for each form region and an associated value that represents the name of the Outlook add-in.

Outlook uses this information to load the form regions.

Debugging a Form Region

You can debug an Outlook add-in that contains a form region just as you would debug other Visual Studio projects. When you start the Visual Studio debugger, Visual Studio automatically starts Outlook.

To view the form region, you must open the appropriate Outlook item. For example, if an adjoining form region is appended to the bottom of a mail item, open a mail item.

Deploying a Form Region

Form regions are deployed automatically with the associated Outlook add-in. Therefore, you do not have to perform any special tasks to deploy a form region. For more information about deploying add-ins, see Deploying Office Solutions.

Related Topics

Title	Description
Guidelines for Creating Outlook Form Regions	Provides information that can help you optimize your form regions and avoid potential problems.
How to: Add a Form Region to an Outlook Add-in Project	Shows you how to create a form region to extend a standard or custom Microsoft Office Outlook form by using the New Outlook Form Region wizard.
Associating a Form Region with an Outlook Message Class	Explains how to specify which Microsoft Office Outlook items display a form region by associating the form region with the message class of each item.
Walkthrough: Designing an Outlook Form Region	Shows how to design a custom form region that appears as a new page in the Inspector window of a contact item.
Walkthrough: Importing a Form Region That Is Designed in Outlook	Shows how to design a form region in Microsoft Office Outlook, and then import the form region into an Outlook add-in project by using the New Outlook Form Region wizard.
Accessing a Form Region at Run Time	Describes how to write code to show, hide, or modify controls on a form region, and enable users to run the code from other areas in your project by using the Globals class.
How to: Prevent Outlook from Displaying a Form Region	Shows how to prevent Microsoft Office Outlook from displaying a form region for a particular item.
Shows how to access the Outlook item in which a form region appears.
Custom Actions in Outlook Form Regions	Describes how to enable users to respond to an Outlook item.