Walkthrough: Designing an Outlook Form Region


Custom form regions extend standard or custom Microsoft Office Outlook forms. In this walkthrough, you will design a custom form region that appears as a new page in the Inspector window of a contact item. This form region displays a map of each address that is listed for the contact, by sending the address information to the Windows Live Local Search Web site. For information about form regions, see Creating Outlook 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 walkthrough illustrates the following tasks:

  • Creating a new Outlook VSTO Add-in project.

  • Adding a form region to the VSTO Add-in project.

  • Designing the layout of the form region.

  • Customizing the behavior of the form region.

  • Testing the Outlook form region.

System_CAPS_ICON_note.jpg Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Customizing Development Settings in Visual Studio.

You need the following components to complete this walkthrough:

link to video For a video version of this topic, see Video How to: Designing an Outlook Form Region.

First create a basic VSTO Add-in project.

To create a new Outlook VSTO Add-in project

  1. In Visual Studio, create an Outlook VSTO Add-in project with the name MapItAddIn.

  2. In the New Project dialog box, select Create directory for solution.

  3. Save the project to any directory.

    For more information, see How to: Create Office Projects in Visual Studio.

An Outlook VSTO Add-in solution can contain one or more Outlook form region items. Add a form region item to your project by using the New Outlook Form Region wizard.

To add a form region to the Outlook VSTO Add-in project

  1. In Solution Explorer, select the MapItAddIn project.

  2. On the Project menu, click Add New Item.

  3. In the Add New Item dialog box, select Outlook Form Region, name the file MapIt, and then click Add.

    The NewOutlook Form Region wizard starts.

  4. On the Select how you want to create the form region page, click Design a new form region, and then click Next.

  5. On the Select the type of form region you want to create page, click Separate, and then click Next.

    A separate form region adds a new page to an Outlook form. For more information about form region types, see Creating Outlook Form Regions.

  6. On the Supply descriptive text and select your display preferences page, type Map It in the Name box.

    This name appears on the Ribbon of the Inspector window when the contact item is open.

  7. Select Inspectors that are in compose mode and Inspectors that are in read mode, and then click Next.

  8. On the Identify the message classes that will display this form region page, clear Mail Message, select Contact, and then click Finish.

    A MapIt.cs or MapIt.vb file is added to your project.

Develop form regions visually by using the form region designer. You can drag managed controls to the form region designer surface. Use the designer and the Properties window to adjust control layout and appearance.

To design the layout of the form region

  1. In Solution Explorer, expand the MapItAddIn project, and then double-click MapIt.cs or MapIt.vb to open the Form Region Designer.

  2. Right-click the designer, and then click Properties.

  3. In the Properties window, set Size to 664, 469.

    This ensures that the form region will be large enough to display a map.

  4. On the View menu, click Toolbox.

  5. From the Common Controls tab of the Toolbox, add a WebBrowser to the form region.

    The WebBrowser will display a map of each address that is listed for the contact.

Add code to form region event handlers to customize the way a form region behaves at run time. For this form region, the code examines the properties of an Outlook item and determines whether to display the Map It form region. If it displays the form region, the code navigates to Windows Live Local Search and loads a map of each address listed in the Outlook contact item.

To customize the behavior of the form region

  1. In Solution Explorer, right click MapIt.cs or MapIt.vb, and then click View Code.

    MapIt.cs or MapIt.vb opens in the Code Editor.

  2. Expand the Form Region Factory code region.

    The form region factory class named MapItFactory is exposed.

  3. Add the following code to the MapItFactory_FormRegionInitializing event handler. This event handler is called when the user opens a contact item. The following code determines whether the contact item contains an address. If the contact item does not contain an address, this code sets the Cancel property of the FormRegionInitializingEventArgs class to true and the form region is not displayed. Otherwise, the VSTO Add-in raises the FormRegionShowing event and displays the form region.

                private void MapItFactory_FormRegionInitializing(object sender,
                    Microsoft.Office.Tools.Outlook.FormRegionInitializingEventArgs e)
                    Outlook.ContactItem myItem = (Outlook.ContactItem)e.OutlookItem;
                    if (myItem != null)
                        if ((myItem.BusinessAddress != null &&
                                myItem.BusinessAddress.Trim().Length > 0) ||
                            (myItem.HomeAddress != null && 
                                myItem.HomeAddress.Trim().Length > 0) ||
                            (myItem.OtherAddress != null && 
                                myItem.OtherAddress.Trim().Length > 0))
                    e.Cancel = true;

  4. Add the following code to the FormRegionShowing event handler. This code performs the following tasks:

    • Concatenates each address in the contact item and creates a URL string.

    • Calls the Navigate method of the WebBrowser object and passes the URL string as a parameter.

    The Local Search Web site appears in the Map It form region and presents each address in the scratch pad.

            private void MapIt_FormRegionShowing(object sender, EventArgs e)
                string tempLoc = "";
                string defaultAddress = "";
                string scratchPadAddress = "";
                Outlook.ContactItem myItem = (Outlook.ContactItem)this.OutlookItem;
                if (myItem != null)
                    if (myItem.HomeAddress != null && 
                            myItem.HomeAddress.Trim().Length > 0)
                        tempLoc = myItem.HomeAddressStreet.Trim() + " " + 
                            myItem.HomeAddressCity + " " + myItem.HomeAddressState + 
                                " " + myItem.HomeAddressPostalCode;
                        if (myItem.HomeAddress == myItem.MailingAddress)
                            defaultAddress = tempLoc + "_Home";
                            scratchPadAddress += "adr." + tempLoc + "_Home~";
                    if (myItem.BusinessAddress != null && 
                            myItem.BusinessAddress.Trim().Length > 0)
                        tempLoc = myItem.BusinessAddressStreet.Trim() + 
                            " " + myItem.BusinessAddressCity + " " + 
                                myItem.BusinessAddressState + " " + 
                        if (myItem.BusinessAddress == myItem.MailingAddress)
                            defaultAddress = tempLoc + "_Business";
                            scratchPadAddress += "adr." + tempLoc + "_Business~";
                    if (myItem.OtherAddress != null && myItem.OtherAddress.Trim().Length > 0)
                        tempLoc = myItem.OtherAddressStreet.Trim() + " " + 
                            myItem.OtherAddressCity + " " + myItem.OtherAddressState + 
                                " " + myItem.OtherAddressPostalCode;
                        if (myItem.OtherAddress == myItem.MailingAddress)
                            defaultAddress = tempLoc + "_Other";
                            scratchPadAddress += "adr." + tempLoc + "_Other~";
                    + defaultAddress + "&sp=" + scratchPadAddress);

When you run the project, Visual Studio opens Outlook. Open a contact item to view the Map It form region. The Map It form region appears as a page in the form of any contact item that contains an address.

To test the Map It form region

  1. Press F5 to run the project.

    Outlook opens.

  2. In Outlook, on the Home tab, click New Items, and then click Contact.

  3. In the contact form, type Ann Beebe as the contact name, and then specify the following three addresses.

    Address TypeAddress
    Business4567 Main St. Buffalo, NY
    Home1234 North St. Buffalo, NY
    Other3456 Main St. Seattle, WA
  4. Save and close the contact item.

  5. Re-open the Ann Beebe contact item.

  6. In the Show group of the item's Ribbon, click Map It to open the Map It form region.

    The Map It form region appears, and displays the Local Search Web site. The Business, Home, and Other addresses appear in the scratch pad. In the scratch pad, select an address that you want to map.

You can learn more about how to customize the UI of an Outlook application from these topics:

Accessing a Form Region at Run Time
Creating Outlook Form Regions
Guidelines for Creating Outlook Form Regions
Walkthrough: Importing a Form Region That Is Designed in Outlook
How to: Add a Form Region to an Outlook Add-in Project
Associating a Form Region with an Outlook Message Class
Custom Actions in Outlook Form Regions
How to: Prevent Outlook from Displaying a Form Region