Generate WCF documentation using SandCastle

Question

I'm trying to generate external documentation for a WCF service using SandCastle. How can I tell SandCastle to use the WCF attributes like ServiceContract for naming the functions and entities instead of the names they have in the assembly?

Answer 1

OK, the following will not be a direct answer to your question, but maybe it'll help anyhow.

If you're saying you want to create "external service documentation", that external documentation is probably not really meant for .NET developers and you may not even want that implementation detail to be (necessarily) visible. So the typical API style documentation might not be suitable anyway.

Next to that API style documentation Sandcastle also supports what is called "conceptual documentation". Which is basically "free text", of course in a certain XML dialect. I'll come back to that later.

OK, you would first generate a WSDL file for your service interfaces (usually by appending ?WSDL to the service's URI or using SVCUTIL.EXE on your service assembly, which is better suited during an automated build).

Then comes the hard part. You'd need to create something that converts the WSDL to MAML documents (An XML stylesheet comes to mind). MAML (Microsoft Assistance Markup Language) is actually the so to say core format used by Sandcastle.

I think your best bet would be to then use the Sandcastle Helpfile Builder to create project out of these files to create a CHM, HTML-pages or whatever from it.

Basically, once you have the MAML documents, you're back in the "standard" Sandcastle tool chain.

I know that sounds like quite some work, and probably it is. I have done something comparable in the past, where I would use SMO to query a SQL Server database to generate MAML documents for the tables, procedures, etc. to generate reference documentation. Actually, it worked out quite nicely and in the end the effort was not too bad.

Anyway, I'll keep that question stared in case there actually exists an "off the shelf" solution :-)