Create Office 2010 - 2000 plugins / add-ins in
Visual Studio .NET: VB, C#, C++ - Developer's Guide
Add-in Express™ Regions
Programming with Advanced Regions
You can use Add-in Express Regions for Outlook and directly within your VSTO 2008 or 2010 projects. Create an Outlook add-in project in VSTO and add an Add-in Express Advanced Outlook Region class to the project. Doing this starts the Add New Region wizard:
The wizard adds a form region class to your project and allows specifying the following settings of your region:
After the form is added, add a button and label onto the form. The controls in the sample are named Button1 and Label1.
Is it Inspector or Explorer?
Add an event handler for the Load event of the form and write the following code:
The code above demonstrates the base principle:
InspectorObj and ExplorerObj properties return COM objects that you must never release in your code because their state is crucial for the functionality of your advanced region. These properties will be released automatically when your form is removed from its region. This may occur several times during the lifetime of a given form instance because the manager may remove your form from a given region and then embed the form to the same region in order to comply with the Outlook windowing.
Accessing ThisAddIn from the form
We suggest adding a Shared (static in C#) member in ThisAddIn. In this sample, we use the code below:
The use of AddinInstance is demonstrated below.
Accessing the Outlook Object Model
Add the following to the Click event handler of the button:
And in ThisAddIn, add methods that deal with the Outlook object model:
Note that the COM object standing for the Outlook Inspector is not released in the code above; that's because that COM object is controlled by the forms manager and it must not be released in your code (see below).
Releasing COM objects - a must in Outlook add-ins
A comprehensive review of typical problems (and solutions) related to releasing COM objects in Office add-ins is given in an article published on the Add-in Express technical blog - When to release COM objects in Office add-ins?
Below are some useful tips.
Pay attention that Inspector.CurrentItem returns an Object (with an underlying RCW pointing to the COM object) and passing the Object to another method as well as casting it to Outlook.MailItem doesn't produce new COM objects (doesn't increase the reference counter).
Passing Nothing (null in C#) to ReleaseComObject produces an exception. Passing a non-COM object to ReleaseComObject produces an exception, too. These situations are handled by the method you add to ThisAddIn:
You can also get the "COM object that has been separated from its underlying RCW cannot be used" exception if you pass a variable to ReleaseComObject and then use the variable in your code. We recommend assigning Nothing (null in C#) to all released variables.
The functionality provided by Add-in Express Regions for Outlook and VSTO is based on the combined use of the Outlook windowing and features provided by the Outlook object model. These two areas are essentially different and keeping objects from these areas in sync requires significant efforts. Some difficulties are impossible to overcome. One of them is born by the need to control the state of COM objects provided by in properties and events of Add-in Express Regions: releasing any of such objects may lead to a run-time exception.
Do not release any COM objects you acquire in the properties and events of ADXOlFormsManager and ADXOlForm. On the contrary, release every COM object you create in your code.
Dealing with Outlook events
Let's handle the SelectionChange event provided by the Outlook.Explorer object.
The DoExplorerClose method demonstrates how you disconnect from events provided by a COM object.
Accessing the form from ThisAddIn
You get a collection item and call the GetCurrentForm method. That method provides a parameter the possible values of which address to the Visible and Active properties of ADXOlForm.
The Visible property of a form region instance is true when the instance is embedded into a window region (as specified by the visualization settings) regardless of the actual visibility of the instance.
The Active property of the form region instance is true when the instance is shown on top of all other instances in the same region.
The code is shown below:
The code refers to the SelectedItemSubject property defined in ADXOlForm1; the code of the property is omitted for brevity - it just assigns the string to Label1.Text.