How to create advanced view and form regions with Add-in Express Regions for Microsoft Outlook and VSTO

In this post I’ll introduce you to the new Add-in Express Regions for Microsoft Outlook and Visual Studio Tools for Office. To get started, create a new Outlook 2010 Add-in project in Visual Studio 2010.

After you’ve typed a suitable name for you project, click on the OK button. The standard Outlook Add-in boiler plate code will be created for you. Next, add a new ADX Region for Outlook and VSTO item to your project by selecting Add New Item… from the Visual Studio Project menu.

Click the Add Button and the New Region Wizard will start. Select FolderView.Top in the Explorer Layout dropdown list. You’ll notice that as you select different Explorer Layouts the wizard updates to show a preview of how the layout will look like in Microsoft Outlook.

The following Explorer region options are available for Outlook 2003, 2007 and 2010:

• FolderView, Left, Right, Top, Bottom
  If you need to provide your users with an alternate view for a folder the FolderView region is what you are looking for. This view will only show in folders that contain items of the type you specified when first adding it to your project or the specific folder names. You have five layout options for this region, Left, Right, Top and Bottom will dock the region to the position you specified within the folder. FolderView will replace the entire folder view with your custom region.
• ReadingPane, Left, Right, Top, Bottom
  The reading pane region works in a similar fashion as the folderview region whereas you can choose to add your custom region to either the left, right, top or bottom of the Outlook reading pane or completely replace it. Your reading pane region will however only be visible if the user has enabled the Outlook reading pane for the folders or folder containing the item types you specified.
• NavigationPane Bottom
  Setting your custom region’s Explorer Layout to Navigationpane.Bottom will dock your region below the Outlook navigation pane or Outlook Bar. This is a useful workaround to add your own functionality to the Outlook navigation pane.
• WebViewPane
  WebviewPane is one of my favourite layouts. If you need to replace an entire folder view e.g. replace the Outlook Today view with your own sales dashboard this is the region layout to use. As with the other layout options you can choose to replace specific folders or folders with specific item types.

The following regions are only available for Outlook 2007 and 2010:

• TaskPaneDock Left, Right, Top, Bottom
  The TaskPaneDock Explorer layout enables you to provide your users with a custom region that is docked to either the left, right, top or bottom of Outlook’s UI. This layout is useful when you need to simulate the Outlook To-do bar.
• TodoBar.Bottom
  Setting the Explorer layout to TodoBar.Bottom will enable you to embed your custom region in the bottom of the Outlook To-do bar.

Select MailItem and ContactItem from the list of Explorer Item Types; this will cause the region to only be visible when the current Explorer Item Types are either mail or contact items.

Click Next. You have an option to share the same region for Inspector regions.

The following Inspector regions are available for Outlook 2003, 2007 and 2010:

• Inspector, Left, Right, Top, Bottom, CompleteReplacement

Similar to the Folderview or ReadingPane layout, the Inspector layout will dock your custom region to either the left, right, top or bottom of any Inspector object e.g. Outlook e-mail, contact and appointment forms. Setting the layout to Inspector adds your region to the main view of the form and gives the user buttons to navigate between the standard Outlook view and your custom region.

You are able to provide your own custom UI for an Inspector object by setting the Layout to Inspector.CompleteReplacement. This will remove/hide all the standard Outlook UI components, enabling you to provide your own UI.

Select Inspector.Left from the Inspector layout dropdown list and Mail from the Inspector item types list. For this example we’ll choose to show the region in both Read and Compose mode.

Click the Next button. Select Normal from the Default region state dropdown list and Standard in the Splitter dropdown list. We’ll choose to Always show header and to Allow the hidden state. You can also type a list of folders in which the region will be visible.

Click Finish. The wizard will create all the necessary code for you to use the Advanced Outlook Region from within your VSTO add-in. Open your newly created region’s designer by double-clicking it in the Solution Explorer. Next, change the design to look similar to the following image:

Add the following code to the Show Folder Totals button’s Click event:

VB.NET

Private Sub btnShowFolderTotals_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
        Handles btnShowFolderTotals.Click
        Dim currExplorer = DirectCast(Me.ExplorerObj, Outlook.Explorer)
 
        If currExplorer IsNot Nothing Then
            Dim currFolder As Outlook.MAPIFolder = currExplorer.CurrentFolder
            Dim currItems As Outlook.Items = currFolder.Items
 
            lblTotalItems.Text = currItems.Count().ToString
            lblTotalUnreadItems.Text = currFolder.UnReadItemCount.ToString()
 
            Marshal.ReleaseComObject(currItems)
            Marshal.ReleaseComObject(currFolder)
        Else
            Me.Highlight()
        End If
    End Sub

C#

private void btnShowFolderTotals_Click(object sender, EventArgs e)
{
	Outlook.Explorer currExplorer = (Outlook.Explorer)this.ExplorerObj;
	if (currExplorer != null)
	{
		Outlook.MAPIFolder currFolder = currExplorer.CurrentFolder;
		Outlook.Items currItems = currFolder.Items;
 
		lblTotalItems.Text = currItems.Count.ToString();
		lblTotalUnreadItems.Text = currFolder.UnReadItemCount.ToString();
 
		Marshal.ReleaseComObject(currItems);
		Marshal.ReleaseComObject(currFolder);
	}
	else
	{
		this.Highlight();
	}
}

And the following to the Show E-mail Properties button’s Click event:

VB.NET

Private Sub btnShowMailProperties_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
	Handles btnShowMailProperties.Click
	Dim currInspector As Outlook.Inspector = DirectCast(Me.InspectorObj, Outlook.Inspector)
 
	If currInspector IsNot Nothing Then
		Dim currItem As Object = currInspector.CurrentItem
		If TypeOf (currItem) Is Outlook.MailItem Then
			Dim mail As Outlook.MailItem = DirectCast(currItem, Outlook.MailItem)
			lblImportance.Text = mail.Importance.ToString()
			lblSubject.Text = mail.Subject
		End If
		Marshal.ReleaseComObject(currItem)
	Else
		Me.Highlight()
	End If
End Sub

C#

private void btnShowMailProperties_Click(object sender, EventArgs e)
{
	Outlook.Inspector currInspector = (Outlook.Inspector)this.InspectorObj;
	if (currInspector != null)
	{
		object currItem = currInspector.CurrentItem;
		if (currItem is Outlook.MailItem)
		{
			Outlook.MailItem mail = (Outlook.MailItem)currItem;
			lblImportance.Text = mail.Importance.ToString();
			lblSubject.Text = mail.Subject;
		}
		Marshal.ReleaseComObject(currItem);
	}
	else
	{
		this.Highlight();
	}
}

Make sure you add the following code to the top of your class in order for the code to compile:

VB.NET

Imports Outlook = Microsoft.Office.Interop.Outlook
Imports System.Runtime.InteropServices

C#

using Outlook = Microsoft.Office.Interop.Outlook;
using System.Runtime.InteropServices;

The code will check if an Inspector Item, in this case a mail item, does exist. If it does, it will show the e-mail properties on the advanced region. If, however, it does not exist, the region’s header will flash or highlight. We accomplish this by invoking the ADX Highlight method.

Thank you for reading. Until next time, keep coding!

Available downloads:

This sample add-in was developed using Add-in Express Regions for Microsoft Outlook and VSTO, beta 1:
VB.NET sample Outlook add-in

You may also be interested in:

Video: Ty Anderson introducing Add-in Express Regions for Outlook and VSTO
Add-in Express Regions for Outlook and VSTO – Basic concepts
Outlook Form regions
Outlook View regions