Outlook 2019, 2016, 2013, 2010 custom form in VB.NET, C#, C++

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

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Add-in Express components > Advanced Outlook regions

Advanced Outlook regions

Please see the UI mechanics of advanced Outlook regions for the detailed description of how Add-in Express panes work. Below you see the list containing some generic terms mentioned in an absolute must-know and their Outlook-specific equivalents:

• <Manager> - AddinExpress.OL.ADXOlFormsManager, the Outlook Forms Manager
• <Item> - AddinExpress.OL.ADXOlFormsCollectionItem
• <Form> - AddinExpress.OL.ADXOlForm

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.

Further on this page you will find the full details about:

• Context-sensitivity of your Outlook custom forms
• Caching Outlook forms
• Is it Inspector or Explorer?
• WebViewPane
• Outlook form region's instancing
• From an Outlook form instance to the Object Model

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. An example of the folder path is "\\Personal Folders\Inbox".

A special value in FolderName is an asterisk ('*'), which means "all folders". 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 (see Showing / hiding form instances programmatically). 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 (see Advanced Outlook form and view regions) 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, 2010, 2013, 2016, 2019) in order to show your custom form as a home page for a given folder(s).

Unfortunately, due to a bug in Outlook 2002 Add-in Express has to scan all Outlook folders in order to set and restore the WebViewUrl and WebViewOn properties. The first consequence is a delay at startup if the current profile contains thousands of folders. A simple way to prevent the delay is to disable the corresponding item(s) of the Items collection of the Outlook Forms Manager at design time and enable it in the AddinStartupComplete event of the add-in module. Because PublicFolders usually contains many folders, Add-in Express doesn't allow using WebViewPane for PublicFolders and all folders below it. Outbox and Sync Issues and all folders below them are not supported as well 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 startup. 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();
					}
				}
			}

Outlook form region's instancing

The user may open multiple Explorer and Inspector windows. That is, the Outlook Forms Manager will create multiple instances of your form region class now and then. How to retrieve the form instance shown in a particular Outlook window? How to get all form instances?

ADXOlFormsCollectionItem.GetForm()

This method returns an instance of your form region in the specified Outlook window.

ADXOlFormsCollectionItem.GetCurrentForm()

This method returns an instance of your form region in the active Outlook window. Consider the following scenarios:

• Calling GetCurrentForm() in the Click event of a Ribbon button is safe because the event can occur in the active Outlook window only; accordingly, GetCurrentForm() returns the form instance embedded into the Inspector (Explorer) window in which the button is clicked.
• GetCurrentForm() will never find e.g. an Inspector form region if an Explorer window is active;
• Some add-in or antivirus may cause the ExplorerSelectionChange event to fire in an inactive Explorer window; that is, using GetCurrentForm() in an Explorer-related event may produce a wrong result. To avoid this, use GetForm() or make sure that GetCurrentForm() is called in the active window.

ADOlFormsCollectionItem.FormInstances()

This method allows enumerating all instances of your form region created for the specified ADOlFormsCollectionItem. Use the FormInstanceCount property to get the total number of form instances created for this ADOlFormsCollectionItem.

From an Outlook form instance to the Object Model

The Outlook Forms Manager creates an instance of your form when the Outlook context matches the settings of the corresponding ADOlFormsCollectionItem.

After creating the form instance, the manager sets a number of properties providing entry points to the Outlook object model; note that these properties are not set when the form region's constructor is running. The properties are listed below. Note that the state of the COM objects retuned by these properties is essential for Add-in Express functioning – you must not release them in your code because passing any of them to Marshal.ReleaseComObject() may cause Outlook to crash.