WCF - contract-first vs. code-first - how to document easily / properly?

Question

Folks,

I'm facing this problem here: I'm designing my second larger batch of WCF services which external parties will consume.

For the first batch, I used a strict "contract-first" approach: manually created the WSDL and XSD files, and from those, generated my service and data contracts and implemented my WCF service.

Worked ok, I was able to use the WSDL and XSD to produce useable documentation (xs3p and other transformations) - but creating and maintaining WSDL and XSD manually is a MAJOR pain, and the generated WCF service and data contract files aren't pretty to look at, either....

So for my second batch, I tried to go the other route - create my service interface in C# and adorn it with ServiceContract and OperationContract attributes, create my classes that make up my request and response objects in C# and add DataContract and DataMember attributes to them - works nicely, my C# code now looks great.

But how do I create a useable documentation from this?? I compiled everything into a DLL and used svcutil -t metadata on it - but the resulting WSDL and XSD somehow aren't complete (WSDL is missing and elements), and they're not "connected", e.g. the WSDL doesn't know where to physically look for the XSD, so my documentation is pretty lousy.......

Sure, I could just deploy the service on a dev box and tell everyone to come grab their WSDL and XSD via a URL - but that's not the way these projects go :-( I need to be able to produce a useable, printable documentation - HTML, PDF or CHM or something alike....

How do you do this?? Both approaches seem to have big and painful drawbacks..... am I missing the "golden third way" ?? If so: what is it?? :-)

Marc

Answer 1

Marc,

I don't have an answer for you but would like to know, when you followed the 1st route, how did you manage to get the WCF service contracts to match your hand-crafted WSDL? Did you follow the same conventions that .Net use when generating a WSDL? We're facing severe issues with the WCF service not matching our contract.

tia

Leon

Answer 2

This is my workflow:

1. Write code for service and data contracts up to the point you're satisfied that the web service interface exposes most of the functionality you want it to expose (I'm talking only about interface classes and data classes, not implementations).

2. Compile the code so that you have the latest .dll for the web service.

3. Generate WSDL and data contract XSD files using svcutil.exe, for example:

   SvcUtil.exe /target:metadata /directory:Wsdl bin\Debug\YourWebService.dll

4. This will create a Wsdl directory containing those definition files. You should add these files to your source control, since they are now the basis for developing and maintaining your web service.

5. Every time you change the WSDL/XSD, you have to regenerate the C# service/class code, example:

   SvcUtil.exe /target:code YourWebService.wsdl YourWebService.xsd schemas.microsoft.com.2003.10.Serialization.xsd

6. (you might need to specify some additional command line options for getting the C# code the way you like it, check the svcutil docs).

7. You will probably want to throw away the old C# code (from the step 1.), since it's not really relevant any longer.

This way you have the total control of the WSDL, which means easier life for clients which use your web service, since there is less chance of some nasty surprises if WCF's WSDL generation engine changes in the future (which is almost certainly going to happen, based on previous experience).

The drawback is that you have to manually tweak WSDL code.