Question

Folks,

I’m creating a new WCF Service and started with my Service interface. Looks something like:

   public interface ISomethingService     {         /// <summary>         /// some description         /// </summary>         /// <version>2.13.0</version>         /// <copyright>2009 by myself</copyright>         /// <author>Marc Scheuner</author>         /// <param name='request'>The request object</param>         [OperationContract]         SomethingResponse GetList(SomethingRequest request);     } 

Now, I also created some data contracts in another file describing the SomethingRequest and SomethingResponse messages.

I compiled my project and fired up svcutil.exe to extract the metadata (WSDL and XSD) from the DLL – but I can’t seem to figure out if there’s a way to get all my comments and explanations into the WSDL/XSD into / nodes.

Am I blind for yet another obscure svcutil.exe parameter, or is there really no way to generate this documentation in the metadata automatically??

EDIT: ok, based on Marc Gravell’s answer, the comments and documentation strings aren’t in either the compiled DLL, nor available over the MEX metadata exchange protocol (pity!).

SO THEN: How do you document your WCF services, if you need to give a third-party the information they need to access your service?? Is there a ‘NService’ or ‘Sandcastle for WCF’ tool around that would scan my WCF service library and construct the WSDL and XSD from source code, including the annotations??

Can’t seem to find a whole lot of tools and ways to do this – to my big surprise, honestly….

Marc

Answer 1

svcutil.exe consumes the ‘mex’ API, and only has access to a subset of the metadata. Comments aren’t included (nor, IIRC, is [DescriptionAttribute] to any great extent).

You might have to rely on external documentation (i.e. a help page / dead tree). One other option (although it breaks a number of pure SOA rules) is to ship the entities / interfaces in a dll + xml; svcutil (and the IDE) can re-use matching types from existing assemblies.