My experience writing an Office Research Service

I was quite intrigued by the idea of providing a research service for office. After all, this was the first real-world web-services based extension interface for a major application. I downloaded the Microsoft Ofiice 2003 Research SDK and got going.

Since building a research service is all about Web services I first looked for WSDLs to describe the service... only to find that the SDK does not provide any WSDL documents. Instead, it shows some C# sample code for an asmx web service. I guess at the time the SDK was put together, nobody had heard about Christian's Contract First Tool to generate asmx Web services stubs. I also guess that nobody considered (or cared about) content providers that use Java or PHP (which is quite common for content web sites). Just in case, I posted an office research WSDL ready for anybody's consumption.

The first positive finding was that the SDK at least provides XML Schemas for all messages that are exchanged between the Office Application and the Web service. Unfortunately I found that these schemas have a few glitches. For example, many types simply define their content using the <any> wildcard, even though their content is (at least seems to be) deterministic. That unfortunate choice reduces the ability to validate incoming messages using these schemas -- an often recommended best practice to secure Web services.

Now that I found the schemas, my logical next step was to create XML serialization classes using XSD.exe from the schemas. After all, we're dealing with strongly structured XML here, which is perfect for parsing with the XmlSerializer. To simplify the process I wanted to create only one C# file with classes for all Xml types in the schemas. Now guess what! I ran into yet another rather brain-dead “feature” of XSD.exe. XSD.exe concatenates the file names of the schemas you provide. Apparently nobody ever produced classes from schemas with longer filenames, because when you try to create classes for the research service schemas XSD.exe will quite happily tell you that it can't write the output file because it's file name is too long!

Once I got the classes from XSD.exe, building the service was mostly a piece of cake. Some classes that XSD.exe generated were not compatible with the XmlSerializer, which I do blame on XSD.exe. Some schemas caused problems because of the way some schema types are defined. In most cases the XML Schemas do a good job to extract types shared between multiple schemas into a common schema. However, some of them were missed before the schemas were released and some types are defined in two schemas.  This is not so much a problem if you only process the Xml messages with DOM or with XmlReaders and XmlWriters. It does break though when you use XmlSerialization though because the two types are structurally compatible, but not identical and cannot be substituted.

Because of all these problems I wound up making a few changes to the auto-generated classes. That's a practice I usually highly discourage, but in cases like this you can only hope that you don't have to regenerate them any time soon.

The modified Xml serialization classes are going to be in my (almost done) gotdotnet sample. After all, coding with Xml serialization is still nicer than coding with DOM or XmlReader/-Writer. In the mean time, take a look at my Feedster Research Service.

Enjoy.