Visual Studio Tools for Office: Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath

2017-07-07 02:10:07

This chapter has discussed the 16 Outlook item types: AppointmentItem, ContactItem, DistListItem, DocumentItem, JournalItem, MailItem, MeetingItem, NoteItem, PostItem, RemoteItem, ReportItem, TaskItem, TaskRequestAcceptItem, TaskRequestDeclineItem, TaskRequestItem, and TaskRequestUpdateItem. We group these object model types because all these types have many common properties and methods, listed in Table 11.8. The properties and methods in this table are found on all Outlook item types. The properties and methods marked in this table with an asterisk are found on all Outlook item types except NoteItem. NoteItem is a special case in the Outlook item family and has a subset of the properties and methods that the other Outlook item types share.

Table 11.8. Properties and Methods Common to All Outlook Items
Actions*	Delete	NoAging*
Application	Display	InternalVersion*
Attachments*	DownloadState	OutlookVersion*
AutoResolvedWinner	EntryID	Parent
BillingInformation*	FormDescription*	PrintOut
Body	GetInspector	Save
Categories	Importance*	SaveAs
Class	IsConflict	Saved
Close	ItemProperties	Sensitivity*
Companies*	LastModificationTime	Session
Conflicts	Links	ShowCategoriesDialog*
ConversationIndex*	MarkForDownload	Size
ConversationTopic*	MessageClass	Subject
Copy	Mileage*	UnRead*
CreationTime	Move	UserProperties*

Now we consider several of these common properties and methods. Even though we talk about Outlook Items as though there were an OutlookItem type in the Outlook object model, there is no such type; the OutlookItem type is a conceptual way of talking about the properties and methods common to the 16 Outlook item types in the Outlook object model. So when we talk about the Save method, for example, that method is found on ContactItem, PostItem, MailItem, and all the other Outlook item types.

Given an object that you know is 1 of the 16 Outlook item types, you can cast it to the correct Outlook item type, or you can talk to the object via late-bound properties if you are talking to a property common to all Outlook items. Some of the code listings in this section use late-bound properties and have illustrated this point. Usually, it is preferable to cast the object to the specific item type rather than use late binding.

Creating an Outlook Item

You learned the two primary ways in which you can create an Outlook item earlier in this chapter, in the section "Adding an Outlook Item to an Items Collection." You can call either the Items collection's Add method or the Application object's CreateItem method. These methods take a member of the OlItemType enumeration and return an object that can be cast to the Outlook item type corresponding to the OlItemType enumeration, as shown in Table 11.9.

Table 11.9. Correspondence Between OlItemType and Outlook Item Types
`OlItemType Member`	Outlook Item Type
`olAppointmentItem`	AppointmentItem
`olContactItem`	ContactItem
`olDistributionListItem`	DistListItem
`olMailItem`	MailItem
`olNoteItem`	NoteItem
`olJournalItem`	JournalItem
`olPostItem`	PostItem
`olTaskItem`	TaskItem

Notice that there are eight items in this table, which leaves out seven Outlook item types. How do you create the other seven remaining Outlook item types? The remaining types are created by Outlook or created as a result of other actions you take with an existing Outlook item type. Table 11.10 identifies how the other Outlook item types are created.

Table 11.10. How the Other Outlook Item Types Are Created
Outlook Item Type	How Created
DocumentItem	The Items collection's Add method also accepts a member of the `OlOfficeDocItemsType` enumeration: `olWordDocumentItem, olExcelWorkSheetItem`, or `olPowerPointShowItem`. Calling the Items collection's Add method with any of these constants returns an `Object` that can be cast to a DocumentItem. You can also create a DocumentItem using the Application object's CopyFile method.
MeetingItem	Cannot be created directly. Created by Outlook when AppointmentItem.MeetingStatus is set to `olMeeting` and sent to one or more recipients.
RemoteItem	Cannot be created directly. Created by Outlook when you use a Remote Access System connection.
ReportItem	Cannot be created directly. Created by the mail transport system.
TaskRequestAcceptItem	Cannot be created directly. Created by Outlook as part of the task delegation feature.
TaskRequestDeclineItem	Cannot be created directly. Created by Outlook as part of the task delegation feature.
TaskRequestItem	Cannot be created directly. Created by Outlook as part of the task delegation feature.
TaskRequestUpdateItem	Cannot be created directly. Created by Outlook as part of the task delegation feature.

Identifying the Specific Type of an Outlook Item

You can determine the specific type of an Outlook item given to you as type Object by using the TypeOf operator to determine whether the Outlook item is a particular type, as shown in Listing 11.21. The code gets an Outlook item out of the Inbox and then uses the TypeOf operator to determine whether it is an Outlook MailItem. If the Outlook item is a MailItem, the code proceeds to call the late-bound subject property to display the subject of the mail message.

Listing 11.21. A VSTO Add-In That Uses the TypeOf Operator on an Outlook Item of Type Object

You can also use declare a variable to a specific Outlook item type and set the variable to the Object representing the Outlook item. This will give you a variable that can be talked to in a strongly typed way. This technique is shown in Listing 11.22. A second technique is to use the CType operator to cast the Object to a particular Outlook item type. This approach is also shown in Listing 11.22.

Listing 11.22. A VSTO Add-In That Uses the Is Operator on an Outlook Item of Type Object

A final way to determine the type of an Outlook item of type Object is to call the late-bound Class property, which is found on every Outlook item type. The Class property returns a member of the OlObjectClass enumeration. Table 11.11 shows the correspondence between OlObjectClass enumerated values and Outlook item types.

Table 11.11. Correspondence Between Outlook Item Type and OlObjectClass Enumerated Value
Outlook Item Type	OlObjectClass Enumeration Member
AppointmentItem	`olAppointment`
ContactItem	`olContact`
DistListItem	`olDistributionList`
DocumentItem	`olDocument`
JournalItem	`olJournal`
MailItem	`olMail`
MeetingItem	`olMeetingRequest`
NoteItem	`olNote`
PostItem	`olPost`
RemoteItem	`olRemote`
ReportItem	`olReport`
TaskItem	`olTask`
TaskRequestAcceptItem	`olTaskRequestAccept`
TaskRequestDeclineItem	`olTaskRequestDecline`
TaskRequestItem	`olTaskRequest`
TaskRequestUpdateItem	`olTaskRequestUpdate`

Listing 11.23 shows some add-in code that calls the Class property on an Outlook item of type Object. Then it uses a Select Case statement, which for illustration purposes contains all the members of the OlObjectClass enumeration that correspond to Outlook item types. The code in Listing 11.23 would be more efficient than using the IsType operator if your code needs to cast to multiple specific Outlook item types, given an Outlook item of type Object. The code in Listing 11.15, for example, would be more efficient if it were rewritten to use the approach in Listing 11.23. The approach in Listing 11.23 needs to make only one late-bound property call to get the Class value and then one cast to get the specific Outlook item type.

Listing 11.23. A VSTO Add-In That Uses the Class Property to Determine the Outlook Item Type

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 item As Object = inbox.Items(1) Dim objectClass As Outlook.OlObjectClass = _ CType(item.Class, Outlook.OlObjectClass) MsgBox(String.Format("Class is {0}.", _ objectClass.ToString())) Select Case objectClass Case Outlook.OlObjectClass.olAppointment Exit Select Case Outlook.OlObjectClass.olContact Exit Select Case Outlook.OlObjectClass.olDistributionList Exit Select Case Outlook.OlObjectClass.olDocument Exit Select Case Outlook.OlObjectClass.olJournal Exit Select Case Outlook.OlObjectClass.olMail Dim mailItem As Outlook.MailItem = item MsgBox(String.Format( _ "Found mail item with subject {0}.", _ mailItem.Subject)) Exit Select Case Outlook.OlObjectClass.olMeetingRequest Exit Select Case Outlook.OlObjectClass.olNote Exit Select Case Outlook.OlObjectClass.olPost Dim postItem As Outlook.PostItem = item MsgBox(String.Format( _ "Found post item with subject {0}.", _ postItem.Subject)) Exit Select Case Outlook.OlObjectClass.olRemote Exit Select Case Outlook.OlObjectClass.olReport Exit Select Case Outlook.OlObjectClass.olTask Exit Select Case Outlook.OlObjectClass.olTaskRequest Exit Select Case Outlook.OlObjectClass.olTaskRequestAccept Exit Select Case Outlook.OlObjectClass.olTaskRequestDecline Exit Select Case Outlook.OlObjectClass.olTaskRequestUpdate Exit Select Case Else End Select End Sub End Class

Other Properties Associated with All Outlook Items

This section covers several commonly used properties associated with all Outlook item types (with the possible exception of NoteItem). When we say properties in the context of Outlook items, some confusion can arise. Some properties are on the actual Outlook item type. The Subject property, for example, is a callable property on all Outlook item object types. There are a MailItem.Subject property, PostItem.Subject, ContactItem.Subject, and so on. Sometimes, a property that is on an Outlook item object type is also accessible via the OutlookItem.ItemProperties collection. If you iterate over the ItemProperties collection, you will find an ItemProperty object where ItemProperty.Name returns "Subject".

The creators of the Outlook object model exposed some of the properties in the ItemProperties collection as first-class properties on the object types themselves. So the Subject property can be accessed by using either OutlookItem.Subject or OutlookItem.ItemProperties("Subject"). Other properties that are more obscure were not exposed out as properties on the objects themselves. The EnableSharedAttachments property, for example, can be accessed only via OutlookItem.ItemProperties("EnableSharedAttachments"). You learn more about the ItemProperties collection later in this chapter.

Table 11.12 lists several properties callable on all Outlook item object types. Properties marked with an asterisk are not available on the NoteItem object.

Table 11.12. Properties Associated with All Outlook Items
Name	Type	What It Does
Body	`String`	Gets and sets the body text of the Outlook item.
Categories	`String`	Gets and sets the categories assigned to the Outlook item. An Outlook item assigned to the Business and Favorites category, for example, would return the string `"Business, Favorites"`.
ConversationIndex*	`String`	Gets an identifier for the conversation index.
ConversationTopic*	`String`	Gets the conversation topic of the Outlook item.
Importance*	`OlImportance`	Gets and sets the importance as a member of the `OlImportance` enumeration: `olImportanceHigh, olImportanceLow`, or `olImportanceNormal`.
Sensitivity*	`OlSensitivity`	Gets and sets the sensitivity as a member of the `OlSensitivity` enumeration: `olConfidential, olNormal, olPersonal`, or `olPrivate`.
CreationTime	DateTime	Gets the DateTime the Outlook item was created.
LastModificationTime	DateTime	Gets the DateTime the Outlook item was last modified.
Size	`Integer`	Gets the size in bytes of the Outlook item.
Subject	`String`	Gets and sets the subject of the Outlook item.
UnRead*	`Boolean`	Gets and sets whether the Outlook item has been opened yet by the end user.

Copying or Moving an Outlook Item to a New Location

An Outlook item can be copied or moved from one folder to another. The Outlook item's Copy method creates a copy of the Outlook item and returns the newly created item as an Object. The Outlook item's Move method moves an Outlook item from one folder to another. It takes a DestFldr parameter of type MAPIFolder to which you pass the folder to which you want to move the Outlook item.

Deleting an Outlook Item

To delete an Outlook item, call the Outlook item's Delete method. Doing so causes the Outlook item to be moved to the Deleted Items folder, where it stays until the user empties the Deleted Items folder. If you do not want the item to appear in the Deleted Items folder, you must call Delete twice. The first call moves the item to the Deleted Items folder, and the second call deletes it from the Deleted Items folder, as shown in Listing 11.24.

Listing 11.24. A VSTO Add-In That Deletes an Item and Then Deletes It Permanently by Removing It from the Deleted Items Folder

Note in Listing 11.24 that we cannot find the item we just deleted in the Deleted Items folder using the EntryID because the EntryID changes when you delete the Outlook item. Instead, we use the Subject, which is not ideal because the Subject is not guaranteed to be unique. A better approach to deleting an item permanently and preventing it from showing up in the Deleted Items folder is using the Collaboration Data Objects (CDO) object model that was briefly described in Chapter 9, "Programming Outlook." Listing 11.25 shows this approach. We assume the VSTO Outlook add-in has a reference to the CDO object model interop assembly that adds the MAPI name space to the project. We use the GetMessageFromOutlookItem method, introduced in Listing 9.4 in Chapter 9.

Listing 11.25. A VSTO Add-In That Uses CDO to Delete an Outlook Item Permanently

Public Class ThisApplication Private mapiSession As MAPI.Session Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup mapiSession = New MAPI.Session() mapiSession.Logon(ShowDialog:=False, NewSession:=False) Dim inbox As Outlook.MAPIFolder inbox = Me.Session.GetDefaultFolder( _ Outlook.OlDefaultFolders.olFolderInbox) Dim postItem As Outlook.PostItem = inbox.Items.Add( _ Outlook.OlItemType.olPostItem) postItem.Subject = "Test Post To Be Deleted" postItem.Save() MsgBox("New post item is in inbox") Dim message As MAPI.Message message = GetMessageFromOutlookItem(postItem) message.Delete() MsgBox("New post item was permanently deleted.") End Sub Private Function GetMessageFromOutlookItem( _ ByVal outlookItem As Object) As MAPI.Message Dim entryID As Object = outlookItem.EntryID Dim parentFolder As Object = outlookItem.Parent Dim storeID As Object = parentFolder.StoreID Return CType(mapiSession.GetMessage(entryID, storeID), _ MAPI.Message) End Function End Class

Displaying an Outlook Item in an Inspector Window

The Outlook item's GetInspector method gives you an Inspector object to display an Outlook item. You can configure the inspector window before showing it by calling the Inspector object's Display method. The Display method takes an optional Modal parameter of type Object to which you can pass TRue to show the inspector window as a modal dialog box or False to show it as a modeless dialog box.

If you do not need to configure the inspector window before you display it, you can just use the Display method on an Outlook item. The Display method displays an inspector window and takes an optional Modal parameter of type Object to which you can pass TRue to show the inspector window as a modal dialog box or False to show it as a modeless dialog box.

If an inspector window is open for a given Outlook item, you can close the inspector window by using the Close method on the Outlook item being displayed. The Close method takes a SaveMode parameter of type OlInspectorClose. You can pass a member of the OlInspectorClose enumeration to this parameter: olDiscard to discard changes made in the inspector window, olPromptForSave to prompt the user to save if changes were made, and olSave to save without prompting.

Listing 11.26 creates a PostItem in the Inbox folder and calls the Display method to display an inspector window for it. Then it calls the Close method passing OlInspectorClose.olDiscard to close the inspector window. Note that we have to cast the PostItem to the Outlook._PostItem interface to distinguish between the Close method and the Close event, which collide on Outlook item objects.

Listing 11.26. A VSTO Add-In That Uses the Display and Close Method

Working with Built-In and Custom Properties Associated with an Outlook Item

The ItemProperties property returns the ItemProperties collection associated with an Outlook item. This collection contains ItemProperty objects for each property associated with the Outlook item. By property, we mean a namevalue pair that may or may not also have a get/set property on the Outlook item type. The ItemProperties collection can be iterated over using the For Each loop. It also supports Visual Basic's index operator (). You can pass a String as the index representing the name of the ItemProperty you want to access. You can also pass a 1-based index for the ItemProperty you want to access in the collection.

Listing 11.27 shows code that gets an ItemProperty object associated with a newly created PostItem using the index operator with a String and numeric index. Listing 11.27 also illustrates iterating over all the ItemProperty objects in the ItemProperties collection using For Each.

Listing 11.27. A VSTO Add-In That Works with ItemProperty Objects

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 postItem As Outlook.PostItem = inbox.Items.Add( _ Outlook.OlItemType.olPostItem) MsgBox(String.Format( _ "There are {0} properties associated with this post.", _ postItem.ItemProperties.Count)) ' Getting an ItemProperty with a string index Dim subject As Outlook.ItemProperty = _ postItem.ItemProperties("Subject") MsgBox(String.Format( _ "The property 'Subject' has value {0}.", _ subject.Value)) ' Getting an ItemProperty with a numeric index Dim firstProp As Outlook.ItemProperty firstProp = postItem.ItemProperties(1) MsgBox(String.Format( _ "The first property has name {0} and value {1}.", _ firstProp.Name, firstProp.Value)) ' Iterating the ItemProperties collection with foreach Dim result As New System.Text.StringBuilder For Each iProperty As Outlook.ItemProperty In _ postItem.ItemProperties result.AppendFormat( _ "{0} of type {1} has value {2}." & vbCrLf, _ iProperty.Name, iProperty.Type.ToString(), _ iProperty.Value) Next MsgBox(result.ToString()) End Sub End Class

You can add your own custom properties to an Outlook item. Custom properties that you have added are accessed by using the UserProperties property. An Outlook item's UserProperties property returns a UserProperties collection that contains UserProperty objects representing custom properties you have added to an Outlook item. Just as with the ItemProperties collection, the UserProperties collection can be iterated over using the For Each loop. A particular UserProperty in the collection can be accessed using the index operator () to which you pass a String representing the name of the UserProperty or the 1-based index of the UserProperty in the collection.

To add your own custom property, use the UserProperties collection's Add method. This method takes a required Name parameter of type String to which you pass the name of the new custom property. You must also specify the type of the new property by passing a member of the OlUserPropertyType enumeration. Common members of that enumeration you might use include olDateTime, olNumber, olText, and olYesNo. Other types are also supported; consult the Outlook object model documentation for more information. The Add method also takes two optional parameters that we omit: AddToFolderFields and DisplayFormat. Note that you can add custom properties to all Outlook item types except the NoteItem and DocumentItem types.

Listing 11.28 shows the creation of several custom properties using the UserProperties.Add method.

Listing 11.28. A VSTO Add-In That Works with Custom Properties

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 postItem As Outlook.PostItem = inbox.Items.Add( _ Outlook.OlItemType.olPostItem) postItem.Subject = "User Properties Test" postItem.Save() Dim userProperties As Outlook.UserProperties = _ postItem.UserProperties Dim dateProp As Outlook.UserProperty = userProperties.Add( _ "DateProp", Outlook.OlUserPropertyType.olDateTime) dateProp.Value = System.DateTime.Now Dim numberProp As Outlook.UserProperty numberProp = userProperties.Add( _ "NumberProp", Outlook.OlUserPropertyType.olNumber) numberProp.Value = 123 Dim textProp As Outlook.UserProperty = userProperties.Add( _ "TextProp", Outlook.OlUserPropertyType.olText) textProp.Value = "Hello world" Dim boolProp As Outlook.UserProperty = userProperties.Add( _ "BoolProp", Outlook.OlUserPropertyType.olYesNo) boolProp.Value = True MsgBox(String.Format("There are now {0} UserProperties.", _ userProperties.Count)) postItem.Save() End Sub End Class

Saving an Outlook Item

As you have already seen, when you create an Outlook item, you have to call the Save method, or the newly created item gets discarded when your variable containing the newly created item goes out of scope. You can check whether an Outlook item needs to be saved by accessing the Saved property. In Listing 11.28, for example, if we examine the Saved property right before we call postItem.Save at the end of the function, Saved would return False because some changes were made to the Outlook item (user properties were added) after the Save method was invoked earlier in the function.

The code in Listing 11.28 works even when you omit the last call to Save. Consider what happens, however, if we omit the last call to Save. If you examine the newly created item, its Saved state is still False after this function runs. If you double-click the newly created item to display an Inspector view and then close the Inspector view without making any changes, Outlook prompts users to save the changes made to the item, which is confusing to users because they did not make any changes. Outlook prompts to save because it still detects that it needs to save the changes made to the user properties by the add-in code. If you exit Outlook, Outlook will save the changes to the newly created item, and on the next run of Outlook, the saved state of the new item will be back to true.

Showing the Categories Dialog Box for an Outlook Item

You can show the Categories dialog box in Figure 11.9 by using the Outlook item's ShowCategoriesDialog method. This dialog box allows the user to select categories to associate with an Outlook item. As described earlier, the Outlook item's Categories property enables you to examine what categories an Outlook item is associated with. The Categories property returns a String value with each category associated with the Outlook item in a comma-delimited list.

Figure 11.9. Outlook's Categories dialog box.

Mail Properties and Methods

Several commonly used properties and methods are associated with items that would be found in a mail folder, such as a MailItem or a PostItem. The BodyFormat property tells you what format the body of a mail message is in. It sets or gets a member of the OlBodyFormat enumeration: olFormatHTML, olFormatPlain, olFormatRichText, or olFormatUnspecified. When a message is set to have its BodyFormat in olFormatHTML, the HTML for the body of the message can be set or get via the HTMLBody property. This property gets and sets the String value, which is the HTML content of the message.

Listing 11.29 shows add-in code that creates a PostItem using the BodyFormat and HTMLBody properties. Figure 11.10 shows the PostItem created by Listing 11.29.

Listing 11.29. A VSTO Add-In That Creates a PostItem with BodyFormat Set to olFormatHTML

Figure 11.10. PostItem created by Listing 11.29.

The Forward method returns a new Outlook item that can be forwarded to a recipient. Given a MailItem, for example, the MailItem object's Forward method returns a new MailItem. Then this MailItem can be given a recipient. Recipients of a MailItem are accessed via the Recipients property, which returns a Recipients collection. A new Recipient can be added by using the Recipients collection's Add method, which takes a String representing the display name of the recipient. When a recipient is added, the Outlook item can be sent in e-mail by calling the Outlook item's Send method.

Listing 11.30 illustrates working with the Forward method, the Recipients collection, and the Send method. It creates a PostItem that it then forwards as a MailItem to a recipient.

Listing 11.30. A VSTO Add-In That Creates a PostItem and Then Forwards It As a MailItem

An identical pattern is followed to reply or reply all to an Outlook item. The original item has its Reply or ReplyAll method called, which generates a new MailItem object. The Recipients collection of the new MailItem object is modified if needed. Finally, the new MailItem object's Send method is invoked to send the new MailItem.

Table 11.8. Properties and Methods Common to All Outlook Items