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.
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.
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.
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.
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.
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.
Create a VSTO add-in for the Microsoft Office Outlook with features that are available to the application itself, regardless of which Outlook items are open.
Interact with various objects provided by the Outlook object model to develop VSTO add-ins for Microsoft Outlook, such as for mail, appointments, and tasks.