Working with the Items Collection

This chapter has already covered how to iterate over the Outlook items in a MAPIFolder by using For Each with the Items collection. This section examines some additional methods that you can use when working with the Items collection.

Iterating over Outlook Items

The Items collection's SetColumns method enables you to tell Outlook to cache certain properties when you iterate over the Items collection so that access to those properties will be fast. An Outlook item has a number of properties associated with itnamevalue pairs that can be accessed by using an Outlook item's ItemProperties property. A typical MailItem has around 80 properties associated with it.

If you know that you are going to iterate using For Each over the Items collection, and you are going to be accessing the Subject and CreationTime properties only of Outlook items in that collection, you can call the Items collection's SetColumns method before iterating the collection and pass the string "Subject, CreationTime". Some limitations apply to which properties can be cached (for example, properties that return objects cannot be cached); check the documentation before using this method. After you have iterated over the collection, use the Items collection's ResetColumns method to clear the cache of properties Outlook created.

The Items collection's Sort method enables you to apply a sort order to the Items collection before you iterate over the collection using For Each. The method takes a Property parameter as a String, which gives the name of the property by which to sort. You pass the name of the property enclosed in square brackets. To sort by subject, you would pass "[Subject]". The Sort method also takes an optional Descending parameter that can be passed TRue to sort descending, False to sort ascending. The default value if you omit the parameter is False. Some limitations apply to which properties can sorted on; check the documentation before using this method.

Listing 11.16 illustrates using the SetColumns and Sort methods. It times the operation of iterating through all the items in the Inbox and examining the Subject property without calling SetColumns. Then it times the operation again but calls SetColumns first. Finally, Sort is illustrated, and the first item and last item in the sorted Items collection are accessed using the index operator. The Items collection's Count property is also used to get the index of the last item in the Items collection.

Listing 11.16. A VSTO Add-In That Uses the Items Collection's SetColumns and Sort Methods

Public Class ThisApplication   Private Sub ThisApplication_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim inbox As Outlook.MAPIFolder     inbox = Me.Session.GetDefaultFolder( _       Outlook.OlDefaultFolders.olFolderInbox)     Dim myItems As Outlook.Items = inbox.Items     MsgBox("Click OK to start the test.")     Dim startDate As System.DateTime = System.DateTime.Now     Dim item As Object     For Each item In myItems       Dim subject As String = CType(item.Subject, String)     Next     Dim endDate As System.DateTime = System.DateTime.Now     Dim result1 As System.TimeSpan = endDate.Subtract(startDate)     MsgBox(String.Format( _       "Without calling SetColumns this took {0} ticks.", _        result1.Ticks))     startDate = System.DateTime.Now     myItems.SetColumns("Subject")     For Each item In myItems       Dim subject As String = CType(item.Subject, String)     Next     endDate = System.DateTime.Now     Dim result2 As System.TimeSpan = endDate.Subtract(startDate)     MsgBox(String.Format( _       "With SetColumns this took {0} ticks.", _       result2.Ticks))     myItems.ResetColumns()     myItems.Sort("[Subject]")     Dim firstItem As Object = myItems(1)     Dim lastItem As Object = myItems(myItems.Count)     MsgBox(String.Format( _       "First item is {0}.", firstItem.Subject))     MsgBox(String.Format("Last item is {0}.", lastItem.Subject))   End Sub End Class 

Finding an Outlook Item

The Items collection's Find method enables you to find an Outlook item in the Items collection by querying the value of one or more properties associated with the Outlook item. The Find method takes a String, which contains a filter to apply to find an Outlook item. You might want to find an Outlook item in the items collection with its Subject property set to "RE: Payroll", for example. The way you would call Find would look like this:

Dim foundItem As Object foundItem = myItems.Find("[Subject] = ""RE: Payroll""") 

The query string has the name of the property in brackets. Alternatively, you could call Find substituting apostrophes for the quotation marks used in the first example:

Dim foundItem As Object foundItem = myItems.Find("[Subject] = 'RE: Payroll'") 

If the Items collection does not contain an Outlook item whose Subject property is equal to "RE: Payroll", the Find method returns Nothing. If there are multiple Outlook items in the Items collection whose Subject property is equal to "RE: Payroll", you can continue finding additional items by using the Items collection's FindNext method. The FindNext method finds the next Outlook item in the collection that matches the filter string passed to Find. You can continue to call FindNext until FindNext returns Nothing, indicating that no more items could be found, as shown in Listing 11.17.

Listing 11.17. A VSTO Add-In That Uses the Items Collection's Find and FindNext Methods

Public Class ThisApplication   Private Sub ThisApplication_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim inbox As Outlook.MAPIFolder     inbox = Me.Session.GetDefaultFolder( _       Outlook.OlDefaultFolders.olFolderInbox)     Dim myItems As Outlook.Items = inbox.Items     Dim foundItem As Object = myItems.Find( _        "[Subject] = ""RE: Payroll""")     While foundItem IsNot Nothing       MsgBox(String.Format(         "Found item with EntryID {0}.", foundItem.EntryID))       foundItem = myItems.FindNext()     End While   End Sub End Class 

We have illustrated a rather simple filter string that just checks to see whether a text property called Subject matches a string. It is possible to use the logical operators AND, OR, and NOT to specify multiple criteria. The following filter strings, for example, check both the property Subject and the property CompanyName. The first finds an Outlook item where the Subject is "RE: Payroll" and the CompanyName is "Microsoft". The second finds an Outlook item where the Subject is "RE: Payroll" or the CompanyName is "Microsoft". The third finds an Outlook item where the Subject is "RE: Payroll" and the CompanyName is not "Microsoft".

Dim foundItem As Object = myItems.Find( _   "[Subject] = 'RE: Payroll' AND [CompanyName] = 'Microsoft'") Dim foundItem As Object = myItems.Find( _   "[Subject] = 'RE: Payroll' OR [CompanyName] = 'Microsoft'") Dim foundItem As Object = myItems.Find( _   "[Subject] = 'RE: Payroll' AND NOT [CompanyName] " & _   "= 'Microsoft'") 

When searching for a property that is an integer value, it is not necessary to enclose the integer value you are searching for in quotes. The same is true for a property that is a boolean property. This example searches for an Outlook item whose integer property OutlookInternalVersion is equal to 116359 and whose boolean property NoAging is set to False.

Dim foundItem As Object = myItems.Find( _   "[OutlookInternalVersion] = 116359 AND [NoAging] = False") 

Some limitations apply to which properties you can use in a filter string. Properties that return objects cannot be examined in a filter string, for example. Check the documentation of the Outlook object model for more information.

If you are working with an Items collection that has a large number of Outlook items in it, consider using the Items collection's Restrict method rather than Find and FindNext. The Restrict method is used in a similar way to how SetColumns and Sort are used. You call the Restrict method on the Items collection passing the same kind of filter string you provide to the Find method. Then you can use For Each to iterate over the Items collection, and only the Outlook items that match the filter string will be iterated over. The Restrict method can be faster than Find and FindNext if you have a large number of items in the Items collection and you expect to find only a few items. Listing 11.18 illustrates using the Restrict method.

Listing 11.18. A VSTO Add-In That Uses the Items Collection's Restrict Method

Public Class ThisApplication   Private Sub ThisApplication_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim inbox As Outlook.MAPIFolder     inbox = Me.Session.GetDefaultFolder( _       Outlook.OlDefaultFolders.olFolderInbox)     Dim myItems As Outlook.Items = inbox.Items     For Each foundItem As Object In myItems.Restrict( _       "[Subject] = ""RE: Payroll""")       MsgBox(String.Format("Found item with EntryID {0}.", _         foundItem.EntryID))     Next   End Sub End Class 

Adding an Outlook Item to an Items Collection

To add a new Outlook Item to an Items collection, use the Items collection's Add method. The Add method takes an optional Type parameter of type Object to which you can pass a member of the OlItemType enumeration: olAppointmentItem, olContactItem, olDistributionListItem, olJournalItem, olMailItem, olNoteItem, olPostItem, or olTaskItem. If you omit the Type parameter, the type of the item is determined by the type of folder (as determined by DefaultItemType) that you are adding the item to. The Add method returns an Object, which can be cast to the Outlook item type corresponding to the Type parameter that was passed in.

You must remember that you can add only an Outlook item that is compatible with the folder type the Items collection came from. It is not possible, for example, to add a ContactItem to an Items collection from a folder that is designated to hold MailItems and PostItems. For more information on the Outlook item types that can be contained by a particular folder type, refer to Table 11.6 earlier in this chapter.

Listing 11.19 shows an example of using the Add method to add a PostItem and a MailItem to the Inbox folder. Note that using the Add method is not sufficient to get the PostItem and MailItem added to the Inbox folder. For the PostItem, we also have to call the Save method on the newly created Outlook item; otherwise, Outlook discards the PostItem when the variable postItem that refers to it goes out of scope. We also have to call Save on the newly created MailItem. In addition, we have to call the Move method to move the newly created MailItem into the Inbox folder. This is necessary because Outlook puts newly created MailItems into the Drafts folder by defaulteven though we called Add on the Items collection associated with the Inbox. Without the call to Move, the newly created MailItem remains in the Drafts folder.

Listing 11.19. A VSTO Add-In That Adds a MailItem and a PostItem

Public Class ThisApplication   Private Sub ThisApplication_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim inbox As Outlook.MAPIFolder     inbox = Me.Session.GetDefaultFolder( _       Outlook.OlDefaultFolders.olFolderInbox)     Dim myItems As Outlook.Items = inbox.Items     Dim postItem As Outlook.PostItem = myItems.Add( _       Outlook.OlItemType.olPostItem)     postItem.Subject = "Test1"     postItem.Save()     Dim mailItem As Outlook.MailItem = myItems.Add( _         Outlook.OlItemType.olMailItem)     mailItem.Subject = "Test2"     mailItem.Save()     mailItem.Move(inbox)   End Sub End Class 

An alternative way to create an Outlook item is to use the Application object's CreateItem method. This method takes a Type parameter of type OlItemType that is passed a member of the OlItemType enumeration. It returns an Object representing the newly created Outlook item. Then you must save the created item and place it in the folder you want to store it in. Listing 11.20 shows code that uses CreateItem to do the same thing that Listing 11.19 does. In Listing 11.20, we must move the new MailItem and PostItem to the Inbox folder using the Move method on MailItem and PostItem.

Listing 11.20. A VSTO Add-In That Uses the Application Object's CreateItem Method to Add a MailItem and a PostItem

Public Class ThisApplication   Private Sub ThisApplication_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim inbox As Outlook.MAPIFolder     inbox = Me.Session.GetDefaultFolder( _       Outlook.OlDefaultFolders.olFolderInbox)     Dim mailItem As Outlook.MailItem = Me.CreateItem( _       Outlook.OlItemType.olMailItem)     mailItem.Subject = "Test 1"     mailItem.Save()     mailItem.Move(inbox)     Dim postItem As Outlook.PostItem = Me.CreateItem( _       Outlook.OlItemType.olPostItem)     postItem.Subject = "Test 2"     postItem.Save()   End Sub End Class