Create Outlook custom form in VB.NET, C#, C++.
Develop custom task panes for Outlook 2007 - 2000.

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home > Add-in Express .NET > Online Guide > Developing custom Outlook forms

Outlook custom forms

Outlook customization has a long-dated history. To create an Outlook custom form, also referred to as custon task pane, you can use the built-in tools for form designing and publishing (see the Tools | Forms | Design a Form menu in Outlook). You can use HTML and VBScript / JScript to customize folder views, and Outlook Today is an example of this approach.

Advanced Outlook form regions

For Add-in Express, Outlook has always been a featured application. In this view, Add-in Express provides Outlook developers with Advanced Outlook Form Regions for customizing Outlook bar, To-Do bar and Navigation pane as well as special features for Outlook plug-in development. Now you can embed custom .NET forms into the Outlook Explorer and Outlook Inspector windows and replace folder views with custom .NET forms in Outlook Today style. Also, you can replace the Outlook Today page with your custom form.

The form-embedding technology of Add-in Express consists of three key parts:

ADXOlForm (or the form) – this is the base class for all forms embeddable into Outlook windows
ADXOlFormsManager (Outlook Forms Manager) – this component provides the Items collection and a number of events
Item – every item of the ADXOlFormsManager.Items collection specifies context and visualization properties for a form

You add a custom Outlook task pane to your project by choosing a corresponding item in the Add New Item dialog. Then, using the context menu of the add-in module, you add an Outlook Forms Manager to the add-in module. Finally, you add an item to the Items collection of the manager, bind the item to the form using the item's FormClass property, and specify items properties such as ExplorerLayout and InspectorLayout that specify the placement of your Outlook custom form in explorer and inspector windows. Also, you can specify Outlook folders and / or item types for which your custom form will be shown.

Context-sensitivity of your Outlook custom forms

Whenever the Outlook Forms Manager detects a context change in Outlook, it searches the ADXOlFormsCollection collection for enabled items that match the current context and shows or creates the corresponding instances.

ADXOlFormsCollectionItem provides a number of properties that allow specifying the context settings for your custom Outlook form. Say, you can specify item types for which your form will be shown. Note that in case of explorer, the items types that you specify are compared with the default item type of the current folder. In addition, you can specify the names of the folders for which your form will be shown in the FolderName and FolderNames properties; these properties also work for Inspector windows – in this case the parent folder of the Outlook item is checked. A special value in FolderName is an asterisk ('*'), which means "all folders". See also COM add-ins for Outlook – template characters in FolderName. Also you can specify message class(es) for which your custom form will be shown. Note that all of the properties of an ADXOlFormsCollectionItem are treated using the OR boolean operation.

In advanced scenarios you can also use the ADXOlFormsCollectionItem.ADXBeforeFormInstanceCreate event and ADXOlForm.ADXBeforeFormShow events in order to prevent your custom Outlook form from being shown. In addition, you can use events provided by ADXOlForm in order to check the current context. Say, you can use the ADXBeforeFolderSwitch or ADXSelectionChange events of ADXOlForm.

Caching Outlook forms

By default, whenever Add-in Express needs to show a form, it creates a new instance of that form. You can change this behavior by choosing an appropriate value of the ADXOlFormsCollectionItem.Cached property. The values of this property are:

NewInstanceForEachFolder – it shows the same form instance whenever the user navigates to the same Outlook folder.
OneInstanceForAllFolders – it shows the same form instance for all Outlook folders.
None – no form caching is used.

Note that caching works within the same Explorer window; when the user opens another Explorer window, Add-in Express creates another set of cached forms. Also note that forms shown in Inspector windows cannot be cached.

Is it Inspector or Explorer?

Check the InspectorObj and ExplorerObj properties of ADXOlForm. These properties return COM objects that will be released when your form is removed from its region. And this may occur one or more times during the life-time of a given instance of your form because Add-in Express may remove your form from a given region and then embed the form to the same region in order to comply with Outlook windowing.

WebViewPane

When this value is chosen in the ExplorerLayout property of ADXOlFormsCollectionItem, Add-in Express uses the WebViewUrl and WebViewOn properties of Outlook.MAPIFolder (also Outlook.Folder in Outlook 2007) in order to show your custom form as a home page for a given folder(s).

Unfortunately, due to a bug in Outlook 2002 and due to the necessity of providing a consistently-working code, Add-in Express has to scan all folders in Outlook in order to set and restore the WebViewUrl and WebViewOn properties. The first consequence is a delay at startup. The delay me be big enough if the user has a large number of folders in the store. The necessity to minimize the delay makes us exclude PublicFolders and all folders below it from the list; that is, Add-in Express doesn't allow using WebViewPane for PublicFolders and all folders below it.

Also, Outbox and Sync Issues and all folders below these folders aren't supported when using WebViewPane. Because of the need to scan Outlook folders, WebViewPane produces another delay when the user works in the Cached Exchange Mode (see the properties of the Exchange account in Outlook) and the Internet connection is slow or broken. To bypass this problem Add-in Express allows reading EntryIDs of those folders from the registry. Naturally, you are supposed to write appropriate values to the registry at add-in start-up. Here is the code to be used in the add-in module:

internal void SaveDefaultFoldersEntryIDToRegistry(string PublicFoldersEntryID,
    string PublicFoldersAllPublicFoldersEntryID,
    string FolderSyncIssuesEntryID)
{
    RegistryKey ModuleKey = null;
    RegistryKey ADXXOLKey = null;
    RegistryKey WebViewPaneSpecialFoldersKey = null;
    try
    {
        ModuleKey = Registry.CurrentUser.OpenSubKey(this.RegistryKey, true);
        if (ModuleKey != null)
        {
            ADXXOLKey = ModuleKey.CreateSubKey("ADXXOL");
            if (ADXXOLKey != null)
            {
                WebViewPaneSpecialFoldersKey =
                    ADXXOLKey.CreateSubKey
                    ("FoldersForExcludingFromUseWebViewPaneLayout");
                if (WebViewPaneSpecialFoldersKey != null)
                {
                    if (PublicFoldersEntryID.Length >= 0)
                    {
                        WebViewPaneSpecialFoldersKey.
                            SetValue("PublicFolders",
                            PublicFoldersEntryID);
                    }
                    if (PublicFoldersAllPublicFoldersEntryID.Length >= 0)
                    {
                        WebViewPaneSpecialFoldersKey.
                            SetValue("PublicFoldersAllPublicFolders",
                            PublicFoldersAllPublicFoldersEntryID);
                    }
                    if (FolderSyncIssuesEntryID.Length >= 0)
                    {
                        WebViewPaneSpecialFoldersKey.
                            SetValue("FolderSyncIssues",
                            FolderSyncIssuesEntryID);
                    }
                }
            }
        }
    }
    finally
    {
        if (ModuleKey != null)
        {
            ModuleKey.Close();
        }
        if (WebViewPaneSpecialFoldersKey != null)
        {
            WebViewPaneSpecialFoldersKey.Close();
        }
        if (ADXXOLKey != null)
        {
            ADXXOLKey.Close();
        }
    }
}

The sample below is written in VB.NET, but you can develop your forms in Visual C#, C++ and Delphi Prism.

Creating Outlook custom forms

To create a custom Outlook form, please follow the first three steps described in sample Outlook COM add-in project first. After that 6 more easy steps, and your custom form is embedded into Outlook.

1. Add the Outlook Forms Manager

Use the corresponding command in the context menu of the add-in module in order to add the Outlook Forms Manager to the module.

2. Add a custom form embeddable into Outlook

To add a custom form to your Outlook add-in project, choose the corresponding wizard in the Add New Item Dialog.

3. Customize your Outlook form

On your Outlook custom form, you can use any .NET controls such as calendars, edit boxes, grids, list views, etc. In this example, we added a label to show when the selected message was sent.

Custom form

4. Access Outlook objects

ADXOlForm provides access to all Outlook objects and events. For example, you can handle the ADXSelectionChange event to synchronize your form with selection changes in the current Explorer window:


 Private Sub ADXOlForm1_ADXSelectionChange() _
      Handles MyBase.ADXSelectionChange
      Dim OlApp As Outlook._Application = CType(OutlookAppObj, _
         Outlook._Application)
      Dim Explorer As Outlook._Explorer = OlApp.ActiveExplorer()
      Dim Selection As Outlook.Selection = Explorer.Selection
      Dim Item As Outlook.MailItem

      If Selection.Count <> 0 Then
         Item = CType(Selection.Item(1), Outlook.MailItem)
         SentLabel.Text = "Sent: " + Item.SentOn
         Marshal.ReleaseComObject(Item)
      End If
      Marshal.ReleaseComObject(Selection)
      Marshal.ReleaseComObject(Explorer)
   End Sub

You can also handle the ADXBeforeFormShow event to initialize your form for the current inspector window:


   Private Sub ADXOlForm1_ADXBeforeFormShow() Handles Me.ADXBeforeFormShow
      'If the form is shown in Explorer then exit.
      If Me.InspectorObj Is Nothing Then Exit Sub
      Dim Inspector As Outlook.Inspector = CType(InspectorObj, _
         Outlook.Inspector)
      Dim Item As Outlook.MailItem = CType(Inspector.CurrentItem, _
         Outlook.MailItem)
      SentLabel.Text = Item.Subject
      Marshal.ReleaseComObject(Item)
   End Sub

5. Specify context for your custom Outlook form

Add a new item to the Items collection of the Outlook Forms Manager, select your form class in the FormClassName property, and specify Outlook context as follows:

Binding form to Outlook context

If the form is to be shown in the Explorer window, use the ExplorerItemTypes, ExplorerLayout, ExplorerMessageClass(es), and FolderName(s) properties.
If the form is to be shown in the Inspector window, use InspectorItemTypes and InspectorMessageClass(es), and FolderName(s) properties.

Note. When several context-sensitivity related properties are set simultaneously, the Add-in Express Extensions for Outlook handles them using the OR Boolean operator.