Building on a Foundation of SandCastle

SandCastle is a promising utility that’s supposed to do something useful with the XML comments in your C# code. I am a professional programmer and I have an appreciation for how much work all of this is. I am about two and a half hours into this process, and I'm hoping that my experience might help others, so I'm taking the time to write it down.

The "out of box" experience with Sandcastle is really disappointing. I started with trying to use NDoc, found out it only works for 1.x versions of .NET and finally with a bunch of searching around ran into Sandcastle. After installing Sandcastle and another program to provide a GUI for Sandcastle (since it doesn’t have it’s own), I started to build a project figuring that I finally had everything I needed. I got this error:

BUILD FAILED: Unable to find XML comments file: C:\src\\bin\Debug\Unknown.xml

I searched for that error message, and found a posting on a SandCastle Forum. There was a snide reply saying basically RTFM... Ok, I'm a big boy, I go to RTFM... After going through four pages of information that I really don't care all that much about, I get to "Setting Up Your Projects" in the SandCastle help file and set the output of my Visual Studio Project to emit the xml file as instructed there.

Then I have to sign up for CodePlex. Sigh. Yet another site that thinks it's so important that it needs yet another password.

I then go into Sandcastle's GUI (After fighting with the fact that the help file viewer was brought up modally, grrr...) and Edit the XMLComments path to refer to the file that I just generated. I go and generate again...

====

Error: Unresolved assembly reference: (, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null) required by

Last step completed in 00:00:02.1094

BUILD FAILED: Unexpected error in last build step. See output above for details.

====

So, now what? Back to the forums, where I'm given a little more information, and told to RTFM again.

And then I find that Codeplex has a limited posting length as I'm trying to explain all this to the author. Sigh.

So I go back and mess around with “the project's Dependencies property.” I figure out eventually, that THIS project means the project inside of SandCastle, not the project in Visual Studio… where I just was. And after messing around a bit, I get to the following error:

BUILD FAILED: Access to the path 'C:\src\kanderson\Libraries\\bin\Debug' is denied.

At this point, I’m giving up for the day... maybe I’ll get back to it, and maybe I’ll just write my own little C# program to deal with the one XML program I’m dealing with.