Exposing Custom Data in Outlook 2007 with Visual Studio 2008

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary: Learn how to expose application data in Microsoft Office Outlook 2007 by using a replace-all form region that you create in Visual Studio 2008. Includes tips about how to further integrate that data in the Outlook user interface.

Office Visual How To

Applies to: 2007 Microsoft Office system, Microsoft Office Outlook 2007, Microsoft Visual Studio 2008

Steve Hansen, VSTOTips.com

March 2009

Overview

As a key communications and organizational application, Office Outlook 2007 is an indispensible tool to information workers. Because those workers spend so much time in Outlook, developers often look for ways to build applications that help those workers to organize or to communicate in new ways.

This how-to article explains how to display custom application data in Outlook by using form regions that you design in Visual Studio 2008. The scenario in the article envisions a Web application that packages team-registration information from a tournament Web site, and then sends that information in an e-mail to the tournament director.

 See It Exposing Application Data in Outlook 2007

Watch the Video

Length: 19:05 | Size: 39.60 MB | Type: WMV file

Code It | Read It | Explore It

Code It

When you expose custom data in Outlook, you typically perform a few common tasks. For example, you might create one or more folders to organize data, or customize the shortcut menu associated with a folder or an Outlook item. In addition, you must write code to retrieve or parse the data that you want to display, and update the controls on the user interface component where you display that data.

Creating an Outlook Folder

When you create a folder, it is useful to create one that is specific to the type of data that you want to display. For example, in the accompanying video, the narrator creates a folder named “Tournament Registrations” to store registrations by using the following code.

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    Outlook.Folder folder = CreateFolder(
        this.Application.Session.GetDefaultFolder(
            Outlook.OlDefaultFolders.olFolderInbox), 
        "Tournament Registrations", 
        Outlook.OlDefaultFolders.olFolderInbox, "");
}
private Outlook.Folder CreateFolder( Outlook.Folder root, 
string folderName, Outlook.OlDefaultFolders folderType, 
string webURL)
{
    Outlook.Folder folder = GetFolder(root, folderName);

    if (folder == null)
    {
        folder = (Outlook.Folder)root.
                    Folders.Add(folderName, folderType);
    }

    // Add a URL and turn on Web view as a home page for the folder.
    if (folder != null)
    {
        if (webURL.Length > 0)
        {
            folder.WebViewURL = webURL;
            folder.WebViewOn = true;
            folder.WebViewAllowNavigation = true;
        }
    }

    return folder;
}

private Outlook.Folder GetFolder(Outlook.Folder root, 
string folderName)
{
    if (root != null)
    {
        foreach (Outlook.Folder f in root.Folders)
        {
            if (f.Name == folderName)
                return f;
        }
    }
    return null;
}

Private Sub ThisAddIn_Startup( _
ByVal sender As Object, ByVal e As System.EventArgs) _
Handles Me.Startup

    ' Create a folder to store the registration e-mail messages.
    Dim fldr As Outlook.Folder
    fldr = CreateFolder( _
        Me.Application.Session.GetDefaultFolder _
        (Outlook.OlDefaultFolders.olFolderInbox), _
        "Tournament Registrations", _
        Outlook.OlDefaultFolders.olFolderInbox)
End Sub

Private Function CreateFolder(ByVal parent As Outlook.Folder, _
ByVal sName As String, _
ByVal folderType As Outlook.OlDefaultFolders, _
) As Outlook.Folder

    ' See whether the folder already exists.
    Dim folder As Outlook.Folder = GetFolder(parent, sName)

    ' If the folder does not exist, add it.
    If folder Is Nothing Then
        folder = parent.Folders.Add(sName, folderType)
    End If

    ' Return the folder.
    Return folder

End Function

Private Function GetFolder(ByVal parent As Outlook.Folder, _
ByVal sFolderName As String) As Outlook.Folder

    Dim f As Outlook.Folder

    If Not parent Is Nothing Then
        For Each f In parent.Folders
            If f.Name = sFolderName Then
                Return f
            End If
        Next
    End If

    Return Nothing

End Function

Customizing the Shortcut Menu Associated with a Folder Item

By customizing the shortcut menu that is associated with a folder, you can extend its functionality. To customize a folder's shortcut menu, you add code to the FolderContextMenuDisplay event handler. The following example uses a class-level variable named button to store a reference to a command-bar button. Menu items on the shortcut menu are command-bar button objects.

void Application_FolderContextMenuDisplay(Office.CommandBar CommandBar, 
Outlook.MAPIFolder Folder)
{
    if (button != null)
    {
        if (Folder.Name == "Tournament Registrations")
        {
            button = CommandBar.Controls.Add(
                Office.MsoControlType.msoControlButton);
            button.Caption = "Consolidate Registrations";
            button.Visible = true;
            button.Click += new Office
                .Core._CommandBarButtonEvents_ClickEventHandler(
                button_Click);
        }
    }
}

void button_Click(
Office.CommandBarButton Ctrl, ref bool CancelDefault)
{
    System.Windows.Forms.MessageBox("Context item clicked...");
}

Private Sub Application_FolderContextMenuDisplay( _
ByVal CommandBar As Microsoft.Office.Core.CommandBar, _
ByVal Folder As Microsoft.Office.Interop.Outlook.MAPIFolder) _
Handles Application.FolderContextMenuDisplay

    If Folder.Name = "Tournament Registrations" Then
        ' Do something to display a shortcut menu.
        button = CommandBar.Controls.Add( _
            Office.MsoControlType.msoControlButton)
        button.Caption = "Consolidate Registrations"
        button.Visible = True
        AddHandler button.Click, AddressOf Button_Click
    End If

End Sub

Public Sub Button_Click( _
ByVal button As Office.CommandBarButton, _
ByRef Cancel As Boolean)

    System.Windows.Forms.MessageBox.Show("Context item clicked..")

End Sub

Disassociating Event Handlers

When you customize a shortcut menu, you must disassociate any event handlers that you added in the FolderContextMenuDisplay event handler by adding the following code to the ContextMenuClose event handler.

void Application_ContextMenuClose(Outlook.OlContextMenu ContextMenu)
{
    if (button != null)
    {
        button.Click -= new Office
            ._CommandBarButtonEvents_ClickEventHandler(button_Click);
    }
    button = null;
}

Private Sub Application_ContextMenuClose( _
ByVal ContextMenu As Microsoft.Office.Interop.Outlook.OlContextMenu) _
Handles Application.ContextMenuClose

    If button IsNot Nothing Then
        RemoveHandler button.Click, AddressOf Button_Click
    End If
    button = Nothing

End Sub

Read It

Outlook 2007 is a natural place to display information. It is often a user's primary application, and it gives the developer several different ways to customize the user interface, including ways to integrate custom data within Outlook. For example, programmers can integrate data from applications external to Outlook, or integrate nonstandard data within Outlook, such as custom message classes.

Form Regions as a User Interface for Custom Data

One possible way to expose custom data in the Outlook user interface is to use form regions. In the video, a replace-all form region is a particularly good fit. The key to using the replacement or replace-all form regions is that they can only be used on custom or derived message classes. For example, standard mail items belong to the message class IPM.Note.

The video uses a derived message class called IPM.Note.Registration. Thus, it is possible to use a replace-all form region to display data for each item. To register for a tournament, a team manager enters the required data into a Web form, and then submits it. Then, the application packages the data as XML and sends it to the tournament director in the body of an e-mail of type IPM.Note.Registration.

Outlook does not display the data as straight XML data. Instead, it calls a procedure inside the FormRegionShowing event handler that parses the XML and updates the controls on a form region to display the data in a way that makes immediate sense to the reader.

Using Folders to Organize Custom Data

People typically use folders to organize data that is associated with a given task or process. It is easy to create folders using the object model in Outlook. One advantage to storing all of a particular kind of data to a specific folder is that you can use the shortcut menus on the folder itself in addition to the shortcut menus on the individual items. Then, you can add contextual user interface hooks into functionality that applies to all of an application's data. For example, if you had to print a program for a tournament that listed the rosters of all of the teams, you could take advantage of automation in Outlook by using the object model in Microsoft Office Word to create and manipulate a document based on a Word template. Then, you could loop through the items in the folder and export each team's roster to the Word template.

The Importance of Command Bars in Outlook

Most of the applications in the 2007 Office release use the Microsoft Office Fluent user-interface Ribbon as the primary user interface to an application's functionality. In Outlook 2007, the user interface uses both the Ribbon and command bars (toolbars). Outlook Inspector windows use the Ribbon (for example, the window that opens when you open a standard message). Outlook Explorer windows use the command-bar interface (for example, the window that opens when you first open Outlook).

Shortcut menus are based on command bars. When you write code for Outlook and want to provide convenient access to your new features, use shortcut menus on the folders and the Outlook items that are specific to your application. That is, add command-bar buttons to the shortcut menu that appears when a user right-clicks a folder or an item that is associated with your custom feature. To do this, use the following events from the Outlook object model:

Explore It