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:

• AddinModule
• Application object
• Outlook base objects
• Accessing base objects

AddinModule

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.

The 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.

Outlook base objects

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.

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.

Accessing base objects

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.

Outlook 2013 add-in development in Visual Studio 2012 for beginners

• 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

You may also be interested in:

• Video: How to create Outlook 2013-2003 add-ins with a single code base
• C#, VB.NET – Creating an Outlook add-in
• Sepcial features for Outlook plugin development