documenting WCF API errors (Best way)

Question

I know, it's too late now and we should have created all possible error list before. We couldn't do this before bcse we were using another API to server our API and that third party API provided us german messages for any error.

Now one of our client has requested to provide them the list of possible error messages for them to handle it accordingly.

Could you please provide me ideal way to document the error lists. I was about to start with an excel spreadsheet but reckon, there should be some better way.

Answer 1

In WCF you should be using a FaultException. Effectively you derive from FaultException and these will be serialized over the wire.

That way your service will correctly pass exceptions down the wire (eg. serialized to SOAP) which your consumers can deal with.

That's why it's there. But given you are in production you might not have a choice.

Answer 2

There is a standard C# XML documentation syntax you could use, explaining what each method can throw. See: http://msdn.microsoft.com/en-us/library/b2s063f7(v=VS.100).aspx

You can then present the docs using a tool such as Sandcastle , which will spit out MSDN-style documentation.

Tools like GhostDoc can help you write these more quickly.

Since you're already in production, I'd write a patch for the code and shelve it in source control.