Outlook 2013 add-in development for beginners: Outlook Application & base objects
Working with a new framework takes time as you familiarize yourself with its architecture and best practices. You have to spend time discovering objects, learning what they do, and when it is best to utilize them. For Outlook addin development (and Microsoft Office development in general), this task can take months due to the number of objects involved. The complexity is both fun and frustrating… you have to embrace it.
Add-in Express for Office exists to reduce the frustration and increase the fun (or at least the Office development productivity). A key way we do this is by making it easy to access Outlook objects and automate them via your code. Not only that, we provide our own class, the AddinModule, to help you organize your solution.
In the first part of the series that will focus on Outlook 2013 add-in development in Visual Studio 2012 for beginners, we are going to have a close look at the following aspects:
Within an Add-in Express based COM Add-in, the core component is the AddinModule; it serves as the gateway to the host application and objects. It is also the location for your core business logic.
AddinModule is also the location for building your custom UI elements. Elements like ribbons & toolbars. To build them, you click their related button on the AddinModule’s toolbar and add them to the AddinModule’s design surface. It is also the place to add Outlook form region managers, Outlook application events and much more.
I start here because the AddinModule is you starting point and your home when using Add-in Express. To access and automate Outlook objects, you begin here and access Outlook’s application object.
Add-in Express provides you with quick and easy access to the Outlook application via a property called OutlookApp. This property returns the Outlook._Application object, which is the root object of Outlook; from this object you can access any objects within Outlook. The OutlookApp property is an analog of Application you find in Office VBA and within a VSTO project. If you have any familiarity with them, you have a leg-up when you begin to use our toolset.
You can access the Outlook easily within your code as follows:
Public Function GetOutlookVersoin() As String Return Me.OutlookApp.Version End Function
The above is a very simple function that uses the OutlookApp property to return the version of Outlook hosting the add-in. Here, Me is the AddinExpress AddinModule and OutlookApp is the Outlook Application object. Simple enough.
Base objects are main objects that reside just below OutlookApp. The best way to discover the base objects is to open the AddinModule in code view, create a method, and type “OutlookApp.” to invoke Visual Studio’s IntelliSense.
Right off the bat you get a good indication of what some other base objects are. Looking at the image above, the ActiveExplorer and ActiveInspector list first. These objects represent the two types of windows Outlook employs to display data to its user: Explorers and Inspectors. Each of these allow a user to work with Outlook items (i.e. mail, appointments, contacts, etc.) but they have different purposes. The point is that Visual Studio makes it easy to identify and utilize base objects.
The table below lists the base objects for Outlook.
|Outlook Item||Description||How to access|
|Explorers||The collection of explorer windows open in Outlook.||OutlookApp.Explorers|
|Explorer||An Outlook window that allows the user to navigate within their Outlook folder structure to “explore” and discover their Outlook items.||OutlookApp.Explorers(0)
|Inspectors||The collection of inspector windows open in Outlook.||OutlookApp.Inspectors|
|Inspector||Displays an individual Outlook item in a separate window.||OutlookApp.Inspectors(0)
|Data Storage||The Outlook data store is called the Namespace. It is also known as the Session object. This object provides you with access to Outlook’s folder structure.||OutlookApp.SessionOutlookApp.GetNamespace(“MAPI”)|
|Folders||The folder collection (or data hierarchy) of the Outlook session.||OutlookApp.Session.Folders|
|MAPIFolder||An individual Outlook folder.||Continue to the next section|
|Items and Item||An Outlook item: mail, appointment, contact, and task being the most common item types.||Continue to the next section|
The key to learning to use Add-in Express for Outlook add-in development is to be curious and explore the various object models. The best place to start is with the OutlookApp object and keep traversing its child objects to learn what there is to learn.
This section is about the code. The examples are functional and intended to be samples you can copy and paste in to get going with Outlook development.
Get active Explorer and current folder
Often, you want to grab access to the Outlook Explorer window the user sees right now. This is the ActiveExplorer object and allows to easily grab a reference to the folder the user is accessing.
Public Function GetFolderType() As String Dim olEx As Outlook.Explorer = Nothing Dim fldr As Outlook.MAPIFolder = Nothing Try olEx = Me.OutlookApp.ActiveExplorer 'Now do something with it...like grab its current folder fldr = olEx.CurrentFolder Return fldr.DefaultItemType.ToString() Finally If (olEx IsNot Nothing) Then Marshal.ReleaseComObject(olEx) If (fldr IsNot Nothing) Then Marshal.ReleaseComObject(fldr) End Try End Function
An Outlook folder is a MAPIFolder in the Outlook object model. If you can remember that, you are well on your way. Here, we declare a MAPIFolder variable and assign the CurrentFolder to it. The function returns the default item type stored in the folder. The MAPIFolder object has two useful collections – Folders and Items. They are purposed for accessing the sub-folders of MAPIFolder and Outlook items contained in the folder, respectively.
Get an active Inspector and item
Working with the ActiveInspector is much like the ActiveExplorer except that you will be accessing an individual Outlook item. The following code grabs the ActiveInspector, accesses its item, changes the item’s Importance, and save it.
Public Sub GetActiveInspectorItemAndDoSomething() Dim insp As Outlook.Inspector insp = OutlookApp.ActiveInspector 'Let's assume it's a mail item Dim mailItm As Outlook._MailItem mailItm = TryCast(insp.CurrentItem, Outlook._MailItem) If (mailItm IsNot Nothing) Then mailItm.Importance = Outlook.OlImportance.olImportanceHigh mailItm.Save() Marshal.ReleaseComObject(mailItm) End If Marshal.ReleaseComObject(insp) End Sub
The procedure makes a big assumption the item is an Outlook.MailItem.
Get a default Outlook folder
If you need to grab quick access to default folder you can use a function like this.
Public Function GetDefaultFolder(folderType As Outlook.OlDefaultFolders) _ As Outlook.MAPIFolder Dim ns As Outlook._NameSpace = OutlookApp.Session Try Return ns.GetDefaultFolder(folderType) Finally Marshal.ReleaseComObject(ns) End Try End Function
The Namespace object has the GetDefaultFolder method. All you need to do is pass the type of folder you want: mail, task, contact, etc.
I made a method that can be called anywhere in your code. But, it is also handy to use this:
Dim folder As Outlook.MAPIFolder Dim ns As Outlook._NameSpace = OutlookApp.Session folder = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox) Marshal.ReleaseComObject(ns) ' ...
This is a common task.
Create an item
You create an item by calling the OutlookApp’s CreateItem method. Here, I create a task, set a few key properties, and save it.
Public Sub CreateTask(title As String) Dim myTask As Outlook._TaskItem myTask = OutlookApp.CreateItem(Outlook.OlItemType.olTaskItem) With myTask .Subject = title .DueDate = Today() .Importance = Outlook.OlImportance.olImportanceNormal .Save() End With Marshal.ReleaseComObject(myTask) End Sub
This example saves the task in the user’s default task folder.
A few samples are a head start
These are just a few examples of what is really big world. Outlook has a mature object model and the best way to learn it is to dig in and investigate what it offers. We make it easy to do via the OutlookApp property. From OutlookApp, you can quickly access and create Outlook base objects.
- Part 1: Outlook Application and base objects
- Part 2: Creating custom Outlook views
- Part 3: Creating custom Outlook forms
- Part 4: Outlook UI – Explorer and Inspector Windows. What is customizable?
- Part 5: Customizing Outlook main menu, context menus and Backstage view
- Part 6: Creating custom Outlook ribbons and toolbars
- Part 7: Advanced view regions for Outlook 2013 – 2003
- Part 8: Advanced form regions for Outlook 2013 – 2003
- Part 9: Working with Outlook Accounts, Stores, Folders and Items
- Part 10: Working with Outlook calendar
- Part 11: Working with Outlook tasks