Integrating Outlook Regions into VSTO projects:
Visual Studio 2008 and 2010, VB.NET, C#

Once you have Add-in Express Regions installed, it's very easy to get started integrating Outlook Regions into your VSTO project. All you have to do is launch the Add New Item dialog, select "ADX Region for Outlook and VSTO" and step through the New Region Wizard. All required components, forms and code will be inserted into your project so you can quickly start designing your UI.

Behind the scenes, a reference to the AddinExpress.Outlook.Regions.dll assembly is added to your VSTO project. This allows for the implementation of our Add-in Express Regions technology with all of the necessary Objects in the AddinExpress.Extensions and AddinExpress.OL namespaces.

The most important new component in your project is the FormsManager module extending the ThisAddIn class.

This class exposes all of the necessary events for interacting with your Regions:

• ADXBeforeFolderSwitchEx
• ADXBeforeFormInstanceCreate
• ADXFolderSwitch
• ADXFolderSwitchEx
• ADXNavigationPaneHide
• ADXNavigationPaneMinimize
• ADXNavigationPaneShow
• ADXNewInspector
• ADXReadingPaneHide
• ADXReadingPaneMove
• ADXReadingPaneShow
• ADXTodoBarHide
• ADXTodoBarMinimize
• ADXTodoBarShow
• OnError
• OnInitialize

A quick walkthrough...

To illustrate how easy it is to add an Add-in Express Region to your VSTO project, let's go through the Wizards that'll help you get up and running. If you want to follow along with Visual Studio 2010, start by creating a new Outlook 2010 VSTO add-in project, select "Add New Item" from the Project menu and choose the "ADX Region for Outlook and VSTO" item. This will add an ADXOlForm class to your project. This is really your Windows Form to build the custom UI for your region, but it inherits from the AddinExpress.OL.ADXOlForm class instead of System.Windows.Forms.Form.

Next, you'll see the first screen of the New Region Wizard:

This screen is specific for Explorer windows (the main Outlook window), and allows you to choose from numerous regions via the Explorer Layout drop down control. If you don't want your Windows Form to be displayed in an Explorer window at all (or want to control its appearance dynamically in code), that's fine - just leave it at "Unknown".

Once you've selected a layout type, notice that we are displaying a mock-up of an Explorer window, with the area to be extended highlighted in yellow (in this case we're targeting ReadingPane.Bottom). What's especially handy is the text under the layout preview that'll show which versions of Outlook support extensibility in the region you've chosen. One more thing though: make sure to select the item types that you want to support for your region (as per the Explorer Item Types list box, where only MailItem is selected). If you want to support only a custom message class, you can do so as well by entering the specific "IPM.<itemtype>.<your_form_name>" value in the Explorer message class text box.

The next dialog in the Wizard is specific to Inspector regions, but very similar to the previous dialog for Explorer regions. The key difference is the ability to choose the mode for your region via the Inspector mode checked list box. As any Outlook user is well aware, Outlook items are either new (compose) items or received (read) items.

The last screen of the wizard allows you to set the global properties for your region. These include setting the default region state (Normal, Minimized or Hidden), the splitter behaviour (None or Standard), and whether to display the header or close button. You can also set whether to allow your region to support drag and drop, hidden states, or to use the Office theme for the background.

If you ever need to change the behavior or properties of your regions after you've used the Wizard, simply modify the code that's automatically inserted into the OnInitialize event of the forms manager class when the Wizard first creates your region:

VB.NET

					Private Sub FormsManager_OnInitialize() Handles FormsManager.OnInitialize
    
        'ADXOlForm1
        Dim ADXOlForm1Item As ADXOlFormsCollectionItem = New ADXOlFormsCollectionItem()
        ADXOlForm1Item.ExplorerLayout = ADXOlExplorerLayout.BottomNavigationPane
        ADXOlForm1Item.ExplorerItemTypes = ADXOlExplorerItemTypes.olMailItem
        ADXOlForm1Item.InspectorLayout = ADXOlInspectorLayout.BottomSubpane
        ADXOlForm1Item.InspectorItemTypes = ADXOlInspectorItemTypes.olMail
        ADXOlForm1Item.AlwaysShowHeader = True
        ADXOlForm1Item.CloseButton = True
        ADXOlForm1Item.UseOfficeThemeForBackground = True
        ADXOlForm1Item.FormClassName = GetType(ADXOlForm1).FullName
        FormsManager.Items.Add(ADXOlForm1Item)

    End Sub

					

C#

					private void FormsManager_OnInitialize()
        {

            #region ADXOlForm1
            ADXOlFormsCollectionItem ADXOlForm1Item = new ADXOlFormsCollectionItem();
            ADXOlForm1Item.ExplorerLayout = ADXOlExplorerLayout.BottomNavigationPane;
            ADXOlForm1Item.ExplorerItemTypes = ADXOlExplorerItemTypes.olMailItem;
            ADXOlForm1Item.InspectorLayout = ADXOlInspectorLayout.BottomSubpane;
            ADXOlForm1Item.InspectorItemTypes = ADXOlInspectorItemTypes.olMail;
            ADXOlForm1Item.AlwaysShowHeader = true;
            ADXOlForm1Item.CloseButton = true;
            ADXOlForm1Item.UseOfficeThemeForBackground = true;
            ADXOlForm1Item.FormClassName = typeof(ADXOlForm1).FullName;
            FormsManager.Items.Add(ADXOlForm1Item);
            #endregion;

        }
					

Aside from that, the only other changes to your project are a few lines of code in the ThisAddIn class to initialize and finalize your regions. And even that is done for you!

VB.NET

					Public Class ThisAddIn
    Private Sub ThisAddIn_Startup() Handles Me.Startup
        'Add-in Express Regions generated code
        Me.FormsManager = AddinExpress.OL.ADXOlFormsManager.CurrentInstance
        Me.FormsManager.Initialize(Me)
    End Sub

    Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown
        'Add-in Express Regions generated code
        Me.FormsManager.Finalize(Me)
    End Sub
End Class
					

C#

					public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {

            #region Add-in Express Regions generated code;

            this.FormsManager = AddinExpress.OL.ADXOlFormsManager.CurrentInstance;
            this.FormsManager.OnInitialize +=
                new AddinExpress.OL.ADXOlFormsManager.
				    OnComponentInitialize_EventHandler(this.FormsManager_OnInitialize);
            this.FormsManager.Initialize(this);

            #endregion;
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {

            #region Add-in Express Regions generated code;

            this.FormsManager.Finalize(this);

            #endregion;
        }
    }