Working with the NameSpace Object

A companion object to the Application object is the NameSpace object, which is retrieved by using the Application object's Session property. As noted earlier, some confusion can arise because functionality that you would expect to be on the Application object is actually often found on the NameSpace object. Further increasing the confusion is the Application.GetNameSpace method, which is an older way to get to a NameSpace object. This method takes a string for the type of NameSpace to return implying that you can get different types of NameSpace objects. In reality, the GetNameSpace method only accepts one string ("MAPI"). In this chapter, we use the Application object's Session property (added in Outlook 98) to get a NameSpace object rather than the older GetNameSpace method.

Working with the Root Folders of the Open Outlook Stores

The NameSpace object's Folders property returns a Folders collection, allowing you to iterate over all the root folders that are open within Outlook. Each root folder is the root of what is called a Store. A root folder could correspond to an Exchange account or some other e-mail account. It could also correspond to an Outlook data file, such as a .PST file. Every folder and Outlook item under a particular root folder share the same StoreID.

You can iterate over the Folders collection using C#'s foreach keyword. You can also get to a particular MAPIFolder in the Folders collection by using the index operator ([]). The index operator can be passed a string representing the name of the Folder in the Folders collection, or a 1-based index representing the index of the Folder within the Folders collection.

Although the Folders collection provides Add and Remove methods, these methods are not applicable to root folders because root folders represent accounts that are added and removed by adding and removing e-mail accounts or adding and removing Outlook data files. The following section discusses how a Store is added and removed programmatically.

Listing 11-10 illustrates iterating over the Folders collection using foreach. It also shows how to get a MAPIFolder using the index operator on the Folders collection. Finally, it shows adding a new Folder to an existing store using the Folders collection's Add method.

Listing 11-10. VSTO Add-In That Iterates over the Root Folders and Adds a New Folder

private void ThisApplication_Startup(object sender, EventArgs e) { foreach (Outlook.MAPIFolder folder in this.Session.Folders) { MessageBox.Show(folder.Name); } Outlook.MAPIFolder rootFolder = this.Session.Folders[1]; Outlook.MAPIFolder newFolder = rootFolder.Folders.Add( "Test Notes Folder", Outlook.OlDefaultFolders.olFolderNotes); MessageBox.Show(String.Format( "A new folder has been created in the store {0}.", rootFolder.Name)); }

Adding and Removing Outlook Stores

To programmatically add a Store, you can use the NameSpace object's AddStore or AddStoreEx methods. The AddStore method takes a Store parameter of type object. You can pass a string representing the complete filename of the PST file to add. If the PST file you provide does not exist, Outlook creates the file for you. AddStoreEx takes the same Store parameter of type object that AddStore does. It also takes a second Type parameter of type OlStoreType. To this parameter, you can pass a member of the OlStoreType enumeration, which will control the format in which the PST file will be created should you pass a PST file that does not exist. The possible values you can pass are olStoreDefault, olStoreUnicode, or olStoreANSI.

Use the NameSpace object's RemoveStore method to programmatically remove a Store. RemoveStore removes the Store from Outlook but does not delete the actual PST file or mailbox on the server associated with the Store. RemoveStore takes a Folder parameter of type MAPIFolder. This parameter must be one of the root folders in the NameSpace object's Folders collection.

Determining the Current User

The NameSpace object's CurrentUser property returns a Recipient object representing the logged-in user. Given a Recipient object, you can use the Recipient object's Name property to get the name of the logged-in user.

Checking Whether Outlook Is Offline

You can determine whether Outlook is offline by getting the value of the NameSpace object's Offline property. This property returns true if Outlook is offline and not connected to a server.

Getting Standard Folders Such As the Inbox Folder

A method already used in several examples in this chapter to get standard Outlook folders such as the Inbox folder is the NameSpace object's GetDefaultFolder method. This method takes a FolderType parameter of type OlDefaultFolders and returns a MAPIFolder object. Table 11-6 lists the members of the OlDefaultFolders enumeration that can be passed to GetDefaultFolder and the standard Outlook folder that is returned.

Getting a Folder or Outlook Item by ID

All Outlook items and folders are uniquely identified by an EntryID and a StoreID. Each Outlook item and folder within a given Store share the same StoreID. The EntryID is unique within a given Store. So the combination of an EntryID and StoreID uniquely identifies a folder or an Outlook item. When you have created a new Outlook item by using the Items collection's Add method or the Application object's CreateItem method, the newly created Outlook item will not be assigned an EntryID until you call the Save method on the newly created item.

Both a MAPIFolder and the 15 Outlook item types have an EntryID property that returns the EntryID for the folder or item as a string. But only MAPIFolders have a StoreID property. To determine the StoreID that corresponds to a particular Outlook item, you must get the parent MAPIFolder using the Parent property of an Outlook item and then determine the StoreID from the parent folder.

The NameSpace object's GetFolderFromID method takes an EntryID parameter as a string and an optional StoreID parameter as an object to which you can pass the StoreID as a string. If you omit the StoreID parameter by passing Type.Missing, Outlook assumes it should look in the default Store (the Store in which the default Inbox and Calendar are found). The GetFolderFromID method returns the MAPIFolder object identified by the EntryID and StoreID.

The NameSpace object's GetItemFromID method takes an EntryID parameter as a string and an optional StoreID parameter as an object to which you can pass the StoreID as a string. If you omit the StoreID parameter by passing Type.Missing, Outlook assumes it should look in the default Store. The GetItemFromID method returns the object for the Outlook item identified by the EntryID and StoreID. You can then cast the returned object to 1 of the 15 Outlook item types listed in Table 10-1.

Listing 11-11 illustrates getting a folder and an Outlook item by EntryID and StoreID.

Listing 11-11. A VSTO Add-In That Uses the NameSpace Object's GetFolderFromID and GetItemFromID Methods

private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.MAPIFolder inbox = this.Session.GetDefaultFolder( Outlook.OlDefaultFolders.olFolderInbox); string inboxStoreID = inbox.StoreID; string inboxEntryID = inbox.EntryID; object outlookItem = inbox.Items[1]; string itemStoreID = inboxStoreID; string itemEntryID = (string)GetPropertyHelper( outlookItem, "EntryID"); Outlook.MAPIFolder theFolder = this.Session.GetFolderFromID( inboxStoreID, inboxEntryID); MessageBox.Show(theFolder.Name); object theItem = this.Session.GetItemFromID( itemStoreID, itemEntryID); MessageBox.Show((string)GetPropertyHelper( theItem, "Subject")); } private object GetPropertyHelper(object targetObject, string propertyName) { return targetObject.GetType().InvokeMember(propertyName, System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.GetProperty, null, targetObject, null, System.Globalization.CultureInfo.CurrentCulture); }

Accessing Address Books and Address Entries

The NameSpace object's AddressLists property returns the AddressLists collection. The AddressLists collection is a collection containing all the available address books as AddressList objects. The AddressList object has an AddressEntries collection, which is a collection of AddressEntry objects. Each AddressEntry object represents an address in an address book.

Listing 11-12 iterates over the available address books and displays the name of each address book. It also displays the name of the first address entry in each address book.

Listing 11-12. A VSTO Add-In That Iterates over Available Address Books

private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.AddressLists lists = this.Session.AddressLists; foreach (Outlook.AddressList list in lists) { MessageBox.Show(String.Format( "{0} has {1} address entries.", list.Name, list.AddressEntries.Count)); if (list.AddressEntries.Count > 0) { MessageBox.Show(String.Format( "The first address in this address book is {0}.", list.AddressEntries[1].Name)); } } }

Displaying the Outlook Folder Picker Dialog

The NameSpace object provides a method that allows you to display Outlook's folder picker dialog shown in Figure 11-7. The folder picker dialog provides a way for the user to pick a folder as well as create a new folder. The NameSpace object's PickFolder method displays the folder picker dialog as a modal dialog box. The method returns the MAPIFolder object corresponding to the folder the user picked in the dialog. If the user cancels the dialog box, this method will return null.

Figure 11-7. Outlook's Select Folder dialog.