|In this article, we will step through creating an email message and a contact using VSTO.|
Time Required: 1-3 hours
Software: Visual Studio 2005
When I read the announcement that Visual Studio 2005 Tools for Microsoft Office (VSTO 2005) had added support for Microsoft Outlook (currently in beta), I downloaded it immediately! After all, my digital universe revolves around email, and being able to easily extend Outlook in custom ways has always been a wish of mine. Writing add-ins for Outlook certainly isn't a new capability, but it was never as easy to write useful, secure code as it is now.
My first step was to download the VSTO Outlook Beta installer. Then, to speed up the learning curve, I downloaded the conveniently supplied snippets. Including the snippets, even this early build is immensely helpful and a great way to jumpstart your creativity. As you will see, the extensibility is quite broad, and in fact we will only be able to scratch the surface with this article. Don't worry though; I'll revisit it again in future columns.
The application we will create today is basically a Hello World for Outlook. We'll step through creating an email message and a contact. The supplied code samples in this article are written in C#, however Visual Basic source code is also included with the code download for this article. Developing with VSTO requires a version of Visual Studio greater than Express Edition. The current beta of Visual Studio can be downloaded from http://lab.msdn.microsoft.com/vs2005/get/. Of course, Microsoft Office Professional 2003 (Service Pack 1) is also a requirement for this article, or at least Outlook 2003 SP1. Be aware that Outlook Express will not function as a replacement for Outlook.
The first step after installing the above is to create an Outlook Add-in project in the Office project templates section in Visual Studio. Notice that alongside the Excel and Word templates, there is a new option for Outlook. Specify a name and click OK.
Creating the Outlook Add-in project (click image to zoom)
Actually working with the new features could have proved to be difficult, but it turns out that the object model and available events just make sense. The project template adds a few references for general VSTO and specifically for Outlook. It also creates a setup project to simplify deployment. The main class file is ThisApplication.cs and contains a Startup and Shutdown event handler similar to other VSTO project types.
To avoid presenting too much material at once, in our example creating these items will occur when the add-in starts up and we will not use a menu or any user input to trigger it. Though not realistic, it makes it easier to step into this new functionality. Keep in mind though, that you can create custom menus on the standard menu bar, or respond to events such as the currently active folder, new messages arriving, or an appointment reminder.
Creating mail items, contacts, and folders is easy using the snippets, but be sure to read the readme that appears after installing them. Though the snippets are installed, they will not appear in the Insert Snippet menu item until added through the Visual Studio Snippets Manager (Tools | Code Snippets Manager menu command).
In order to create a new mail message, you will first need to obtain a reference to an Outlook.MAPIFolder object. This encapsulates an Outlook folder like Inbox, Draft, Outbox, or user-created folders. In order to get the default Outbox folder call the GetDefaultFolder method of the MAPI namespace object:
Outlook.MAPIFolder outBoxfolder = this.GetNamespace("MAPI").GetDefaultFolder(
Dim outBoxfolder As Outlook.MAPIFolder =
Correction (9/7/2005, thanks to Sue Mosher, Outlook MVP): You should actually use the Application.CreateItem method, which is the standard (and simpler) technique for creating a new item in one of the default folders.
Once you have a reference to the folder, you can add an item to it. Because the Outbox is generally intended for mail items, that is what we will add, but remember that Outlook supports any item type being added to any folder. To create and add a new mail item, call the Items.Add method of the folder object:
Outlook.MailItem mailItem = (Outlook.MailItem)outBoxfolder.Items.Add(Outlook.OlItemType.olMailItem);
Dim mailItem As Outlook.MailItem =
At this point you have a mail item to manipulate. You can set the Subject, Body, and To properties, add a reminder, attach files, display the message, and of course send it:
mailItem.Subject = "Coding4Fun Sample";
mailItem.Body = "This email was created using VSTO 2005 Outlook support.";
mailItem.To = "emailaddress@emailaddress";
mailItem.Subject = "Coding4Fun Sample"
mailItem.Body = "This email was created using VSTO 2005 Outlook support."
mailItem.To = "emailaddress@emailaddress"
Sending the message simply requires calling the Send method, while displaying the message is accomplished with the Display method (modally or not). If you do not call the Send or Save method, the message will not persist unless you display the message to allow the user to save or send it. This model is consistent with the various item types.
If you have added the snippets, you can create a mail item in two quick steps: insert the snippet, and then fill in the placeholder fields. You should probably create a new method to contain your message sending code, then right-click and select Insert Snippet, and navigate to the Outlook | Create sub-menu. You will see all of the above code, including helpful TODO comments, and commented out Send and Display calls.
A sample message (click image to zoom)
There is no snippet for adding a task item (yet anyway), so for our final sample, let's create a new task. The API is so well thought-out, that once you can create an email, creating a task is a snap. As before, obtain a reference to the folder, this time the Tasks folder. Also as before, remember that any folder will hold a task. This feature is useful for linking items and maintaining isolation between business or project boundaries. Once again, the folder is one of the defaults, so call GetDefaultFolder, this time with the olFolderTasks enumerated folder name:
Outlook.MAPIFolder tasksFolder = this.GetNamespace("MAPI").GetDefaultFolder(
Dim outBoxfolder As Outlook.MAPIFolder =
Next, add a new instance of a task item. Notice that you are not calling a constructor. Each item type is actually an interface. Items must be created as children of a folder, not as stand-alone objects:
Outlook.TaskItem taskItem = (Outlook.TaskItem)tasksFolder.Items.Add(Outlook.OlItemType.olTaskItem);
Dim taskItem As Outlook.TaskItem =
Next, set the appropriate properties. In this case, the task's subject, owner, percentage complete, and status. Status is an enumerated type representing Complete, Deferred, In Progress, Not Started, and Waiting.
taskItem.Subject = "Finish Coding4Fun article!";
taskItem.Owner = "Bob";
taskItem.PercentComplete = 0;
taskItem.Status = Microsoft.Office.Interop.Outlook.OlTaskStatus.olTaskInProgress;
taskItem.Subject = "Finish Coding4Fun article!"
taskItem.Owner = "Bob"
taskItem.PercentComplete = 0
taskItem.Status = Microsoft.Office.Interop.Outlook.OlTaskStatus.olTaskInProgress
The final step is to save the task. This step must be called, or the task will be lost when Outlook is closed or the object goes out of scope.
VSTO support for Outlook makes it painless to create add-ins for Outlook in managed code. You can create all of the common entity types such as email messages, contacts, and tasks, respond to events, create HTML folder views, and also add application menus. Download Visual Studio 2005, the beta VSTO Outlook installer, then give this application a try. Get started at http://lab.msdn.microsoft.com/vs2005/get/.