Outlook Items and Folders Events explained

In this post, we’ll have a closer look at two classes provided by Add-in Express: the Outlook Folders Events class and the Outlook Items Events class. I’ll be using Add-in Express 2010 for Office and .Net and Visual Studio 2010.

First, let’s create a new COM Add-in in Visual Studio:

In the first prompt of the New Microsoft Office COM Add-in project wizard, select your programming language and the Minimum Office version you would like to support. Today we’ll be using Visual C# and Microsoft Office 2007.

Since the Outlook ItemEvents and FolderEvents classes are only available for Microsoft Outlook we’ll choose Microsoft Outlook from the list of Supported Applications.

Outlook Items Events class

Add a new Outlook Items Events Class to your project by Selecting Add New Item… from the Visual Studio Project menu. The item template is under Add-in Express Items > Outlook.

In order to use the Outlook Items Events Class we need to add some code to the AddinModule class.

First declare the Outlook Items Events class we’ve just added:

OutlookItemsEventsClass itemsEvents = null;

Switch to the AddinModule designer and double-click in its AddinStartupComplete event in the property grid to generate an empty event handler.

Add the following code to the AddinStartupComplete event handler:

private void AddinModule_AddinStartupComplete(object sender, EventArgs e)
{            
    itemsEvents = new OutlookItemsEventsClass(this);
    itemsEvents.ConnectTo(ADXOlDefaultFolders.olFolderContacts, true);
}

We also need to add an event handler for the AddinBeginShutdown event and insert the following code:

private void AddinModule_AddinBeginShutdown(object sender, EventArgs e)
{
    if (itemsEvents != null)
    {
        itemsEvents.RemoveConnection();
        itemsEvents.Dispose();
    }
}

Now that we’ve added all the necessary code to the AddinModule class, open the Outlook Items Events class we’ve added earlier and let’s have a look at the Items Events.

ProcessItemAdd

This event occurs when one or more items are added to the specific folder. A reference to the newly added item is passed as a parameter. Be careful though because this event does not fire when a large number of items are added to the folder at once. This is one of the reasons this event is not reliable when checking for new mail. You can read more about it in Eugene’s post: Handling NewMail, NewMailEx and ItemAdd Outlook events in .NET. We’ll investigate the NewMail challenge later in a series of posts.

public override void ProcessItemAdd(object item)
{
    if (item is Outlook._ContactItem)
    {
        Outlook._ContactItem newContact = (Outlook._ContactItem)item;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
        Outlook.MAPIFolder targetFolder = (Outlook.MAPIFolder)this.FolderObj;
        Outlook._JournalItem journalItem = null;

        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            journalItem.Subject = String.Format("You've added {0} to {1}", 
                newContact.FullName, targetFolder.FolderPath);
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessItemChange

This event is fired when an item in the specified folder is changed. A reference to the changed item is passed as a parameter.

public override void ProcessItemChange(object item)
{
    if (item is Outlook._ContactItem)
    {
        Outlook._ContactItem changedContact = (Outlook._ContactItem)item;

        if (String.IsNullOrEmpty(changedContact.JobTitle))
        {
            MessageBox.Show(String.Format(
				"Please add a job title for {0}. All contacts must have proper titles",
                 changedContact.FullName), 
				 "Title Required");
        }
    }
}

ProcessItemRemove

This event is the opposite of the ProcessItemAdd event and occurs when an item is deleted from a specified folder. As with the ProcessItemAdd event, this event does not fire when more than 16 items are deleted at once. It also does not fire when the last item in a .pst file is deleted. Unfortunately this event does not give us any reference to the items that has been deleted.

public override void ProcessItemRemove()
{
    Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
    Outlook.MAPIFolder targetFolder = (Outlook.MAPIFolder)this.FolderObj;
    Outlook._JournalItem journalItem = null;

    try
    {
        journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
			Outlook.OlItemType.olJournalItem);
        journalItem.Subject = String.Format("You've removed items from {0}", 
			targetFolder.FolderPath);
        journalItem.Save();
    }
    finally
    {
        if (journalItem != null)
            Marshal.ReleaseComObject(journalItem);

    }
}

ProcessBeforeItemMove

In Outlook 2007-2010 you can use the ProcessBeforeItemMove event to determine when an item is about to be deleted or moved from a folder. A reference to the item being moved is passed as a parameter as well as a reference to the folder it is being moved to. If the item is deleted permanently the MoveTo parameter will be Null or Nothing in Visual Basic.

public override void ProcessBeforeItemMove(object item, object moveTo,
	AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (item is Outlook._ContactItem)
    {
        Outlook._ContactItem movedContact = (Outlook._ContactItem)item;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
        Outlook._JournalItem journalItem = null;

        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            if (moveTo != null)
            {
                Outlook.MAPIFolder targetFolder = (Outlook.MAPIFolder)moveTo;
                journalItem.Subject = String.Format("You've moved {0} to {1}",
                    movedContact.FullName, targetFolder.FolderPath);
                Marshal.ReleaseComObject(moveTo);
            }
            else
            {
                journalItem.Subject = String.Format(
					"You've permanently deleted {0}", movedContact.FullName);
            }
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessBeforeFolderMove

This event occurs when a folder is about to be deleted or moved. A reference to the folder it is being moved to, is passed as a parameter. As with the ProcessBeforeItemMove event, if the MoveTo parameter is Null or Nothing in Visual Basic, it means the folder has been permanently deleted.

public override void ProcessBeforeFolderMove(object moveTo,
	AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.FolderObj != null)
    {
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
        Outlook._JournalItem journalItem = null;

        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            if (moveTo != null)
            {
                Outlook.MAPIFolder targetFolder = (Outlook.MAPIFolder)moveTo;
                journalItem.Subject = String.Format(
					"You've moved the folder to {1}", targetFolder.FolderPath);
            }
            else
            {
                Outlook.MAPIFolder deletedFolder = (Outlook.MAPIFolder)this.FolderObj;
                journalItem.Subject = String.Format(
					"You've permanently deleted {0}", deletedFolder.FolderPath);
            }
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

You can read more about these events here and here.

Outlook Folders Events class

Add a new Outlook Folder Events Class to your project by Selecting Add New Item… from the Visual Studio Project menu. The item template is under Add-in Express Items > Outlook.

Declare the Folders event class:

OutlookFoldersEventsClass folderEvents = null;

Add the following code to the AddinStartupComplete event handler of the AddinModule class:

if (folderEvents != null)
{
    folderEvents = new OutlookFoldersEventsClass(this);
    Outlook.NameSpace ns = OutlookApp.GetNamespace("MAPI");
    Outlook.MAPIFolder folderContacts = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderContacts);                        
    folderEvents.ConnectTo(folderContacts, true);
    if (ns != null) Marshal.ReleaseComObject(ns);
}

As with the Outlook Items event class we need to properly remove any connections when our add-in shuts down, so add the following to the AddinBeginShutdown event handler:

if (folderEvents != null)
{
    folderEvents.RemoveConnection();
    folderEvents.Dispose();
}

With all the necessary code added, we can have a look at the Folder events.

ProcessFolderAdd

This event occurs when a folder is added to the specified folder. A reference to the newly added folder is passed as a parameter.

public override void ProcessFolderAdd(object folder)
{
    if (folder != null)
    {
        Outlook.MAPIFolder newFolder = (Outlook.MAPIFolder)folder;
        Outlook.MAPIFolder parentFolder = (Outlook.MAPIFolder)this.FolderObj;

        MessageBox.Show(String.Format("You've added a sub folder called {0} to {1}", 
                        newFolder.Name, parentFolder.FolderPath));
    }
}

ProcessFolderChange

The ProcessFolderChange event is raised when a folder is changed. The changes include when a folder was renamed or when an item was added, renamed or removed from the folder. A reference to the changed folder is passed as a parameter.

public override void ProcessFolderChange(object folder)
{
    if (folder != null)
    {
        Outlook.MAPIFolder changedFolder = (Outlook.MAPIFolder)folder;
        Outlook.MAPIFolder parentFolder = (Outlook.MAPIFolder)this.FolderObj;

        MessageBox.Show(String.Format("The {0} folder in {1} has changed", 
            changedFolder.Name, parentFolder.FolderPath)); 
    }
}

ProcessFolderRemove

As the name of the event suggests, it is raised when a folder is removed from the specified folders collection. Unfortunately no reference to the folder is passed.

public override void ProcessFolderRemove()
{
    Outlook.MAPIFolder parentFolder = (Outlook.MAPIFolder)this.FolderObj;
    MessageBox.Show("A subfolder has been removed from " + parentFolder.FolderPath);
}

On MSDN you can read more about the Folders events.

Thank you for reading. Until next time, keep coding!

Available downloads:

This sample add-in was developed using Add-in Express for Office and .net:
C# sample add-in