Introduction
Interacting with Microsoft Office (as well as taking advantage of the mountains of built-in classes and functions) can be a powerful addition to your business applications. You can perform highly valued operations using the interoperability assemblies that ship with Office products to give the user an experience that will be familiar and easy to adopt. This article is the first part of a two-part series. It will focus on interacting with Outlook within the context of a .NET application. You will create a simple example to familiarize yourself with the Outlook interoperability classes, specifically dealing with the manipulation of Outlook contact items. It will also discuss briefly the security implications associated with Outlook interaction from your .NET application. Part Two of this series will cover extending Outlook via an add-in, illustrating how to add a custom button to the Outlook toolbar.
Redemption
The Redemption DLL is one way to avoid the security warnings introduced by the “Outlook Security Patch” included in Office 2002 and later when accessing information deemed to be sensitive. For example, when you try to access a contact’s email property later in this article, without Redemption when your application makes the call to Outlook for the information, Outlook displays the following message to the user:
If you do not mind inconveniencing your users with such warnings and plan to train them on the appropriate response to said dialogs, you can skip the rest of this section and all later references to Redemption. Less sadistic coders will be interested in the fact that the Redemption library exposes a method to access “sensitive” information without warnings. Redemption is available free for development purposes but requires a onetime licensing fee when distributing it with your applications. For more information about this library and to download the DLL, navigate here.
The source code sample included with this article does not use Redemption in case you choose not to download it; however, the code includes lines where Redemption could be used but are commented out. Also, note that no error catching is present in this sample code for the case when your user chooses to deny a security access request. You will want to add error checking in a real-world application. Redemption would avoid these scenarios.
If you decide to use Redemption, you will have to register the DLL on your computer by issuing the following command at a command prompt after navigating to the folder location of the DLL:
RegSvr32 Redemption.dll
You will also need to add a reference to the DLL in your solution before re-instating the code that uses Redemption to suppress the warnings.
Getting Started
Unlike Redemption, the Outlook COM library is a necessary reference for building an application that interacts with Outlook. For this article and its sample, I am using Visual Studio 2005 (.NET Framework 2.0), C#.NET, and Microsoft Office Outlook 2003. The first step is to add a reference to the appropriate Outlook COM library in your project. The Office interop libraries are located under the COM tab of the references dialog in Visual Studio. In my case, because I am using Outlook 2003, the library is called “Microsoft Outlook 11.0 Object Library.” These interop libraries ship with Office. Therefore, if you have Outlook 2003 installed on your machine, this is the library you will see. If you have Outlook 2007 installed, instead you will see “Microsoft Outlook 12.0 Object Library.”
In each class that will use the Outlook functionality, you will also want to include the following using directive:
using Outlook = Microsoft.Office.Interop.Outlook;
Please note that you may need to adjust the references in the sample project to run it with your machine’s configuration.
Creating a Simple Outlook Contact Management Application
To demonstrate some of the functionality of the Outlook interop class, you will create a “contact management” application that enables a user to choose an Outlook folder from which to view contacts, see the information for each contact when hovering over the name, and to alter some of the contacts’ properties. The sample will introduce you to the Outlook classes and how easy it can be to come up with your own uses for interacting with Outlook (and, by extension, Office) from your .NET applications.
The application, on first glance, will have an empty list box and a button to “Get Contacts” like so:
When the user clicks the button, he will be presented with an Outlook-style folder picker to choose the folder from which he wants to “import” contacts. The Outlook interop class exposes a PickFolder method of its Namespace class to provide this functionality with one line of code. First, however, you need to create an Outlook Application object that will expose the Outlook functionality and get its Namespace object.
Outlook.Application oApp = new Outlook.Application();
Outlook.NameSpace oNS = oApp.GetNamespace("MAPI");
“MAPI” is the supported parameter for the GetNamespace method with Outlook. The following code and screenshot illustrate how you accomplish the task of allowing the user to choose an Outlook folder.
private Outlook.MAPIFolder oContactsFolder = oNS.PickFolder();
You will limit the “import” process to contact types, so if the user chooses a folder with no contacts in it, he will receive no results. The PickFolder method returns an object of type MAPIFolder. Once you have a reference to the desired folder, you can iterate through its items. Before doing so, you will restrict the items to the contact type.
string filter = "[MessageClass] = "IPM.Contact""
Outlook.Items oContactItems = oContacts.Items.Restrict(filter);
foreach (Outlook.ContactItem oContact in oContactItems)
{}
The Restrict method takes a filter argument, a formatted string referencing the item’s properties to search against in brackets with the search criteria in quotations. For more information on creating the filter string and for some examples, refer to the MSDN article.
The ContactItem class exposes properties of the contact such as:
- LastName, FirstName, MiddleName, Title
- JobTitle
- Email1Address, Email1DisplayName, IMAddress
- WebPage
- BusinessTelephoneNumber, OtherTelephoneNumber, PagerNumber, MobileTelephoneNumber, BusinessFaxNumber
The list goes on, but the above enumerates the properties you will use for the example. The Email1Address, Email1DisplayName, and IMAddress properties are special in this list. They are properties that, when accessed, will cause Outlook to prompt the user with the security warning mentioned above. The others will not.
I use Email1DisplayName to populate the ListBox on my form. I then display some of the properties in a tool tip in the hover event.
When the user double-clicks one of the contacts, a new form will open up; it allows the user to modify the contact’s information. The following sample code shows how to update the contact with the information from the textboxes.
oContact.FirstName = textBoxFirst.Text; oContact.LastName = textBoxLast.Text; oContact.MiddleName = textBoxMiddle.Text; oContact.Title = textBoxTitle.Text; oContact.JobTitle = textBoxJobTitle.Text; oContact.WebPage = textBoxWebPage.Text; oContact.Email1Address = textBoxEmail.Text; oContact.Save();
Notice that you can write to the Email1Address property without triggering the security warning. The Outlook security model will block read access to the property to prevent applications from stealing your information. You will not receive a security warning when you simply set the property to a new value. Once you have set the properties, the save method will update the contact in Outlook.
Sending an Email to Your Contacts
Just to give an example of the contacts in use, you can add a button to the application’s form that will automatically send an email to the selected contact in the ListBox. The button’s click event looks like this:
Outlook.Application oApp = new Outlook.Application();
if (this.listViewContacts.SelectedItems != null &&
this.listViewContacts.SelectedItems.Count > 0)
{
Outlook.ContactItem oRecip = (Outlook.ContactItem)
(this.listViewContacts.SelectedItems[0].Tag);
Outlook.MailItem email = (Outlook.MailItem)
(oApp.CreateItem(Outlook.OlItemType.olMailItem));
email.Recipients.Add(oRecip.Email1Address);
email.Subject = "Just wanted to say...";
email.Body = "Have a great day!";
if (MessageBox.Show(
"Are you sure you want to send a good day message to " +
oRecip.Email1DisplayName + "?", "Send?",
MessageBoxButtons.OKCancel)
== DialogResult.OK)
{
try
{
((Outlook.MailItem)email).Send();
MessageBox.Show("Email sent successfully.", "Sent");
}
catch (Exception ex)
{
MessageBox.Show("Email failed: " + ex.Message,
"Failed Send");
}
}
oRecip = null;
email = null;
}
Unless you are using Redemption, the above code again will be affected by security warnings.
Business Case
There are many business cases for which Outlook interop would be a great solution. In my case, I use Outlook interop and Redemption to do an actual import of a user’s Outlook contacts so that the contacts can be associated with projects created within the enterprise application. The user then can store information about the contact specific to the application’s use. I also use Redemption’s AddressBook functionality to quickly implement a feature that allows the user to choose one of their active directory-level users to send emails and add users to the review processes. Finally, I tap the Outlook classes to create an add-in that allows users to “push” emails from the Outlook console to the application as an attachment to projects.
Conclusion
The functionality exposed in this article is really only a very small subset of things you can do with the Outlook Interoperability classes (and, by extension, the whole suite of Office integration libraries). You learned how to tap the Outlook classes to manipulate information about a user’s contacts as well as utilize the built-in functionality, such as the folder picker. I encourage you to play with the libraries to investigate how they can help you with your business application needs. Look for Part Two of this series to learn how extending Outlook via an add-in can increase your users’ productivity by exposing new functionality in an environment with which they are already familiar and comfortable. Reduce development time and increase value by starting with the Office suite as your starting point instead of building an Office-related application from scratch.
Acknowledgements
I would like to thank Matt Goebel for his suggestions and help with this article series.
About the Author
Rachel Wireman (MCPD, MCTS) is a developer specializing in Windows-based solutions at Crowe Chizek in Oak Brook, Illinois. Reach her at rwireman@crowechizek.com.
