Create Outlook form regions

Applies to: Visual Studio Visual Studio for Mac

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

• Add an Outlook form region to your project

• Use the form region designer

• Use a form region designed in Outlook

• Add custom code to a form region

• Build the project

• Debug a form region

• Deploy 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 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.

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.

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.

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.

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