Create Outlook form regions
Applies to: 
Visual Studio 
Visual Studio for Mac
Note
This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
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 VSTO Add-in projects for Outlook. For more information, see Features available by Office application and project type.
This topic provides the following information:
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 Customize form pages and form regions.
Add 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 VSTO Add-in project, you can reuse your existing form region.
Create a new form region by using the wizard
To create a form region, add an Outlook Form Region item to an Outlook VSTO 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 Use the form region designer. For more information about using a form region designed in Outlook, see Import 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 Handle form region events.
Add 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 VSTO 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.
Use 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.
Import 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 VSTO 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.
Update 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.
Add 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.
Handle 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. |
Build the project
When you build an Outlook VSTO 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 VSTO Add-in.
Outlook uses this information to load the form regions.
Debug a form region
You can debug an Outlook VSTO 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.
Deploy a form region
Form regions are deployed automatically with the associated Outlook VSTO Add-in. Therefore, you do not have to perform any special tasks to deploy a form region. For more information about deploying VSTO Add-ins, see Deploy an Office solution.
Related topics
| Title | Description |
|---|---|
| Guidelines for create 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. |
| Associate 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: Design 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: Import 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 VSTO Add-in project by using the New Outlook Form Region wizard. |
| Access 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. |