Working with Outlook Objects

Working with the Application Object

This chapter examines some of the major objects in the Outlook object model, starting with the Application object. Many of the objects in the Outlook object model are very large, and it is beyond the scope of this book to completely describe these objects. Instead, this chapter focuses on the most commonly used methods and properties associated with these objects.

The Application object is the root object in the Outlook object model hierarchy, meaning that you can access all the other objects in the object model by starting at the Application object and accessing its properties and methods and the properties and methods of objects it returns.

A companion object to the Application object is the NameSpace object, which is retrieved by using the Application object's Session property. Some confusion can arise because functionality that you would expect to be on the Application object is often found on the NameSpace object. For example, the way to get to the root folders that are open in Outlook is through the NameSpace object's Folders property. The Application object has no Folders property.

Methods and Properties That Return Active or Selected Objects

The Application object has a number of methods and properties that return active objectsobjects representing things that are active or selected within Outlook. Table 11-1 shows some of these properties and methods.

Properties That Return Important Collections

The Application object has a number of properties that return collections that you will frequently use. Table 11-2 shows several of these properties. Listing 11-1 shows some code from a VSTO Outlook add-in that works with the active object methods and properties shown in Table 11-1 and the collections shown in Table 11-2.

Listing 11-1. A VSTO Add-In That Works with Active Objects and Collections

private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.Explorer activeExplorer = this.ActiveExplorer(); if (activeExplorer != null) { MessageBox.Show(String.Format( "The active explorer is {0}.", activeExplorer.Caption)); } Outlook.Inspector activeInspector = this.ActiveInspector(); if (activeInspector != null) { MessageBox.Show(String.Format( "The Active Inspector is {0}.", activeInspector.Caption)); } object activeWindow = this.ActiveWindow(); if (activeWindow != null) { Outlook.Explorer explorer = activeWindow as Outlook.Explorer; Outlook.Inspector inspector = activeWindow as Outlook.Inspector; if (explorer != null) { MessageBox.Show(String.Format( "The active window is an Explorer: {0}.", explorer.Caption)); } else if (inspector != null) { MessageBox.Show(String.Format( "The active window is an Inspector: {0}.", inspector.Caption)); } } else { MessageBox.Show("No Outlook windows are open"); } Outlook.NameSpace ns = this.Session; MessageBox.Show(String.Format( "There are {0} root folders.", ns.Folders.Count)); MessageBox.Show(String.Format( "There are {0} explorer windows.", this.Explorers.Count)); foreach (Outlook.Explorer explorer in this.Explorers) { MessageBox.Show(explorer.Caption); } MessageBox.Show(String.Format( "There are {0} inspector windows.", this.Inspectors.Count)); foreach (Outlook.Inspector inspector in this.Inspectors) { MessageBox.Show(inspector.Caption); } MessageBox.Show(String.Format( "There are {0} reminders.", this.Reminders.Count)); System.Text.StringBuilder reminders = new System.Text.StringBuilder(); foreach (Outlook.Reminder reminder in this.Reminders) { reminders.AppendLine(reminder.Caption); } MessageBox.Show(reminders.ToString()); }

Performing a Search and Creating a Search Folder

Outlook provides an AdvancedSearch method on the Application object that allows you to perform a search in Outlook. The AdvancedSearch method works asynchronously and raises the AdvancedSearchComplete event when the search has completed. You can also save a search you perform using the AdvancedSearch method as an Outlook Search folder. AdvancedSearch takes four parameters, as shown in Table 11-3.

We now consider how to construct the filter string that was mentioned in Table 11-3. The easiest way to do this is to let Outlook's built-in UI for constructing filters build the string for you. To do this, first select the folder you want to search. From the Arrange By menu in the View menu, choose Custom to display the Customize View dialog (see Figure 11-1).

Figure 11-1. The Customize View dialog.

Click the Filter button to display the Filter dialog. You can use this dialog to create the filter you want. In Figure 11-2, we have simply set the filter to show messages where the word review is in the subject field.

Figure 11-2. The Filter dialog.

After you have edited the filter to yield the results you want, click the SQL tab shown in Figure 11-3. Check the Edit these criteria directly check box. Doing so enables you to select the filter string and copy and paste it into your code. After you have copied the filter string onto the clipboard, you can cancel out of the Filter Dialog and the Customize View dialog.

Figure 11-3. The SQL tab of the Filter dialog displays a filter string.

Finally, paste the filter string into your code. You will want to use C#'s @ operator to preface the string, and you also need to expand all quotation marks to be double quotation marks. For our example, the C# code would look like this:

string filter = @"""urn:schemas:httpmail:subject"" LIKE '%review%'";

Listing 11-2 shows a complete example of using AdvancedSearch. Note that because the search proceeds asynchronously, we must handle the AdvancedSearchComplete event to determine when the search is finished. We also save the completed search as a search folder by calling Save on the completed Search object.

Listing 11-2. A VSTO Add-In That Uses the AdvancedSearch Method

public partial class ThisApplication { const string searchTag = "'review' Search In Inbox"; private void ThisApplication_Startup(object sender, EventArgs e) { this.AdvancedSearchComplete += new Outlook.ApplicationEvents_11_AdvancedSearchCompleteEventHandler( ThisApplication_AdvancedSearchComplete); this.AdvancedSearchStopped += new Outlook.ApplicationEvents_11_AdvancedSearchStoppedEventHandler( ThisApplication_AdvancedSearchStopped); string scope = @"'Inbox'"; string filter = @"""urn:schemas:httpmail:subject"" LIKE '%review%'"; bool searchSubfolders = true; try { MessageBox.Show("Starting search"); this.AdvancedSearch(scope, filter, searchSubfolders, searchTag); } catch (Exception ex) { MessageBox.Show(ex.Message); } } void ThisApplication_AdvancedSearchStopped( Outlook.Search searchObject) { if (searchObject.Tag == searchTag) { MessageBox.Show(String.Format( "Search completed. Found {0} results.", searchObject.Results.Count)); // Save this search as a search folder searchObject.Save(searchTag); } } void ThisApplication_AdvancedSearchComplete( Outlook.Search searchObject) { if (searchObject.Tag == searchTag) { MessageBox.Show(String.Format( "Search was stopped. Found {0} results.", searchObject.Results.Count)); } } #region VSTO Designer generated code private void InternalStartup() { this.Startup += new System.EventHandler(ThisApplication_Startup); } #endregion }

Copying a File into an Outlook Folder

Outlook provides a method to copy an existing document such as a spreadsheet on your desktop to an Outlook folder. The Application object's CopyFile method takes as a parameter a FilePath as a string, which is the full path to the document you want to copy into the Outlook folder. It also takes a DestFolderPath parameter, which is the name of the Outlook folder you want to copy the document to. Listing 11-3 shows an example of using CopyFile to put a spreadsheet called mydoc.xls into the Inbox and a second spreadsheet called mydoc2.xls into a folder called Reviews nested within a folder called Reference.

Listing 11-3. A VSTO Add-In That Uses the CopyFile Method

private void ThisApplication_Startup(object sender, EventArgs e) { this.CopyFile(@"c:mydoc.xls", "Inbox"); this.CopyFile(@"c:mydoc2.xls", @"ReferenceReviews"); }

Quitting Outlook

The Quit method can be used to exit Outlook. If any unsaved Outlook items are opened, Outlook prompts the user to save each unsaved Outlook item. When users are prompted to save, they get a dialog box that gives them a Cancel button. If the user clicks Cancel, Outlook does not quit.