CDO Tips and Pitfalls

The CDO library is powerful and approachable, but you can run into problems if you aren't careful when writing your code. This section introduces some tips and tricks you should use and some pitfalls you should avoid. Many of the pitfalls I mention are from personal experience ”they are quite frustrating, so I recommend that you read this section before attempting to write any CDO code.

Avoid the GetNext Trap

Let's jump right in! Look at the following code and try to figure out what is wrong:

 MsgBox oSession.Inbox.Messages.GetFirst.Subject For Counter = 2 To oSession.Inbox.Messages.Count     MsgBox oSession.Inbox.Messages.GetNext.Subject Next 

The same subject will appear in your message box as many times as the number of messages in your Inbox. Despite what the code looks like, it won't recurse through your Inbox because if you don't explicitly assign an object to a variable, CDO will create needed temporary objects for each statement and then discard the object after the statement. This means you will instantiate a new object every time you loop in the For Next loop. Each new object does not maintain the state of the previous temporary object, so the object will always point to the first message in the collection. So you should set explicit variables to refer to a collection to get the desired functionality. The following listing shows the rewritten code, which behaves as expected:

 Set oMessages = oSession.Inbox.Messages Set oMessage = oMessages.GetFirst MsgBox oMessage.Subject For Counter = 2 To oMessages.Count     Set oMessage = oMessages.GetNext     MsgBox oMessage.Subject Next 

Avoid Temporary Objects if Possible

Whenever possible, avoid the use of temporary objects, as demonstrated in the previous section. But don't spend a lot of time scouring your code to get rid of temporary objects unless you are a major offender of this rule. Sometimes you'll want to use temporary objects to represent the different CDO objects rather than declare variables. However, using temporary objects should be an exception and not a rule in your coding practices.

Use Early Binding with Visual Basic

To improve the performance of your Visual Basic CDO applications, always try to use early binding by declaring your CDO variables as specific CDO objects. Not only will it be easier to write your code because Visual Basic can perform type checking and help you finish statements in your code, but your users will thank you for the application's improved performance.

Use With Statements

You use the dot operator to set a property, call a method, or access another object. Essentially, each dot represents additional code that must be executed. If you can reduce the number of dot operators in your code, you can improve performance of your application. One way to do this is by using With statements. For example, consider the following code snippet, which has no With statements and is inefficient in terms of both performance and readability:

 MsgBox "Text: " & oSession.Inbox.Messages.GetFirst.Text MsgBox "Subj: " & oSession.Inbox.Messages.GetFirst.Subject 

Now consider the next bit of code, which does use the With statement. This code executes faster:

 With oSession.Inbox.Messages.GetFirst     MsgBox "Text: " & .Text     MsgBox "Subj: " & .Subject End With 

The rule of thumb is to think of dots in your code as expensive.

Avoid the Dreaded ASP 0115 Error

For writing CDO applications using ASP, the best tip I can give you is that you should use the code from this book to handle your logons and logoffs from CDO and ASP sessions. The most common pitfall that new and even experienced CDO developers run into when writing ASP applications is forgetting to insert the correct impersonation code into Global.asa, which properly destroys the CDO and ASP sessions. When a user attempts to access your Web application after Microsoft Internet Information Services (IIS) attempts to use the wrong context to destroy these objects, the application returns the ASP 0115 error, which means that a trappable error has occurred in an external object.

Avoid the MAPIE_FailOneProvider and CDOE_FailOneProvider Errors

In your ASP applications, you should also avoid the CDOE_FailOneProvider and MAPIE_FailOneProvider errors, which occur when you try to access the root folder of the Public Folder InfoStore object or a folder in the mailbox of a specific user. Many developers run into these errors, especially those who are new to ASP programming. The most common cause of these errors is not changing the security context that IIS uses to access the Exchange server so that the Web user will be authenticated via Windows Challenge/Response authentication or Basic authentication. The Web user will therefore try to access the root of the Public Folder store or a user's mailbox using the Windows credentials of the anonymous IIS user account. This anonymous account often doesn't have security permissions to access the Exchange server. When this is the case, CDO returns CDOE_FailOneProvider or MAPIE_FailOneProvider to indicate an error in accessing the information.

The easiest way to solve this problem is to use the logon and logoff code from the examples in this book. These examples, especially the Helpdesk application, authenticate users by prompting them for their Windows credentials before attempting to access any Exchange Server information.

Learn Your Properties and Their IDs Well

As you have seen, many of the objects in the CDO library support the Fields property. This property returns a Fields collection, which allows you to find custom and built-in properties using identifiers supplied by either Exchange Server or MAPI. These Exchange Server and MAPI properties are powerful yet elusive . They allow you to perform operations on Exchange Server and Outlook items in situations where CDO does not provide objects. For example, in the Helpdesk application, user information is pulled out of the AddressEntry property by using the unique identifiers for department name , office location, and other properties. If you did not know that these properties existed, you would think that their information was inaccessible from CDO because CDO does not provide explicit objects for them.

Another scenario that illustrates why these unique properties are valuable is when you set up folders to work off line. Documentation on this process is hard to find, but MAPI provides a property called PR_OFFLINE_FLAGS ( &H663D0003 ), which contains a zero (0) if the folder is not currently set to synchronize off line and a 1 if it is. By using this property, you can programmatically set any folder in the mailbox of a user to synchronize off line ”the user does not have to set synchronization manually through Outlook. If this field does not already exist in the Fields collection, you must add it to the collection by using the Add method.

The best place to find the information about the properties you can use with the Fields collection is in the CDO help file under "MAPI Property Tags" or in the Messaging and Collaboration section of the MSDN Library under "Collaboration Data Objects," "CDO 1.2.1," "SDK Documentation," "CDO 1.2.1," and then "Appendixes." MSDN contains both the MAPI property tags and the Exchange Server property tags. These properties can provide new functionality to your applications even though CDO might not provide explicit objects for this functionality.

Learn to Love MDBVUE

If you have never used the MDBVUE tool, you should get familiar with it. MDBVUE is included on the Exchange Server CDs. It uses MAPI and allows you to look at the internals of your Exchange Server such as property IDs and detailed MAPI information. Note that the property IDs you get back when you use MDBVUE are machine specific. This means you cannot take the property ID returned for the IM address of an Outlook contact and use it on another machine. Instead, you have to use the full property set ID and property ID, which we will discuss in the next section.