Blog of Helmut Obertanner (en)

DotNetPro 07/2010: Going beyond the Outlook Object Model

Helmut Obertanner — Sat, 19 Jun 2010 10:39:44 GMT

In Issue 07/2010 of the DotNetPro magazin is an article that I wrote about going behind the Outlook Object Model and using the Windows API to implement an additional event that is missing in the Outlook Version 2003, but new in Outlook 2007. This event is called Inspector "PageChanged" and is fired when the user has selected another page in the Inspector Window. I find this useful and had a requirement for a customer to have this also available in Outlook 2003. So I hacked something together and published an article about it.

On this way I also want to say a big THANK YOU to the team of DotNetPro for supporting us at the Office Community Day 2010 at Microsoft/Unterschleißheim.

Helmut Obertanner

Microsoft releases updated Time Zone Data Update Tool for Microsoft Office Outlook

Helmut Obertanner — Fri, 04 Jun 2010 06:24:02 GMT

Outlook Time Zone Data Update Tool 3.0

This tool solves problems with DSTs and time zones by updating Microsoft Outlook calendar entries.
The knowledgebase article can be found here: http://support.microsoft.com/default.aspx?scid=kb;EN-US;931667

Affected Outlook versions: 2002 to 2010.
There is a 32-bit and a 64-bit version of this tool available, also there's an extra tool for updating Exchange servers.

32-bit Version: http://www.microsoft.com/downloads/details.aspx?familyid=%20E343A233-B9C8-4652-9DD8-AE0F1AF62568

64-bit Version: http://www.microsoft.com/downloads/details.aspx?FamilyID=4bf28882-789e-4a66-a56f-a3c3ef23e5a7

Knowledgebase article for updating Exchangeservers: http://support.microsoft.com/kb/941018/

Exchangeserver Version: http://www.microsoft.com/downloads/details.aspx?FamilyId=27BB0EE2-03AC-4E5B-AEC5-3E878490FCE1&displaylang=en

Windows7 tastes good!

Helmut Obertanner — Mon, 08 Mar 2010 09:09:00 GMT

More...

Outlook Personal Folders File Format specification available

Helmut Obertanner — Mon, 08 Mar 2010 07:57:23 GMT

Microsoft released documentation for the Outlook PST-File format.

You can download the documentation as PDF-Files from this site:
http://msdn.microsoft.com/en-us/library/ff385210.aspx

Enforcing business rules for Outlook Items

Helmut Obertanner — Tue, 29 Dec 2009 18:16:18 GMT

Recently I had a customer request helping forcing business rules when saving Outlook Contact Items. Luckily I programmed a sample on how to do this some time ago and published it on Outlookcode.com. While this sample was programmed using a shared Add-in I decided to give it a refresh and update this sample using VSTO.

Inspector Wrapper

It all begins with an Inspector Wrapper template. I blogged about it and you can read it here: http://www.outlooksharp.dehttp://www.outlooksharp.dehttp://www.outlooksharp.de/Home/tabid/36/EntryId/44/Outlook-Inspector-Wrapper-explained.aspx.

The base for this code sample is to handle each Outlook Item individually. When an Item is opened within Outlook it is monitored by the Inspector. With the Wrapper code it is easy to handle all the Inspectors gracefully. The Item behind the Inspector is exposed by the Inspector.CurrentItem property. In this scenario we are enforcing business rules for Contacts.
A ContactItem exposes some Events that can be used to implement a small Framework that checks if all rules are met before a contact form is closed, or when someone is going to save the contact. We need to monitor the write and the close events of all contact items. The write and the close events of the ContactItem have a Cancel Property that is passed by reference. When setting the Cancel property to true, the operation is interrupted. First create a new Outlook Add-in solution.

Picture 1: Create an Outlook Add-in

After creating the Add-in go on and implement the Inspector Wrapper code to handle all Items individually. The base class called InspectorWrapper.cs implements all Inspector events and handles them individually. If you want to handle ContactItems you need to derive a class of it and implement the code to handle ContactItems events and businesslogic here.
Below is the code for the InspectorWrapper base class:

///

/// Eventhandler used to correctly clean up resources

///

/// The unique id of the Inspector instance

internal delegate void InspectorWrapperClosedEventHandler(Guid id);

///

/// The base class for all InspectorWrappers

///

internal abstract class InspectorWrapper {

///

/// Event notifier for the InspectorWrapper.Closed event.

/// Is raised when an Inspector has been closed.

///

public event InspectorWrapperClosedEventHandler Closed;

///

/// The unique Id the identifies the Inspector Window

///

public Guid Id { get; private set; }

///

/// The Outlook Inspector Instance

///

public Outlook.Inspector Inspector { get; private set; }

///

/// .ctor

///

/// The Outlook Inspector instance that should be handled

public InspectorWrapper(Outlook.Inspector inspector) {

Id = Guid.NewGuid();

Inspector = inspector;

// register for Inspector events here

((Outlook.InspectorEvents_10_Event)Inspector).Close += new Outlook.InspectorEvents_10_CloseEventHandler(Inspector_Close);

((Outlook.InspectorEvents_10_Event)Inspector).Activate += new Outlook.InspectorEvents_10_ActivateEventHandler(Activate);

((Outlook.InspectorEvents_10_Event)Inspector).Deactivate += new Outlook.InspectorEvents_10_DeactivateEventHandler(Deactivate);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeMaximize += new Outlook.InspectorEvents_10_BeforeMaximizeEventHandler(BeforeMaximize);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeMinimize += new Outlook.InspectorEvents_10_BeforeMinimizeEventHandler(BeforeMinimize);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeMove += new Outlook.InspectorEvents_10_BeforeMoveEventHandler(BeforeMove);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeSize += new Outlook.InspectorEvents_10_BeforeSizeEventHandler(BeforeSize);

// Only Outlook 2007((Outlook.InspectorEvents_10_Event)Inspector).PageChange += new Outlook.InspectorEvents_10_PageChangeEventHandler(PageChange);

// Initialize is called to give the derived Wrappers a chance to do initialization

Initialize();

}

///

/// Eventhandler for the Inspector close event

///

private void Inspector_Close() {

// call the Close Method - the derived classes can implement cleanup code

// by overriding the Close method

Close();

// unregister Inspector events

((Outlook.InspectorEvents_10_Event)Inspector).Close -= new Outlook.InspectorEvents_10_CloseEventHandler(Inspector_Close);

((Outlook.InspectorEvents_10_Event)Inspector).Activate -= new Outlook.InspectorEvents_10_ActivateEventHandler(Activate);

((Outlook.InspectorEvents_10_Event)Inspector).Deactivate -= new Outlook.InspectorEvents_10_DeactivateEventHandler(Deactivate);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeMaximize -= new Outlook.InspectorEvents_10_BeforeMaximizeEventHandler(BeforeMaximize);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeMinimize -= new Outlook.InspectorEvents_10_BeforeMinimizeEventHandler(BeforeMinimize);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeMove -= new Outlook.InspectorEvents_10_BeforeMoveEventHandler(BeforeMove);

((Outlook.InspectorEvents_10_Event)Inspector).BeforeSize -= new Outlook.InspectorEvents_10_BeforeSizeEventHandler(BeforeSize);

// Only Outlook 2007((Outlook.InspectorEvents_10_Event)Inspector).PageChange -= new Outlook.InspectorEvents_10_PageChangeEventHandler(PageChange);

// clean up resources and do a GC.Collect();

Inspector = null;

GC.Collect();

GC.WaitForPendingFinalizers();

// raise the Close event.

if (Closed != null) Closed(Id);

}

///

/// Method is called after the internal initialization of the Wrapper

///

protected virtual void Initialize() { }

///

/// Method gets called when another Page of the Inspector has been selected

///

/// The active page name by reference

protected virtual void PageChange(ref string ActivePageName) { }

///

/// Method gets called before the Inspector is resized

///

/// To prevent resizing set Cancel to true

protected virtual void BeforeSize(ref bool Cancel) { }

///

/// Method gets called before the Inspector is moved around

///

/// To prevent moving set Cancel to true

protected virtual void BeforeMove(ref bool Cancel) { }

///

/// Method gets called before the Inspector is minimized

///

/// To prevent minimizing set Cancel to true

protected virtual void BeforeMinimize(ref bool Cancel) { }

///

/// Method gets called before the Inspector is maximized

///

/// To prevent maximizing set Cancel to true

protected virtual void BeforeMaximize(ref bool Cancel) { }

///

/// Method gets called when the Inspector is deactivated

///

protected virtual void Deactivate() { }

///

/// Method gets called when the Inspector is activated

///

protected virtual void Activate() { }

///

/// Derived classes can do a cleanup by overriding this method.

///

protected virtual void Close() { }

///

/// This Fabric method returns a specific InspectorWrapper or null if not handled.

///

/// The Outlook Inspector instance

/// Returns the specific Wrapper or null

public static InspectorWrapper GetWrapperFor(Outlook.Inspector inspector) {

// retrieve the message class using late binding

string messageClass = (string)inspector.CurrentItem.GetType().InvokeMember("MessageClass", BindingFlags.GetProperty, null, inspector.CurrentItem, null);

// depending on a messageclass you can instantiate different Wrappers

// explicitely for a given MessageClass

// using a switch statement

switch (messageClass) {

case "IPM.Contact":

return new ContactItemWrapper(inspector);

case "IPM.Journal":

return new ContactItemWrapper(inspector);

case "IPM.Note":

return new MailItemWrapper(inspector);

case "IPM.Post":

return new PostItemWrapper(inspector);

case "IPM.Task":

return new TaskItemWrapper(inspector);

}

// or check if the messageclass begins with a specific fragment

//if (messageClass.StartsWith ("IPM.Contact.XXXX")){

// return new CustomItemWrapper(inspector);

//}

// or check the interface type of the Item

if (inspector.CurrentItem is Outlook.AppointmentItem) {

return new AppointmentItemWrapper(inspector);

}

// or check the interface type of the Item

if (inspector.CurrentItem is Outlook.ContactItem) {

return new ContactItemWrapper(inspector);

}

// no wrapper found

return null;

}

Next you can see the ContactItemWrapper class. It is derived of the InspectorWrapper and used to handle all contacts in your application. Nothing fancy. How can you enforce business rules there? If you study the code you can see that in the Initialize method we register for the open, write and close events of the ContactItem. In C# the close event needs a special syntax, because there's already a close method for the ContactItem. To register for the event you need to cast directly to the ItemEvents_10_Event interface. After registering the events a method SetupBusinessRules is called. We discuss this in detail later – here is the code of the ContactItemWrapper class.

internal class ContactItemWrapper : InspectorWrapper {

///

/// .ctor

///

/// The Outlook Inspector instance that should be handled

public ContactItemWrapper(Outlook.Inspector inspector)

: base(inspector) {

}

///

/// The Object instance behind the Inspector (CurrentItem)

///

public Outlook.ContactItem Item { get; private set; }

///

/// Method is called when the Wrapper has been initialized

///

protected override void Initialize() {

// Get the Item of the current Inspector

Item = (Outlook.ContactItem)Inspector.CurrentItem;

// Register for the Item events

Item.Open += new Outlook.ItemEvents_10_OpenEventHandler(Item_Open);

Item.Write += new Outlook.ItemEvents_10_WriteEventHandler(Item_Write);

((Outlook.ItemEvents_10_Event)Item).Close += new Microsoft.Office.Interop.Outlook.ItemEvents_10_CloseEventHandler(Item_Close);

SetupBusinessRules();

}

///

/// This Method is called when the Item is going to be closed

///

void Item_Close(ref bool Cancel) {

if (!Item.Saved) {

Cancel = !Validate();

}

///

/// This Method is called when the Item is saved.

///

/// When set to true, the save operation is cancelled

void Item_Write(ref bool Cancel) {

if (!Item.Saved) {

Cancel = !Validate();

}

///

/// This Method is called when the Item is visible and the UI is initialized.

///

/// When you set this property to true, the Inspector is closed.

void Item_Open(ref bool Cancel) {

//TODO: Implement something

}

///

/// The Close Method is called when the Inspector has been closed.

/// Do your cleanup tasks here.

/// The UI is gone, can't access it here.

///

protected override void Close() {

// unregister events

Item.Write -= new Outlook.ItemEvents_10_WriteEventHandler(Item_Write);

Item.Open -= new Outlook.ItemEvents_10_OpenEventHandler(Item_Open);

((Outlook.ItemEvents_10_Event)Item).Close -= new Microsoft.Office.Interop.Outlook.ItemEvents_10_CloseEventHandler(Item_Close);

_BusinessRules.Clear();

_BusinessRules = null;

// required, just stting to NULL may keep a reference in memory of the Garbage Collector.

Item = null;

GC.Collect();

GC.WaitForPendingFinalizers();

}

#region business rule check methods

List<X4UBusinessRule> _BusinessRules = new List<X4UBusinessRule>();

private void SetupBusinessRules() {

_BusinessRules.Add(new X4UBusinessRule("LastNameUppercase", "The Office Location is required and must be Uppercase.", this.BusinessRuleCheck_OfficeLocationRequiredAndUppercase));

_BusinessRules.Add(new X4UBusinessRule("CompanyName3Letters", "The Company Name must have a minimum length of 3.", this.BusinessRuleCheck_CompanyNameMinimum3Letters));

}

public bool Validate() {

// if every business rule is valid we return true

if (_BusinessRules.TrueForAll(X4UBusinessRule.IsRuleValid)) return true;

// no ?

// show a warning to the user and

StringBuilder message = new StringBuilder(500);

message.AppendLine("You can't save this Item, because the following requirements are not met:");

foreach (X4UBusinessRule rule in _BusinessRules) {

if (!rule.IsValid()) message.AppendLine(rule.Description);

}

// display a message to the user what's wrong.

MessageBox.Show (new OutlookWin32Window(Inspector), message.ToString());

return false;

}

public bool BusinessRuleCheck_OfficeLocationRequiredAndUppercase() {

return (!string.IsNullOrEmpty (Item.OfficeLocation) && Item.OfficeLocation == Item.OfficeLocation.ToUpper());

}

public bool BusinessRuleCheck_CompanyNameMinimum3Letters() {

return (Item.CompanyName != null && Item.CompanyName.Length > 2);

}

#endregion

}

Defining the business rules

First a class is defined that should describe a business rule. It has a name for identification and a description that should be displayed to the user if the rule is not validated successfully. It also has a pointer to a function that checks the business rule and returns true if it's valid. The Signature of such a rule check method is defined as a delegate.

///

/// Delegate declares the Method signature that checks the BusinessRule and returns true or false

///

/// True if the rule is ok

public delegate bool BusinessRuleCheckMethod();

In the constructor of the business rule you setup the name and description and the pointer to that method that validates the rule. There's another static method IsRuleValid that just call the function and returns the result. It is defined as you can see next.

///

/// This class defines a business rule

///

public class X4UBusinessRule {

///

/// The Name of the business rule

///

public string Name { get; private set; }

///

/// A description displayed to the user if the rule is not met

///

public string Description { get; private set; }

///

/// A function pointer that points to the method that checks if the business rule is valid

///

public BusinessRuleCheckMethod IsValid { get; private set; }

///

/// .ctor

///

/// The name

/// The description

/// Function pointer to the validation method

public X4UBusinessRule(string name, string description, BusinessRuleCheckMethod ruleValidator) {

IsValid = ruleValidator;

Name = name;

Description = description;

}

///

/// This method executes the method that the rule points to and returns the result

///

/// The businesrule to check

/// True if the rule is valid

public static bool IsRuleValid(X4UBusinessRule rule) {

return rule.IsValid();

}

Next we take a look on setting up the rule check in the ContactItemWrapper class. Just for reference there are two business rule check methods defined as you can see here:

public bool BusinessRuleCheck_OfficeLocationRequiredAndUppercase() {

return (!string.IsNullOrEmpty (Item.OfficeLocation) && Item.OfficeLocation == Item.OfficeLocation.ToUpper());

}

public bool BusinessRuleCheck_CompanyNameMinimum3Letters() {

return (Item.CompanyName != null && Item.CompanyName.Length > 2);

}

The first method checks if the OfficeLocation property of the Item is not empty and uppercase. The second checks if the minimum length of the CompanyName property is 3 letters. You can define any kind of check – just make sure you return true when the rule is validated successfully.

Validation

How and when are the rules validated? For that we define a Validate method that is called in the write and close events.
The rules are stored in a list and so we can use the TrueForAll statement to check all rules at once. If one of the rules fails, we display a message to the user and return the cause of the mistake. Here is the Validate method.

public bool Validate() {

// if every business rule is valid we return true

if (_BusinessRules.TrueForAll(X4UBusinessRule.IsRuleValid)) return true;

// no ?

// show a warning to the user and

StringBuilder message = new StringBuilder(500);

message.AppendLine("You can't save this Item, because the following requirements are not met:");

foreach (X4UBusinessRule rule in _BusinessRules) {

if (!rule.IsValid()) message.AppendLine(rule.Description);

}

// display a message to the user what's wrong.

MessageBox.Show (new OutlookWin32Window(Inspector), message.ToString());

return false;

}

This is easy to implement. The Validate method is executed in the Item.Write and in the Item.Close event. You can see that in this method the Saved state of the Item is checked. When the Item isn't modified there's no need for a rule check. If the Validate method returns false, the write or close operation is canceled. The event handlers are defined as you can see here:

///

/// This Method is called when the Item is going to be closed

///

void Item_Close(ref bool Cancel) {

if (!Item.Saved) {

Cancel = !Validate();

}

///

/// This Method is called when the Item is saved.

///

/// When set to true, the save operation is cancelled

void Item_Write(ref bool Cancel) {

if (!Item.Saved) {

Cancel = !Validate();

}

How to setup the business rule with function pointers? This is done using a single line of code.
Just add a new Instance of a BusinessRule class to the list and pass the name, description and the method as parameters to the constructor.

List<X4UBusinessRule> _BusinessRules = new List<X4UBusinessRule>();

private void SetupBusinessRules() {

_BusinessRules.Add(new X4UBusinessRule("OfficeLocationRequiredAndUppercase", "The Office Location is required and must be uppercase.", this.BusinessRuleCheck_OfficeLocationRequiredAndUppercase));

_BusinessRules.Add(new X4UBusinessRule("CompanyName3Letters", "The Company Name must have a minimum length of 3.", this.BusinessRuleCheck_CompanyNameMinimum3Letters));

}

The code is executed whenever you modify or create a contact form and you try to save or close the form. When a rule is not valid, a MessageBox is displayed to the user as you can see in the screenshot.

Picture 2: MessageBox showing that business rules are not valid

Sample code

You can download the code sample for this solution here:
Visual Studio 2010

References

Outlook Inspector Object: http://msdn.microsoft.com/en-us/library/bb176679.aspx
Outlook ContactItem Object: http://msdn.microsoft.com/en-us/library/bb176651.aspx
InspectorWrapper: http://www.outlooksharp.dehttp://www.outlooksharp.dehttp://www.outlooksharp.de/Home/tabid/36/EntryId/44/Outlook-Inspector-Wrapper-explained.aspx

Recursively Iterating Outlook Folders

Helmut Obertanner — Fri, 25 Dec 2009 21:01:14 GMT

In this small how-to we discuss different methods for iterating Outlook Folders and its subfolders.

In the Outlook Object Model (OOM) a folder is represented by a type called MAPIFolder.
There are different ways to retrieve a MAPIFolder instance:

Using the Session.GetDefaultFolder(OlDefaultFolders) method to retrieve predefined folders like Inbox
Using the Session.GetFolderById(folderId, [optional] storeId) method to retrieve a Folder by its EntryId
Retrieving the Parent Property of an Item or another Folder
Retrieving the Explorer.CurrentFolder Property
Iterate over the Folders collection of a Store or a Folder instance.
By creating a new Folder

Recursively iterating a folder tree and accessing Outlook Items can be a long running process. It depends on the amount of Items in a Folder and the levels of subfolders. When programming against the Outlook Object Model using .Net(managed) code you need to take care about memory management and how to use the COM Objects. Accessing and retrieving Outlook Objects like Emails, Appointments and Tasks could be very slow. This is by design and caused by the MAPI level where the Outlook Object Model is built on top. It also depends on the configuration, if you are using an Exchangeserver, if you are working connected(online) or offline and how fast the network connection is.

RPC Connections problem

This problem occures only if you are connected to an Exchangeserver and when you access multiple Outlook Items in a short time. For each Item that you access by code, a connection (Remote Procedure Call) is made to the server and the item is retrieved or synchronized. By default the size of RPC-connections made to an Exchangeserver by one Client is limited to 256. If an Outlook solution is developed offline – or just with a few amount of test data – the developer may never run into this problem. When the solution is deployed to the customer and under heavy load you may get unexpected behavior. So whenever you iterate over Outlook Items you need to take care of this problem. First we simply iterate over Outlook Items in the Inbox. Let's discuss different possibilities. For testing purposes we define a method to get the Inbox Folder Object.

Outlook.MAPIFolder GetInboxFolder() {

return Globals.ThisAddIn.Application.Session.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox);

}

The first test iterates over the Inbox folder Items and traces the Subject of the Item.

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

// Iterate over all Inbox items and get the Subject

foreach (object item in inboxFolder.Items) {

Trace.WriteLine (item.GetType ().InvokeMember ("Subject", BindingFlags.GetProperty, null, item, null));

}

What's wrong with this code? Theoretically this code is OK, but
- when there are more Items then available RPC-Connections?
- an Outlook Items collection can change the number of items?
- the process can't be interrupted until you iterated over all items
- the process is running in the main thread of the Outlook process – this means that the GUI is not responsible until the method has finished.

How can you solve it?

First we avoid the RPC-connections problem. We will define a variable that counts the processed items. While iterating over the folder content we increase the count of it and after a predefined value we force the .Net garbage collector to release the references from memory. The problem is: The .Net Garbage Collector is intelligent. It caches the data you accessed for a while – so if you access the same item again within a specific time you get this object again very fast. This is also true for Outlook Objects. When you access an Object a reference is kept in memory - even when you set this object to null by code. The GC decides when to finally release an object. Alternatively you can force the GC to do a Cleanup. Note: A GC cleanup is very expensive by consuming CPU load and some time – GC often will slow down all Applications – so you need to find a good mix. It is absolutely a must to do a GC cleanup after using and releasing an Inspector or an Explorer object.
Study the next snippet.

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

int watchDog = 0;

// Iterate over all Inbox items and get the Subject

foreach (object item in inboxFolder.Items) {

Trace.WriteLine (item.GetType ().InvokeMember ("Subject", BindingFlags.GetProperty, null, item, null));

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

The watchdog variable is used to force the Garbagecollector to release the COM objects from memory and close the RPC connections.
Note that the Folder.Items collection is not static – it can change its content at any time. Instead of iterating over the Items collection using the foreach statement, consider getting the collection count and process the items using a countdown loop.

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

int watchDog = 0;

// Iterate over all Inbox items and get the Subject

for (int index = inboxFolder.Items.Count; index > 0; index-- ) {

object item = inboxFolder.Items[index];

Trace.WriteLine(item.GetType().InvokeMember("Subject", BindingFlags.GetProperty, null, item, null));

item = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

The index variable is used for iterating over a number of items from last to first. This way you can delete or move items while iterating the collection. The iteration process still cannot be interrupted, because the process runs in the main thread of Outlook. To turn this into a stoppable and responsive iteration process, you need to use a thread for it. In the .Net Framework there is already a Framework that you can use called BackgroundWorker.
Check out the next code snippet.

BackgroundWorker _worker;

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

// Setup the background thread

_worker = new BackgroundWorker();

_worker.DoWork += new DoWorkEventHandler(_worker_DoWork);

_worker.WorkerSupportsCancellation = true;

_worker.RunWorkerAsync();

}

void _worker_DoWork(object sender, DoWorkEventArgs e) {

BackgroundWorker worker = (BackgroundWorker)sender;

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

int watchDog = 0;

// Iterate over all Inbox items and get the Subject

for (int index = inboxFolder.Items.Count; index > 0; index--) {

// if someone interrupts the worker exit here

if (worker.CancellationPending) break;

object item = inboxFolder.Items[index];

Trace.WriteLine(item.GetType().InvokeMember("Subject", BindingFlags.GetProperty, null, item, null));

item = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

private void ThisAddIn_Shutdown(object sender, System.EventArgs e)

{

if (_worker.IsBusy) {

_worker.CancelAsync();

}

Using a BackgroundWorker you can execute a long running process in a separate thread. The UI keeps responsive and you can interrupt the operation.

Recursive Operations

Next we are going to iterate recursively over a folder tree. We implement a function that calls itself recursively.

void IterateFolder(Outlook.MAPIFolder folder) {

int watchDog = 0;

// Iterate over all Inbox items and get the Subject

for (int index = folder.Items.Count; index > 0; index--) {

object item = folder.Items[index];

Trace.WriteLine(item.GetType().InvokeMember("Subject", BindingFlags.GetProperty, null, item, null));

item = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

for (int index = folder.Folders.Count; index > 0; index--) {

Outlook.MAPIFolder subFolder = folder.Folders[index];

// Call this function recursively

IterateFolder(subFolder);

subFolder = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

While this is working – it's not the best approach. Calling recursive functions can mess up the processor call stack. How can we solve this?
One easy solution is to use a Queue Object that is already part of the .Net Framework. A Queue has two essentials Methods called Enqueue() and Dequeue().
The Enqueue inserts an object at the end while Dequeue removes the first object of a Queue. In this scenario EntryID's of the folders that needs to be iterated recursively are stored in a queue. In the worker method the number of items in the queue is checked and if there is an item in the queue, it is processed. The EntryID of the folder is removed of the Queue and the folder is processed. While processing, each of the subfolders EntryID is added to the end of the Queue. This way there is no problem with the stack of the program and the process can be interrupted at any time.

BackgroundWorker _worker;

Queue<string> _folderIdsToProcess;

private void ThisAddIn_Startup(object sender, System.EventArgs e) {

_folderIdsToProcess = new Queue<string>();

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

// and add it to the queue

_folderIdsToProcess.Enqueue(inboxFolder.EntryID);

// Setup the background thread

_worker = new BackgroundWorker();

_worker.DoWork += new DoWorkEventHandler(_worker_DoWork);

_worker.WorkerSupportsCancellation = true;

_worker.RunWorkerAsync();

}

void _worker_DoWork(object sender, DoWorkEventArgs e) {

BackgroundWorker worker = (BackgroundWorker)sender;

Outlook.MAPIFolder folder;

int watchDog = 0;

while (_folderIdsToProcess.Count > 0 && !worker.CancellationPending) {

// pick one folder

string entryId = _folderIdsToProcess.Dequeue();

folder = Globals.ThisAddIn.Application.Session.GetFolderFromID(entryId, Type.Missing);

// Iterate over all Inbox items and get the Subject

for (int index = folder.Items.Count; index > 0; index--) {

if (worker.CancellationPending) break;

object item = folder.Items [index];

Trace.WriteLine(item.GetType().InvokeMember("Subject", BindingFlags.GetProperty, null, item, null));

item = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

for (int index = folder.Folders.Count; index > 0; index--) {

if (worker.CancellationPending) break;

Outlook.MAPIFolder subFolder = folder.Folders[index];

// Call this function recursively

_folderIdsToProcess.Enqueue(subFolder.EntryID);

subFolder = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

folder = null;

}

private void ThisAddIn_Shutdown(object sender, System.EventArgs e) {

if (_worker.IsBusy) {

_worker.CancelAsync();

}

There is no problem accessing the queue variable by different threads because the Queue is modified only by the worker thread.

Making things go faster

You may notice that iterating over a large number of Items costs a lot of time. There are a few Options that may help you to optimize your application. The first option is to use a Filter to restrict the number of items in a folder. Let's say you want to search for Items that are modified after a specific time.

BackgroundWorker _worker;

Queue<string> _folderIdsToProcess;

private void ThisAddIn_Startup(object sender, System.EventArgs e) {

_folderIdsToProcess = new Queue<string>();

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

// and add it to the queue

_folderIdsToProcess.Enqueue(inboxFolder.EntryID);

// build a filter

// note that this filter is build a little bit complicated

// This works even if you are using an Outlook even with another language format, not only en-us

DateTime from = DateTime.Now.AddMonths(-1);

DateTime to = DateTime.Now;

string filter = string.Format("[LastModificationTime] > '{0}/{1}/{2}' AND [LastModificationTime] <='{3}/{4}/{5}'"

, from.Year, from.Month, from.Day

, to.Year, to.Month, to.Day);

// Setup the background thread

_worker = new BackgroundWorker();

_worker.DoWork += new DoWorkEventHandler(_worker_DoWork);

_worker.WorkerSupportsCancellation = true;

_worker.RunWorkerAsync(filter);

}

void _worker_DoWork(object sender, DoWorkEventArgs e) {

BackgroundWorker worker = (BackgroundWorker)sender;

string filter = (string)e.Argument;

Outlook.MAPIFolder folder;

int watchDog = 0;

while (_folderIdsToProcess.Count > 0 && !worker.CancellationPending) {

// pick one folder

string entryId = _folderIdsToProcess.Dequeue();

folder = Globals.ThisAddIn.Application.Session.GetFolderFromID(entryId, Type.Missing);

Outlook.Items items = folder.Items.Restrict(filter);

// Iterate over all Inbox items and get the Subject

for (int index = items.Count; index > 0; index--) {

if (worker.CancellationPending) break;

object item = items[index];

Trace.WriteLine(item.GetType().InvokeMember("Subject", BindingFlags.GetProperty, null, item, null));

item = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

for (int index = folder.Folders.Count; index > 0; index--) {

if (worker.CancellationPending) break;

Outlook.MAPIFolder subFolder = folder.Folders[index];

// Call this function recursively

_folderIdsToProcess.Enqueue(subFolder.EntryID);

subFolder = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

items = null;

folder = null;

}

private void ThisAddIn_Shutdown(object sender, System.EventArgs e) {

if (_worker.IsBusy) {

_worker.CancelAsync();

}

Note that you cannot use every property to restrict the number of items in a folder.

The Table Object

Starting from Outlook 2007 there is a new Table object in the OOM that provides a fast access to the Folder table. It's fast because you can decide on what columns you want to retrieve on each row. You may get the best performance if you need just information that can be retrieved directly as column in the row of a table. In the code above we used only the properties LastModificationTime and Subject. Let's see if we can speed things a little bit. To measure success, the code is slightly modified to count the number of items processed and the duration of the whole process. The Test using Outlook items has the following result:

Processing 773 items took 11262ms

After modifying the code to use a table object instead, the test read the following values:

Processing 773 items took 15162ms

Funny. All of my tests using Outlook2010 showing that using the Folder.Table object is slower than iterating over the Outlook Items. Theoretically using GetTable() should be much faster than iterating over an Outlook Item collection. But it isn't.

Here is the code:

BackgroundWorker _worker;

Queue<string> _folderIdsToProcess;

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

_folderIdsToProcess = new Queue<string>();

// Get the Inbox folder

Outlook.MAPIFolder inboxFolder = GetInboxFolder();

// and add it to the queue

_folderIdsToProcess.Enqueue(inboxFolder.EntryID);

// build a filter

DateTime from = DateTime.Now.AddMonths(-6);

DateTime to = DateTime.Now;

string filter = string.Format("[LastModificationTime] > '{0}/{1}/{2}' AND [LastModificationTime] <='{3}/{4}/{5}'"

, from.Year, from.Month, from.Day

, to.Year, to.Month, to.Day);

// Setup the background thread

_worker = new BackgroundWorker();

_worker.DoWork += new DoWorkEventHandler(_worker_DoWork);

_worker.WorkerSupportsCancellation = true;

_worker.RunWorkerAsync(filter);

}

void _worker_DoWork(object sender, DoWorkEventArgs e) {

BackgroundWorker worker = (BackgroundWorker)sender;

string filter = (string)e.Argument;

Outlook.MAPIFolder folder;

int itemsProcessed = 0;

Stopwatch watch = new Stopwatch();

watch.Start();

int watchDog = 0;

while (_folderIdsToProcess.Count > 0 && !worker.CancellationPending) {

// pick one folder

string entryId = _folderIdsToProcess.Dequeue();

folder = Globals.ThisAddIn.Application.Session.GetFolderFromID(entryId, Type.Missing);

Outlook.Table table = folder.GetTable(filter, Outlook.OlTableContents.olUserItems);

// try to get the first row

Outlook.Row row = table.GetNextRow ();

// Iterate over all Inbox items and get the Subject

while (!table.EndOfTable ) {

if (worker.CancellationPending) break;

string subject = (string) row["Subject"];

Trace.WriteLine(subject);

itemsProcessed++;

row = table.GetNextRow();

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

for (int index = folder.Folders.Count; index > 0; index--) {

if (worker.CancellationPending) break;

Outlook.MAPIFolder subFolder = folder.Folders[index];

// Call this function recursively

_folderIdsToProcess.Enqueue(subFolder.EntryID);

subFolder = null;

// Ensures that not too many RPC connections are made to a Server

watchDog++;

if (watchDog > 100) {

watchDog = 0;

GC.Collect();

GC.WaitForPendingFinalizers();

}

table = null;

folder = null;

}

Trace.WriteLine(string.Format("Processing {0} items took {1}ms", itemsProcessed, watch.ElapsedMilliseconds));

}

private void ThisAddIn_Shutdown(object sender, System.EventArgs e)

{

if (_worker.IsBusy) {

_worker.CancelAsync();

}

The next enhancement would be to use two threads that work together. One thread enumerates all folders and adds the items into a Queue, a second thread processes all the Items.

Avoiding to collect the GC

While this is necessary to cleanly release COM objects – forcing the GC can be time consuming and affects all running .Net programs. In the loop we are calling the function to avoid a specific problem when connected online to Exchange. If Outlook is offline there's no need for the workaround.

Here is the optimized code:

private void IncreaseWatchdogAndCallGCIfOnline(ref int watchDog) {

watchDog++;

if (watchDog > 100) {

Outlook.OlExchangeConnectionMode mode = Globals.ThisAddIn.Application.Session.ExchangeConnectionMode;

if (mode == Outlook.OlExchangeConnectionMode.olCachedConnectedDrizzle

|| mode == Outlook.OlExchangeConnectionMode.olCachedConnectedFull

|| mode == Outlook.OlExchangeConnectionMode.olCachedConnectedHeaders

|| mode == Outlook.OlExchangeConnectionMode.olOnline) {

// Ensures that not too many RPC connections are made to a Server

GC.Collect();

GC.WaitForPendingFinalizers();

}

watchDog = 0;

}

References

Outlook Folder Object: http://msdn.microsoft.com/en-us/library/bb176362.aspx
Outlook Table Object: http://msdn.microsoft.com/en-us/library/bb176406.aspx
.Net Queue Object: http://msdn.microsoft.com/en-us/library/7977ey2c.aspx

New developer content for Office 2010(Beta) available

Helmut Obertanner — Thu, 12 Nov 2009 18:48:07 GMT

Today the Outlook team has posted new developer content for Office2010(Beta version) on MSDN. Enjoy!

http://msdn.microsoft.com/en-us/library/ee692176(office.14).aspx

Here you can see what's new for Outlook developers:

http://msdn.microsoft.com/en-us/library/ee692174(office.14).aspx

A Haunted House Control Unit – Talk to USB from C#

Helmut Obertanner — Sun, 08 Nov 2009 19:08:08 GMT

More...

Outlook Inspector Wrapper explained

Helmut Obertanner — Sun, 01 Nov 2009 20:54:58 GMT

More...

All-In-One Code Framework

Helmut Obertanner — Wed, 09 Sep 2009 06:48:16 GMT

Found this Project on Codeplex.

All-In-One Code Framework code-name CodeFx delineates the framework and skeleton of most Microsoft development techniques (e.g. COM, Data Access, IPC) using typical sample codes in different programming languages (e.g. Visual C#, VB.NET, Visual C++).

The target of the project is to sketch the skeleton of most Microsoft development techniques using typical sample codes that are frequently-asked, tested or used.