Tuesday, August 14, 2012

Contract First Web Services


Recently I was thrust into the need to create a new Web Service from scratch, but the client required that the service not be written code first. There are a lot of good arguments on why Contract First development is useful. Here is a chapter on why "Contract First" is preferred, a StackOverflow discussion, and a list of Six Reasons (page is slow to load, but worth it).

I found an MSDN blog that gave be a good middle point to work from, but it didn't contain the entire process from start to finish. So here it is, a three-part walk-through on how to create a .net contract first web service from scratch. Here is an overview of the process:
  • Create a Visual Studio Project
  • Create a WSDL using Altova XMLSpy, and add it to the project
  • Convert the WSDL to a web-service interface
  • Implement and test the web-service with soapUI

Here we go - Create a Visual Studio Project

In Visual Studio 2010, create a new ASP.NET Web Application; I called mine ContractFirstWebServiceExample.

Creating the Visual Studio Project
Now that the solution has been created, it's time to start working on the WSDL. A very good tool for authoring the WSDL is Altova XMLSpy, as mentioned earlier. But before I get into that, think about the specific web service we're going to implement.

The web service will be pretty strait forward, a "Hello Contract First Web Service World" kind of thing. The web service will simply take someones full name as the request, and return a response like "Hello, Abraham Dybvig." The request and response can be a string type:

Simple Web Service Diagram
Now that we know what our web service does, it's time to design a contact for it. In XMLSpy, create a new WSDL file. For this walk-through I'm using a v1.1 WSDL:

Create New Document Dialogue

This generates a stub WSDL with default values. I expanded all nodes on the right panel in this example:

Overview Pane (Expanded)

Edit the details of the WSDL, to names that make sense for the project and save the WSDL in the same folder as the Visual Studio project created earlier. The center pane of XMLSpy now looks something like this (I expanded all the nodes):

WSDL Definition

Here are my modifications:
  • Changed the namespace to http://contract.first.project.namespace
  • Changed the request and response messages to HelloUserRequest and HelloUserResponse respectively
  • Changed the request and response parameters to userName and reply respectively
  • Changed the port to IHelloUserPort (The reasoning for IHelloUserPort is discussed in a later section)
  • Changed the operation to SayHello
  • Changed the binding to HelloUserBinding
  • Changed the service to HelloUserService
One could go on, defining a complete WSDL with imported XSD types, and a robust set of operations in the service. Before the WSDL is published to clients, it can be iterated over in XMLSpy to include more capabilities. Save it to the existing project folder (from earlier) and add it to the Visual Studio project.

WSDL Added to Project
Now that the WSDL is part of the project, we can generate an interface, contained in a .cs file. Visual Studio does not come with a built in tool to create code interfaces from WSDLs, but it can be configured as an external tool by calling SvcUtil. This tool is included as part of the Windows SDK.
  • Add a new menu item, I called it Create WSDL Interface
  • The Command, as of this posting, is located at
    C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SvcUtil.exe
  • For parameters, I used
    /language:C# /out:$(ProjectDir)$(ItemFileName).cs $(ItemPath) /noConfig
    which instructs SvcUtil to create a new C# class file, of the same name as the WSDL in the same directory as the project. Config saving is disabled to prevent UAC errors on Windows 7.
Add External Tool

Once ScvUtil is ready the WSDL can be processed from within Visual Studio. With the WSDL open in Visual Studio, click on the new menu uption Tools/Create WSDL Interface. The results are given in the output window, and a new code file is created in the project folder ready for addition:

Create WSDL Interface
Add the interface to the Visual Studio project and create a new Web Service to implement it.
  • Add the interface .cs file to the project, mine is called IHelloUser.cs
  • Add a new web service to the project, I called mine HelloUserWebService
  • Include and implement the IHelloUserPort interface and add the [WebService] method decoration
The web service is ready for a basic test. Using soapUI to test the service will generate an error response since the method isn't implemented. (For those who prefer TDD, this is expected and encouraged!) Now the service can be fully implemented.

There you have it a soup to nuts walkthrough of contract first web service development. I really enjoyed learning about this the first time trough, and gathering information from various sources (linkes provided in the article).


P.S. Based on recent experiences working with web services, I have become huge fan of Contract First Web Service Development for a couple reasons. I prefer to use TDD whenever possible and Contract First makes it easy to generate a set of tests for the stub service. One odvious test: does the stub service respond to a soap call (using soapUI, for example) based on the contract WSDL?