Walkthrough: Design an Outlook form region

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

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 Create 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.

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 Personalize the Visual Studio IDE.

Prerequisites

You need the following components to complete this walkthrough:

• An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configure a computer to develop Office solutions.

• Outlook 2010 or newer.

  For a video version of this topic, see Video how to: Design an Outlook form region.

Create a new Outlook VSTO Add-in project

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.

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

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 Create 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.

Design the layout of the form region

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.

Customize the behavior of the form region

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))
           {
               return;
           }
       }
   
       e.Cancel = true;
   }
   

   Private Sub MapItFactory_FormRegionInitializing(ByVal sender As Object, ByVal e As Microsoft.Office.Tools.Outlook.FormRegionInitializingEventArgs) Handles Me.FormRegionInitializing
   
       Dim myItem As Outlook.ContactItem = CType(e.OutlookItem, Outlook.ContactItem)
   
       If Not (myItem Is Nothing) Then
           If Not (myItem.BusinessAddress Is Nothing) AndAlso myItem.BusinessAddress.Trim().Length > 0 Or (Not (myItem.HomeAddress Is Nothing) AndAlso myItem.HomeAddress.Trim().Length > 0) Or (Not (myItem.OtherAddress Is Nothing) AndAlso myItem.OtherAddress.Trim().Length > 0) Then
               Return
           End If
       End If
   
       e.Cancel = True
   
   End Sub
   

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";
                 }
                 else
                 {
                     scratchPadAddress += "adr." + tempLoc + "_Home~";
                 }
             }
             if (myItem.BusinessAddress != null && 
                     myItem.BusinessAddress.Trim().Length > 0)
             {
                 tempLoc = myItem.BusinessAddressStreet.Trim() + 
                     " " + myItem.BusinessAddressCity + " " + 
                         myItem.BusinessAddressState + " " + 
                             myItem.BusinessAddressPostalCode;
                 if (myItem.BusinessAddress == myItem.MailingAddress)
                 {
                     defaultAddress = tempLoc + "_Business";
                 }
                 else
                 {
                     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";
                 }
                 else
                 {
                     scratchPadAddress += "adr." + tempLoc + "_Other~";
                 }
             }
         }
     
         webBrowser1.Navigate("http://local.live.com/default.aspx?style=r&where1=" 
             + defaultAddress + "&sp=" + scratchPadAddress);
     
     }
     

     Private Sub MapIt_FormRegionShowing(ByVal sender As System.Object, _
         ByVal e As System.EventArgs) Handles MyBase.FormRegionShowing
         Dim tempLoc As String = ""
         Dim defaultAddress As String = ""
         Dim scratchPadAddress As String = ""
     
         Dim myItem As Outlook.ContactItem = _
             CType(Me.OutlookItem, Outlook.ContactItem)
     
         If Not (myItem Is Nothing) Then
             If Not (myItem.HomeAddress Is Nothing) And _
                 myItem.HomeAddress.Trim().Length > 0 Then
                 tempLoc = myItem.HomeAddressStreet.Trim() + " " _
                     + myItem.HomeAddressCity + " " + myItem.HomeAddressState + _
                         " " + myItem.HomeAddressPostalCode
                 If myItem.HomeAddress = myItem.MailingAddress Then
                     defaultAddress = tempLoc + "_Home"
                 Else
                     scratchPadAddress += "adr." + tempLoc + "_Home~"
                 End If
             End If
             If Not (myItem.BusinessAddress Is Nothing) And _
                 myItem.BusinessAddress.Trim().Length > 0 Then
                 tempLoc = myItem.BusinessAddressStreet.Trim() + " " _
                     + myItem.BusinessAddressCity + " " + _
                         myItem.BusinessAddressState + " " + _
                             myItem.BusinessAddressPostalCode
                 If myItem.BusinessAddress = myItem.MailingAddress Then
                     defaultAddress = tempLoc + "_Business"
                 Else
                     scratchPadAddress += "adr." + tempLoc + "_Business~"
                 End If
             End If
             If Not (myItem.OtherAddress Is Nothing) And _
                 myItem.OtherAddress.Trim().Length > 0 Then
                 tempLoc = myItem.OtherAddressStreet.Trim() + " " + _
                     myItem.OtherAddressCity + " " + myItem.OtherAddressState + _
                         " " + myItem.OtherAddressPostalCode
                 If myItem.OtherAddress = myItem.MailingAddress Then
                     defaultAddress = tempLoc + "_Other"
                 Else
                     scratchPadAddress += "adr." + tempLoc + "_Other~"
                 End If
             End If
         End If
     
         WebBrowser1.Navigate(("http://local.live.com/default.aspx?style=r&where1=" _
             + defaultAddress + "&sp=" + scratchPadAddress))
     
     End Sub
     

Test the Outlook form region

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 Type	Address
   Business	4567 Main St. Buffalo, NY
   Home	1234 North St. Buffalo, NY
   Other	3456 Main St. Seattle, WA

4. Save and close the contact item.

5. Reopen the Ann Beebe contact item.

   In Outlook, this can be done in the Find group by either opening the Address Book for Contacts or typing Ann Beebe into Search People.

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.

Next steps

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

• To learn about how to customize the ribbon of an Outlook item, see Customize a ribbon for Outlook.

See also

• Access a form region at run time
• Create Outlook form regions
• Guidelines to create Outlook form regions
• Walkthrough: Import a form region that is designed in Outlook
• How to: Add a form region to an Outlook Add-in project
• Associate a form region with an Outlook message class
• Custom actions in Outlook form regions
• How to: Prevent Outlook from displaying a form region