Wiz/dumb : Outlook

Line Breaks in Managed Web Service Proxy Classes

Patrick Creehan — Wed, 22 Jul 2009 16:00:00 GMT

Matt, Rick, and I were working on an issue recently where when an application using EWS would set a contact’s Street address to a value containing a carriage return and line feed, like this:

  physicalAddress.Street = "1234 56 Ave NE\r\nc/oPatrick Creehan";

the address card control in Outlook would render it like this:

Ugly, right? The problem was that the XMLSerializer would strip out the line feed and leave the carriage return, which the address card didn’t like.

We could prove by sending raw XML requests in a separate application that sending 
 for the carriage return line feed would make everything right, however, if we set the street address like this:

  physicalAddress.Street = "1234 56 Ave NE&#x0d;&#x0a;c/oPatrick Creehan";

then the contact’s address card would look like this:

Even uglier! It seems that the .net framework, in an attempt to help us out is encoding our string for XML but it wasn’t letting us specify the value we knew was right.

So – the solution is to implement your own class which can handle the XmlSerialization yourself, and replace the auto-generated proxy class’s decision for the type to yours.

Here’s my simple class:

     [SoapTypeAttribute(Namespace = "http://schemas.microsoft.com/exchange/services/2006/types",TypeName="text")]
     public class mstring:IXmlSerializable   
     {
         private string m_string = string.Empty;
 
         public override string ToString()
         {
             return m_string;
         }
         
  
         public static mstring CreateMString(string str){
             mstring newmstring = new mstring();
             newmstring.m_string = str;
             return newmstring;
         }
 
         public static implicit operator mstring(string str)
         {
             return CreateMString(str);
         }
 
 
         #region IXmlSerializable Members
 
         public System.Xml.Schema.XmlSchema GetSchema()
         {
             return new System.Xml.Schema.XmlSchema();
         }
 
         public void ReadXml(XmlReader reader)
         {
             m_string = reader.ReadContentAsString();
         }
 
         public void WriteXml(XmlWriter writer)
         {
             string outString = m_string;
             outString = HttpUtility.HtmlEncode(outString);
 
             outString = outString.Replace("\r", "&#x0d;");
             outString = outString.Replace("\n", "&#x0a;");
 
             writer.WriteRaw(outString.ToString());
         \

A few things to point out is that I decorated this class with the XML namespace for the Exchange Web Services so that it doesn’t fail schema validation. Also, I didn’t really test whether this works when binding to an existing contact – there may be more work needed in the ReadXML section. In order to support still setting the Street property to a string, I had to override the implicit operator. That allows me to set Street to a string even though technically, now Street is an “mstring.” You’ll notice that the work of actually writing the correct value occurs in WriteXml which we got by implementing IXmlSerializable. Now when the SOAP infrastructure goes to build the request, it will call into our interface to serialize this class.

That reminds me, the last thing you need to do to hook all this up is to go into the web service proxy class Reference.cs and modify the PhysicalAddressDictionaryEntryType so the street properties use your new mstring class instead of string:

     /// <remarks/>
     [System.CodeDom.Compiler.GeneratedCodeAttribute("System.Xml", "2.0.50727.4918")]
     [System.SerializableAttribute()]
     [System.Diagnostics.DebuggerStepThroughAttribute()]
     [System.ComponentModel.DesignerCategoryAttribute("code")]
     [System.Xml.Serialization.XmlTypeAttribute(Namespace="http://schemas.microsoft.com/exchange/services/2006/types")]
     public partial class PhysicalAddressDictionaryEntryType {
         
         private mstring streetField;
         
         private string cityField;
         
         private string stateField;
         
         private string countryOrRegionField;
         
         private string postalCodeField;
         
         private PhysicalAddressKeyType keyField;
         
         /// <remarks/>
         public mstring Street {
             get {
                 return this.streetField;
             }
             set {
                 this.streetField = value;
             }
         }
 
         /// <remarks/>
         public string City {
             get {
                 return this.cityField;
             }
             set {
                 this.cityField = value;
             }
         }
         
         /// <remarks/>
         public string State {
             get {
                 return this.stateField;
             }
             set {
                 this.stateField = value;
             }
         }
         
         /// <remarks/>
         public string CountryOrRegion {
             get {
                 return this.countryOrRegionField;
             }
             set {
                 this.countryOrRegionField = value;
             }
         }
         
         /// <remarks/>
         public string PostalCode {
             get {
                 return this.postalCodeField;
             }
             set {
                 this.postalCodeField = value;
             }
         }
         
         /// <remarks/>
         [System.Xml.Serialization.XmlAttributeAttribute()]
         public PhysicalAddressKeyType Key {
             get {
                 return this.keyField;
             }
             set {
                 this.keyField = value;
             }
         }
     \

and (after removing the email address so the address will fit on the card) it looks like this:

Cake.

ConfigureMsgService fails with MAPI_E_INVALID_PARAMETER (0x80070057)

Patrick Creehan — Fri, 10 Jul 2009 16:02:00 GMT

I recently helped a customer with an issue where they were calling ConfigureMsgService and that call was failing, returning an HRESULT of MAPI_E_INVALID_PARAMETER (0x80070057). After debugging it, we established that the reason that ConfigureMsgService was failing was that the PR_PROFILE_HOME_SERVER_ADDRS property was missing from the profile. Outlook seemed to work fine, logons worked, sending mail worked; it was just that ConfigureMsgService would fail. We tried recreating the profile, but still the property wasn’t being set on the profile.

It turns out that PR_PROFILE_HOME_SERVER_ADDRS gets its value from PR_EMS_AB_NETWORK_ADDRESS, which in turn, gets its value from the networkAddress attribute on the server object in Active Directory. That value was set correctly, but permissions to that object were not. After following the requirements laid out on technet for permissions to AD objects, we determined that the Authenticated Users group was missing the ACL for Read All Properties on the server object. Once we set that permission and recreated the profile, the property was set correctly on the profile and ConfigureMsgService started succeeding.

TNEF (Chapter 2): Old School

Patrick Creehan — Wed, 28 Jan 2009 02:09:40 GMT

As discussed in Chapter 1 of this captivating series, MAPI contains an interface to allow developers to create and read TNEF data. This interface is the ITnef interface. There are only a few methods in this interface and they are, for the most part, self explanatory. The entire process of creating a TNEF stream can be done in just a few steps:

Call OpenTnefStreamEx to get a TNEF stream to write into.

Make sure you pass in TNEF_ENCODE since you’ll be creating TNEF. If you were reading TNEF, you’d pass in TNEF_DECODE instead. The other flags to worry about here are TNEF_BEST_DATA, TNEF_COMPATIBILITY, and TNEF_PURE. All of these just signal to MAPI how you want the properties you add to the TNEF stream treated. They will either be all converted to the old-school attributes (TNEF_COMPATIBILITY) – you shouldn’t use this one; some will be converted to attributes but also written to the attMAPIProps section (TNEF_BEST_DATA); or they will all just be written to the MAPI props and none of them written to the attributes (TNEF_PURE).
Call EncodeRecips and pass in the Recipient table you get from a call to IMessage::GetRecipientTable on your message.
Call AddProps passing in an SPropTagArray of non-transmittable prop tags and use the TNEF_PROP_EXCLUDE flag.

There are essentially two schools of thought for building your TNEF: exclude the props you don’t want and let MAPI deal with the rest; or choose carefully which props you do want to include and add them each piecemeal. These are the reason for having the TNEF_PROP_EXCLUDE and TNEF_PROP_INCLUDE flags. One of them says here are the properties I don’t want you to encode (TNEF_PROP_EXCLUDE) and the other, TNEF_PROP_INCLUDE, says I want you to include all of these properties.

There’s another method, SetProps, which does just that, sets the value of a property in the TNEF stream to a value you supply. This allows you to modify the data of the message you are trying to encode, or add additional properties that weren’t on the original.

Back to AddProps for a moment. The flags that supports don’t stop with TNEF_PROP_INCLUDE and TNEF_PROP_EXCLUDE, There is also TNEF_PROP_ATTACHMENTS_ONLY which says “of the properties I’ve given you to work with, I only want you to include/exclude the ones that have to do with attachments. Contrast that with TNEF_PROP_MESSAGE_ONLY which says "”of the properties I’ve given you to work with, I only want you to include/exclude the ones that have to do with the message itself – not attachments.” Then there’s the CONTAINED flags: TNEF_PROP_CONTAINED and TNEF_PROP_CONTAINED_TNEF. TNEF_PROP_CONTAINED means that these properties are going on an attachment; and the TNEF_PROP_CONTAINED_TNEF means I have TNEF data I’m going to give you to put in an attachment – like if you already had a TNEF blob you wanted to include as an attachment, which I’ll demonstrate below.
Once you get all your properties added and included/excluded properly, you call Finish and you’re done. One thing that makes it a little complicated though, is that you have to keep alive all the pointers and streams, etc you’re using in your TNEF until Finish is called, because that’s when all the internal work is actually done. So when you call Finish, that’s when MAPI says, Oh, ok, let me go get that recipient table you gave me. If you’ve already released it, then the process fails.

So it’s pretty easy to do this. This is essentially the way that MFCMAPI demonstrates how to do it (look in File.cpp under SaveToTNEF). There are problems associated with doing it this way when it comes to Unicode properties and when having multiple embedded messages.

The more complicated way to do this to work around some of the issues described above is to add the properties you want explicitly, including each attachment.

The basic difference in the strategy is that instead of calling AddProps with TNEF_PROP_EXCLUDE, call it with TNEF_PROP_INCLUDE and give it the SPropTagArray you get from a call to GetPropList on the message. You’ll need to filter out the non-transmittable properties (such as custom props and things like the Store EntryID). Once you add all the message props, call GetAttachmentTable and loop through each attachment and do one of two things, if it’s not an embedded message, just add the attachment data with AddProps on PR_ATTACH_DATA_BIN; otherwise, you’re going to recurse over yourself and build a TNEF stream from the embedded message. When you call Finish on it, then you’ll add it to the parent TNEF stream by calling AddProps with PR_ATTACH_DATA_OBJ and using the TNEF_PROP_CONTAINED_TNEF flag and give it the stream for your TNEF blob. Once you unwind all the way, you’ll have your “master” TNEF stream. Essentially, you’ll follow the steps here: http://msdn.microsoft.com/en-us/library/cc839833.aspx

TNEF (Chapter 1): Basics

Patrick Creehan — Fri, 16 Jan 2009 19:17:36 GMT

I’ve worked quite a few cases recently regarding problems some folks have had either reading or composing TNEF content. I’ve learned quite a bit myself as a result, and I thought I’d share. I decided I would do a series of blog posts on the topic and hopefully save some of you the time I spent learning all this.

So, being the first post on the topic, I suppose now would be a good time for a review on just what TNEF is and how it’s structured.

TNEF stands for Transport-Neutral Encapsulation Format. If you use Outlook or any other MAPI client as your mail client, you may know that MAPI is a protocol for communication between the client and the mailbox server. MAPI defines a set of interfaces which the client can use to work with the data in the mailbox. The MAPI structure for the data is hierarchical with messages being contained in containers, which themselves can have a parent container, all the way up to the root of the store. MAPI also defines a set of properties understood by the client and, in some cases, the server. If all mail sent could stay on this one server and only go between clients on this one system, this would be all we need; but we know that’s not the case. A very large quantity of e-mail is sent over the internet to foreign systems every day. The vast majority of those use an industry-standard protocol called SMTP (Simple Mail Transfer Protocol) to send messages in an industry-standard format called MIME (Multipurpose Internet Mail Extensions). MIME is composed of body parts, which can in turn be composed of additional body parts themselves. MIME also allows you to add headers to each of the body parts which allow you to describe the content of that body part. So one body part may be a Word Document attachment, so the MIME headers on that body part would contain the MIME type such as application/doc and the transfer type, such as base64. The content of that body part would then contain a base64 encoding of the document. The headers for the root body part contain information such as the subject of the message, the sender and recipient information, etc.

As a message makes its way through transport from one person’s email client to another person’s, it encounters many “hops” (brief stops at SMTP servers in the routing path) which have the opportunity to modify the headers. They do this in order to track the path the message took or to flag it as SPAM, verify the sender address, etc. So there’s a chance the headers you specify when you send the message won’t be the same as when the message arrives at the destination. The headers also only support text values. One of the problems discovered early on about the MIME format was that it has no concept of “rich text.”

In early versions of Outlook, users wanted the ability to send and receive email that contained rich text bodies. Microsoft devised a plan to create an attachment to the messages it was sending that would have a certain content-type and would come to have a well-known name, “winmail.dat”. This attachment would contain an encapsulation of the MAPI properties that could represent this rich body that would work across any transport and be readable by any system that supported MIME.

The original structure just supported a very simple structure that was basically Name/size/value. These were called “attributes” and the names of these attributes are still prefixed by “att.” Many of the attribute names can be seen here: http://msdn.microsoft.com/en-us/library/cc765736.aspx. The most important of these attributes for the purposes of our discussion will be the attMAPIProps. This attribute contains a list of MAPI properties that the receiving system can set on the message once it has converted the other MIME parts into their MAPI format. Some of the TNEF attributes can be directly translated into MAPI properties as defined by the link earlier in this paragraph, but there is not a 1-1 mapping between TNEF attributes and MAPI properties – hence the attMAPIProps attribute. Attachments and recipient data can also be encoded into the TNEF structure, which we’ll examine more later.

MSDN documents the general structure of TNEF but it’s hard to understand. Last year, when Exchange decided to be among those systems that elected to publicly document their protocols, they created [MS-OXTNEF].pdf, which documents very clearly the structure of the TNEF data and how to parse it. Don’t get too nervous, though. I have parsed a 3MB TNEF blob manually myself, but in Exchange 2007, we provide managed code interfaces to allow you to read (or write) this data very easily. In subsequent posts, I’ll dive more into the structure and into the managed classes, as well as the legacy MAPI ITnef interfaces, and more into problems you may experience in developing TNEF-enabled applications.

MAPI Docs Moved

Patrick Creehan — Thu, 04 Dec 2008 18:34:00 GMT

So, the Exchange team decided they didn't want to maintain the MAPI documentation anymore since they don't ship MAPI anymore. So the Outlook team stepped up and took over the docs. As such, you can now find them under the Outlook branch in the MSDN left-nav.

http://msdn.microsoft.com/en-us/library/cc765775.aspx

Steve Griffin has been working with the Outlook team on prettying them up and updating them for a few months, and they're now better than ever! He even got a new icon for MFCMAPI out of the deal!

Trouble with Live Search Maps Add-in for Outlook

Patrick Creehan — Wed, 22 Oct 2008 16:08:27 GMT

Several million of you have downloaded the Live Search Maps Add-in for Outlook which allows integration in Outlook with maps and has some cool functionality around extending your appointment blocks to account for automatically calculated travel time among other things.

We have received a large number of support cases that are caused either directly or indirectly because of this add-in. These include hangs, crashes, and leaks. There could be any number of different reasons for those, but to name one culprit, the add-in interops with CDO 1.21, which if you are a messaging developer following the blogs of anyone on our team, you will know that this is not supported.

http://support.microsoft.com/kb/266353

Worse than that, it is distributing CDO.dll, which is also not supported. http://support.microsoft.com/kb/171440

A customer of mine reported an issue that lead us to another discovery. The add-in installs a custom form to your Personal forms registry and changes the default form for the calendar to IPM.Appointment.Location. The form it publishes is based on the LEO.oft form that it installs in your Program Files. The OFT was clearly customized from an existing item in the designer’s mailbox. The form contains a value for PR_START_DATE and PR_END_DATE set to 4/6/2006. The problem with this is that Outlook doesn’t use PR_START_DATE and PR_END_DATE, but CDO 1.21 does and OWA will set them as well. Outlook uses custom named props to keep track of dates. Exchange normally keeps these custom props and PR_START/END_DATE in sync, but only if it needs to because of a modification you did from OWA or something like that. Otherwise, the original values will stick.

If you have a CDO 1.21 application which filters based on a date, all the appointments you created with this form in your calendar will appear to be on 4/6/2006.

The long-term plan for what to do about all the problems in this add-in has not been determined at the time of writing of this blog, but it may result in the download being removed from microsoft.com. This won’t help you fix up any items that already exist in your calendar though – nor will it prevent users from using the add-in if they already have it downloaded and installed.

If you insist on continuing to use the add-in, then please at least use this updated form.

You will need to publish this form to your Personal Forms library over the original. If you uncomfortable with that, you can

Uninstall the add-in using Add/Remove Programs.
Remove the existing form from your Personal forms library,
Close Outlook and ensure no instances of Outlook.exe are running in Task Manager.
Reinstall the add-in,
Replace the LEO.oft in the Program Files folder (C:\Program Files\Live Search Maps for Outlook) with the one contained in the ZIP file linked above.
Open Outlook. (the add-in will publish your new form).

This should allow your CDO 1.21 code to execute normally on any newly created items. For existing items, you can use Outlook Object Model or CDO 1.21 (or Extended MAPI) code to loop through the appointments in your calendar and delete the PR_START_DATE and PR_END_DATE properties if they are on 4/6/2006 with a message class of IPM.Appointment.Location. Outlook should still be able to work with the appointment just fine without those properties.

Misha Shneerson : COM Interop: Handling events has side effects

Patrick Creehan — Wed, 22 Oct 2008 16:04:09 GMT

Misha, a Senior Dev on the VSTO team just posted this blog describing why handling events in managed code can be problematic. This is not news to our team, but he provides a good explanation of why it’s problematic.

Misha Shneerson : COM Interop: Handling events has side effects

If any of what he says sounds familiar, it’s because our own Matt Stehle has been talking about this for a while.

Forwarding Appointments in Outlook Prepopulates “To” Field With All Attendees

Patrick Creehan — Fri, 19 Sep 2008 20:38:00 GMT

We’ve had a lot of folks calling in recently about this one. The symptoms are that if you go to your calendar in Outlook and forward a meeting, the To field is prepopulated with all attendees of the meeting and the Subject field is not prefixed with “FW:.”...(read more)

RPC - Really Problematic Conundrum

Patrick Creehan — Tue, 15 Jul 2008 17:49:52 GMT

I’ve had a couple cases recently where customers were having problems getting into deadlock with one of our modules, usually MAPI or Outlook. There’s one common thread that connects these cases: message pumps.

Your application has to make a remote call to a server object living in a different process or thread. Often times this is referred to as an “asynchronous” call. That term is somewhat misleading – suggesting your process could actually forget that it made the call and then be surprised when it comes back. In actuality, there’s always a listener constantly waiting for the call to return. What makes it seem asynchronous is that the waiting happens on a different thread. In order to wait for your call return, applications often implement logic called a “message pump.” This just processes incoming Windows messages or RPC calls and dispatches them to be processed; and it keeps processing messages until your call returns.

The problem with this is that there’s no easy way to tell what these incoming messages are or what they’ll do. This is what gets you into trouble.

Let’s say that a normal code path in one thread will go something like this:

Outlook does some work
Outlook locks a critical section (CS1)
Outlook calls into you
You do some work
You get a lock on a critical section (CS2)

There’s nothing wrong with this at all. Everything is fine at this point. Now lets suppose there’s a different thread that does something like this

You do some work
You get a lock on a critical section (CS2).
You make an RPC call or otherwise pump messages.

Now, up to this point there’s nothing wrong. Suppose, however, that one of the pending messages is from Outlook and the execution goes something like this:

…You make an RPC call…
The message pump dispatches the Outlook call
Outlook does some work
Outlook locks a critical section (CS1).

Again, nothing is inherently wrong with this execution path by itself. However, when you combine both threads, you have critical sections being locked in reverse order – classic deadlock.

Here’s a way to understand the problem: Let’s say you’re at home watching a Virginia Tech football game (There are other teams? Oh yeah, I just call them “losers.”) with a friend. You both get a hankering for a cold adult beverage. You go to the fridge, but there’s only one left. You decide to split it with your buddy, which is ok, since it’s a 40. Meanwhile, your other friends arrive with their own adult beverages and ask if anyone has an opener. Your buddy gets up and gets the bottle opener. You are thinking, “OK, I have the bottle, now all I need is the bottle opener, but my buddy has it so I’ll just wait until he’s done.” You both return to your respective recliners. Your buddy is thinking, “ok, I have the opener, I guess I’ll just start opening bottles with it until my glass gets filled. Surely one of the bottles will be mine.” As he’s opening your other friends’ bottles, the thought enters his mind – my friend [you] has a bottle he needs opened – I need to get his bottle to open it for him. Since both yours and your buddy’s rear ends are plastered to their respective recliners, you have now entered adult beverage deadlock.

Your buddy was keeping the bottle opener all to himself while waiting for his glass to be filled. Little did he understand that by holding the bottle opener to himself, he was preventing that from happening, since the bottle was already being held firmly in your grip. Had he relinquished control of the bottle opener, you could have easily picked it up and used it. He didn’t know that one of the bottles he had to open would be yours.

So how do we prevent this problem from occurring in the first place? The key is really that your buddy didn’t know what bottles he would be opening, while waiting for his glass to be filled. He didn’t know that you were planning to split the beverage with him. What he could have done is just told your friends that the bottle opener was in the drawer instead of holding onto the bottle opener while waiting for his glass to be filled. That way, when you needed it, it would be available and as long as everyone puts it back when they’re done with it, though you may need to wait for a short time, no one will go thirsty for long.

The moral of the story is that you shouldn’t make it a practice to hold onto a lock while making an RPC call or otherwise pumping messages because you don’t know what messages will arrive in your pump and what locks they will request.

Secondary moral of the story: always make sure your adult beverage supply is properly maintained.

Go Hokies!

Two-way STSSync Protocol Server for Outlook 2007

Patrick Creehan — Wed, 11 Jun 2008 00:53:19 GMT

So I've finally done it. I made the first stab at a two-way stssync protocol server. You can get it here:

http://www.codeplex.com/stssyncprovider

I'd love to have some of you start using it and report issues you find with it so I can continue to improve it. I know there are issues already, but it should be mostly there to at least get you started.

This was largely inspired by Stephen Toub's original Custom Calendar Provider sample. I'd recommend reading that article for background on this idea. I later updated it to work with Outlook 2007, but this was still just using the ver=1.0 sync (one-way) . Now, with the release of the SharePoint protocol documents which I announced some months back and troubleshooting logging in Outlook, I've been able to construct a stssync protocol server, which, like Toub's sample, allows for you to simply create a provider that snaps into the engine.

My original design goal was to make it so that provider developers would only have to implement a single interface which returned a dataset of records when Outlook requests them and accepted a dataset of updates when Outlook makes changes and the rest of the plumbing would be handled by the provider engine ("the engine"). I came pretty close. Here is the interface as it stands so far:

public interface IProvider

{

DataSet GetEmptyDataSet(Guid ProviderID);

DataRow GetSingleRow(Guid ProviderID, int id);

DataRow Update(Guid ProviderID, DataRow updateRow);

DataSet GetUpdatesSinceToken(Guid ProviderID, ChangeKey changeKey);

ListType GetProviderType(Guid ProviderID);

StringDictionary GetFieldMappingsForListType(Guid ProviderID, ListType listType);

}

So here's the explanation for the interface.

GetEmptyDataSet: this is mostly used so that the engine can get a feel for what columns are in the table you're returning. You simply return an empty typed dataset or a standard dataset with a single (empty) table that contains the same columns you would later return filled.
GetSingleRow: Pretty easy - I give you an ID, you give me back the row associated with it.
Update: I give you the datarow with changes made and you pass me back the updated row (some columns may change as a result of doing the update - like Modified time, for example)
GetUpdatesSinceToken: I give you a changekey from which you can extract a timestamp, or just call ToString to use the changekey as a watermark for getting changes since the last sync. You return your DataSet filled with any rows that have changed since the provided watermark (changeKey).
GetProviderType: You return a value from the ListType enumeration. This tells the engine whether you're a contacts provider versus a calendar provider, task provider, discussion list provider, or document library provider (no doc library or attachment support is currently in the provider - it's tbi).
GetFieldMappingsForListType - In this method you simply return a StringDictionary filled with any field name mappings the engine can use to map the columns in your dataset to column names it's familiar with. For example, you might do something like oSDict.Add("myContactIDField","ID");

Each method is passed the ProviderID specified in the web.config for this provider. If you want to implement two different providers in the same class, you can distinguish between them using this ID, otherwise, your implementation can largely ignore this parameter - it is mostly used by the engine to get a reference to your interface.

Once you've implemented the interface, just go to the web.config file for the engine and add a new Provider element. Here's a sample:

<ProviderProxy>      
  <Providers>       
    <Provider Name="AdventureWorks Contacts" ID="{7765B84F-6D32-4d31-B28E-6BC615D2F187}" Type="AdventureWorksProvider.Contacts" Assembly="AdventureWorksProvider" />       
  </Providers>       
</ProviderProxy>

Name = just the display name you want to appear on the list in Outlook and on default.aspx
ID = this contains a Guid that is used in invoking methods on your IProvider interface.
Type = the Namespace.ClassName of the type of your IProvider interface.
Assembly = the qualified assembly name of the the assembly that contains the Type specified.

Copy your assembly to the bin directory of the engine web site and the engine will automatically find your assembly. I modified the Pre- and Post-Build events on my AdventureWorks provider sample to automatically do this to simplify the debugging process.

This is just a very rough draft. I wanted to have a sample up there that folks could start to work with and get some ideas. I'd love to hear your feedback and for you to help mold the project into something that is good over time. Please contact me with any issues you find or any suggestions (I know of some myself, already). I'll do my best to put out regular releases as the code base improves. I'd also love to hear what you do with it and what unique stores you start syncing with Outlook.

Just as a note, in this initial release, I do not support one-way sync, just two-way (seems backwards, but the goal was to get a two way sync working).

Also, I may need to change the IProvider interface definition from one release to the next as bugs/feature-completeness dictate probably in the early phases. It doesn't make sense to have an interface that's incomplete. Once I'm able to declare feature-completeness on the IProvider interface, any new enhancements or additional functionality will come in the form of additional/augmented interfaces (IProvider2, etc).

Outlook Requests Can't Get a Date

Patrick Creehan — Wed, 23 Apr 2008 21:52:00 GMT

There exists a scenario in which attendees to a meeting in Outlook will receive an updated meeting request from the originator that appears to be "out-of-date." In the InfoBar, Outlook will display a message that says "This request is out-of-date." If the attendee attempts to accept the meeting request, they get an error dialog box. Now, this is expected if there was an update that was made but a later update was already made - that's sort of what that functionality in Outlook was designed for. However, in this scenario, you see a new meeting request and very shortly after you get an update to the same meeting. It's clear that the update didn't come before the original request, so how can it be out-of-date?

This scenario exists where an appointment is modified by an application using CDO 1.21. In order to get the problematic behavior, the machine running the CDO 1.21 code has to have the clock set to a time earlier than the client machine. If CDO 1.21 modifies the appointment and sends updates within the time delta between the two machines, the update will appear to Outlook to be earlier than the original request.

Imagine the scenario:

CLIENT_MACHINE_1 and CLIENT_MACHINE_2 have a current system time of 3:00 PM.

CDO121_MACHINE has a current system time of 2:57 PM.

3:00 PM	User1 on CLIENT_MACHINE_1 sends a meeting request to User2 on CLIENT_MACHINE_2.
3:01 PM	User2 accepts the meeting request and the appointment is added to User2's calendar.
3:02 PM	CDO 1.21 code runs on CDO121_MACHINE server and modifies the appointment on User1's calendar and sends the meeting request update (stamped 2:59 PM which is the current system time on CDO121_MACHINE) .
3:03 PM	User2 receives the updated meeting request and Outlook displays the update as being out-of-date.

The problem boils down to a difference in meeting update behavior between Outlook and CDO 1.21. There's a sequence number property on meeting requests that Outlook increments each time an update is made to a meeting. Outlook examines this sequence number first when deciding which update is newest - this code was put in place for scenarios like this primarily for pop3 clients, which only use sequence number. The timestamp is used as a secondary factor in deciding which is newer. CDO 1.21 wasn't designed with some of these modern calendaring scenarios in mind and doesn't (and won't ) support incrementing the sequence number - it's simply copied over as are most props.

So...if everyone just synchronizes their clocks to the same time server often enough, we'll all be happy :).

If you have CDO 1.21 code which causes this to occur to some of your clients, here are a few ideas that you can try:

in your processing, don't process meetings that have the timestamp later than the current system time on the machine your code is running on.
Push for your customer to keep machine times in their environments synchronized. This should at least minimize the impact. Clearly this won't account for scenarios where users are using home computers over a VPN or RPC/HTTP connection or using mobile devices that may have clocks synchronized to a different source.

STSSync for the Masses: Toub's Revenge

Patrick Creehan — Tue, 08 Apr 2008 21:13:12 GMT

Many of you have been using the Custom Calendar Provider samples created by Stephen Toub and I:

Stephen Toub - Custom Calendar Providers for Outlook 2003

Custom Calendar Providers for Outlook 2007

The development team has finally documented pretty much everything you need to know in order to build your own STSSync provider (to replace SharePoint as our code samples do). The documentation is included in many of the newly documented Open Protocol specifications:

[MS-OUTSPS] Lists Client Sync Protocol Specification

I'm excited to see what you do with this!

Outlook Crashes When Using Outlook Object Model in Multiple Threads

Patrick Creehan — Thu, 13 Mar 2008 19:11:11 GMT

One of the major requirements most developers are up against these days is ensuring their code runs as fast as possible. No one likes to wait for an application to run, they want seamless, invisible, instant speed. Multithreading is becoming more popular now that many desktops and certainly most servers are shipping with multiple processors or multiple cores. By spinning up multiple threads to execute many different code-paths simultaneously, you can certainly increase the performance of your application.

This mentality is ever-increasingly being blended into Outlook development as well. There has been a rash of developers in recent months who are reporting problems with their Outlook add-ins crashing Outlook when doing multi-threading. While it may give the perception of a better performing add-in, the reality is that this really isn't going to help, nor will it work.

Outlook Object Model is run in a STA COM server. This means that all OOM calls are executed on the main thread. If you are building an add-in that is making OOM calls from another thread (other than the main thread), then your calls need to be properly marshaled back to thread 0. For unmanaged code, you should use CoMarshalInterface or CoMarshalInterThreadInterfaceInStream to marshal your object pointer across threads. This will ensure your OOM calls are properly executed on thread 0. If you are writing managed code, using the OOM through COM interop by means of the PIA will actually handle this marshalling for you.

All of this talk about marshalling interfaces back to the main thread begs the question, "What's the point?" If the OOM calls need to run on thread 0, why spin up a new thread to do OOM work in the first place? That's a great question. You don't gain any performance because all the calls are going to run on the same thread anyway and you incur the overhead hit of doing the marshaling to begin with, so there's not really an advantage to multithreading Outlook Object Model.

Here are some links to some smart folks talking about this same thing:

All Outlook object model calls run on the main thread

Threading in an Outlook Addin

Add-in threading issue causes Outlook to crash or hang

HELP: Outlook 2003 Doesn't Display my HTML Body

Patrick Creehan — Thu, 10 Jan 2008 18:46:00 GMT

If you've developed a custom message store and you can't get Outlook to display RTF or HTML content, check the length of your EntryIDs. If your RTF content is really just wrapped HTML content or you are providing PR_HTML, and for some reason Outlook 2003 won't display your HTML content, it may be the length of your EntryIDs.

Outlook 2003 leverages IE (mshtml) to display it's HTML content. It does this by implementing a protocol handler for the outbind:// protocol. Outbind's format leverages the EntryID of the message when creating the URL. You can probably see where I'm going here. If your entryID is longer than the allowable limit for a URL, which for IE7 is 0x200 (512) characters, then mshtml fails the load of the HTMLDocument. When that happens, Outlook says "oh, well, RTF/HTML didn't work, let's just load PR_BODY and live with that.

If you've verified that your EntryID is sufficiently short enough (maybe only 100 or so characters) then you may want to look at the values you're returning in the GetProps or QueryRows call.

This could change from version to version, but in general, you just return MAPI_E_NOT_FOUND for properties you don't support, MAPI_E_NOT_ENOUGH_MEMORY that you support but don't want to return in this GetProps call necessarily. If you return the size error for PR_BODY, PR_HTML, and PR_RTF_COMPRESSED then the RTFSync property will determine the preference on whether we use HTML or RTF. Of course, you should always be returning the value (or MAPI_E_NOT_FOUND) if asked for the property directly (as in OpenProperty or HrGetOneProp).

Folder Homepage no longer works in Outlook 2007 from MAPI store providers

Patrick Creehan — Wed, 19 Dec 2007 19:02:00 GMT

If you are developing or have developed a MAPI store provider for use in Outlook and are trying to support folder homepages in your store, you are probably familiar with the PR_FOLDER_WEBVIEWINFO property. This property is undocumented and not supported, but I'll assume for the sake of this article that you have a read/write store and you're allowing Outlook to set that property for you. :)

You may have noticed that folder homepages worked in previous versions of Outlook, but don't work in Outlook 2007. This is because we are turning off folder home pages (FHP) for non-default stores by default in Outlook 2007.

You cannot add a URL to the Address box on the Home Page tab in Outlook 2007 (923933)

Simply setting the registry key below will re-enable them:

\Software\Policies\Microsoft\Office\12.0\Outlook\Security
"NonDefaultStoreScript"=dword:00000001