Developing .Net Service Oriented Applications - Contract-First Approach

SO (Service Oriented) architecture, generally nowadays implies Web Service Service Oriented architecture, is in vogue and every vendor clamours to produce easy-to-use tools/IDE. But SO or Web Service is more than authoring some classes and spitting out the service. In my research, I come across the following highly recommended articles by Aaron Skonnard, slightly dated but every bit relevant today, containing extremely valuable lessons to designing SO/Web Services that are worth remembering.

In his first article of a series to introduce this concept of "Contract-First Approach", he introduce this by way of drawing parallelism with COM programming. "Contract-First approach" in that technology is by way of authoring the COM IDL. Contrasting this is an approach promoted by Visual Basic and he called this "Code-first approach" by encouraging developers to author classes which are then translated into COM type library.

He went on to cite the following disadvantages of code-first vs contract-first:

The code-first approach made it much easier for developers using Visual Basic to build COM applications, but it came with its own set of problems.

Although it increased productivity, this code-first approach complicated versioning.
[...]
The other problem with the Visual Basic code-first approach was that it hurt interoperability in mixed-language environments.

In contrast, for the contract-first approach, he cited that

...they were more aware of the issues given their focus on the contract. An important aspect to designing a shared contract is considering the needs of all possible implementation environments before writing code.

Many developers didn't realize that they too could enjoy the benefits of contract-first development by authoring the IDL first, compiling the IDL into a type library, and then referencing the type library to bring the interface definition into the project.

He concluded his introduction with the following warning that everyone serious about developing SO should heed:

Now, not all organizations using COM were concerned with mixed-language support or long-term versioning and were more interested in improving short-term development productivity. Such organizations were perfectly content, and even successful, taking the Visual Basic code-first route despite some of the issues I've outlined. Ironically, the new world of SO is heading down the same path, dealing with a very similar set of issues.

I was drummed in, in my early days of COM programming, that the proper way to develop COM (and to the same extend CORBA) was to author IDL first and I've never forget this valuable advice. Unfortunately, I have lost the reference to this article.

In dealing with Web Service,

most of today's Web services frameworks make it possible to design services using either code-first or contract-first techniques; however, most Web service development frameworks push developers towards the former. Frameworks that provide a code-first approach provide a translation layer to map between the native programming language and XSD and WSDL.

While code-first ASMX programming technique improves productivity and reduce the learning curve, his warning should be heeded:

Experience has shown that services implemented using code-first techniques, like the default ASMX model, are less likely to interoperate cleanly in mixed-language environments. However, the difference with SO is that mixed environments are much more common—practically the norm—making interoperability a much greater design concern. The problem is compounded by the fact there are more programming languages and type systems involved in this new world than before in the component days. Now it's even more important to consider all possible implementation environments during the contract design stage.

Code-first can also complicate versioning because the developer isn't in direct control of the contract, but must rely on the translation layer throughout development. However, unlike Visual Basic 6.0, ASMX doesn't provide any fancy compatibility modes to help the developer know when making changes to the ASMX class may break contract compatibility with existing clients, which makes the situation even worse.

This is how to do the contract-first approach:

To use a contract-first approach, you start by authoring the XSD definitions to model the messages used by the service. Next you author the WSDL to define the service operations, specifying which XSD messages are sent and received. There are a variety of applications you can use to author these documents, including Notepad. These first few steps are the hardest for most developers because they aren't familiar with XSD and WSDL and because there isn't a great deal of tool support.

So how do you choose when to use code-first or contract-first approach? Here are his guidelines:

The answer is any time there is a strong emphasis on the messages exchanged or you need to ensure conformance to an existing message format..... Contract-first is, without question, the most natural approach in a message-oriented world, such as that of BizTalk.

Contract-first is also especially important when you require conformance to a particular contract from third parties, or when you're collaborating with other groups to define a shared contract throughout an organization. Using contract-first here allows you to solidify the contract up front while numerous parties implement the contract in parallel. All of these situations are common in industry today.
[...]
So when you own the contract, it is common sense to strive to make the contract as easy as possible for your consumers to use, which also begs for a contract-first model.

The biggest obstacle to contract-first design today is the lack of tool support, which hurts productivity. When productivity is the overriding concern, code-first can be an acceptable approach, especially when you're not particularly concerned with mixed-environment interoperability.

In his second article of this series, he describes the techniques and toolsets to support this contract-first approach.

There are not too many tools that are integrated with VS2005 to produce the WSDL, which in his mind is the toughest of the steps - the first, constructing the XSD Schema representing the XML message can be accomplished with the XSD designer in Visual Studio.

The one that he find extremely useful and competent is by thinktecture and is called Web Service Contract First. It is a free tool for VS2003 and VS2005.

These two articles are a must read materials for anyone serious about developing SO or Web Services applications.