This documentation is archived and is not being maintained.

Walkthrough: Designing an Outlook Form Region

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

  • Application-level projects

Microsoft Office version

  • Outlook 2007

For more information, see Features Available by Application and Project Type.

Custom form regions extend standard or custom Microsoft Office Outlook 2007 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.

This walkthrough illustrates the following tasks:

  • Creating a new Outlook add-in project.

  • Adding a form region to the add-in project.

  • Designing the layout of the form region.

  • Customizing the behavior of the form region.

  • Testing the Outlook form region.


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 Visual Studio Settings.

You need the following components to complete this walkthrough:

  • Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

  • Microsoft Office Outlook 2007.

  • A connection to the Internet to use the Local Search service.

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

First create a basic add-in project.

To create a new Outlook add-in project

  1. In Visual Studio, create an Outlook 2007 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 Visual Studio Tools for Office Projects.

An Outlook 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 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 New Outlook 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 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 Tools for Office runs the add-in and 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 File menu, point to New, and then click Contact.

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

    Address Type



    4567 Main St. Buffalo, NY


    1234 North St. Buffalo, NY


    3456 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: