Gunnar Peipman's ASP.NET blog

ASP.NET, C#, SharePoint, SQL Server and general software development topics.

Sponsors

News

 
 
 
DZone MVB

Links

Social

Using Sandcastle to build code contracts documentation

In my last posting about code contracts I showed how code contracts are documented in XML-documents. In this posting I will show you how to get code contracts documented with Sandcastle and Sandcastle Help File Builder.

Before we start, let’s download Sandcastle tools we need:

Install Sandcastle first and then Sandcastle Help File Builder. Because we are generating only HTML based documentation we upload to server we don’t need any other tools. Of course, we need Cassini or IIS, but I expect it to be already there in your machine.

Open your project and turn on XML-documentation for project and contracts.

Now let’s run Sandcastle Help File Builder. We have to create new project and add our Visual Studio solution to this project. Now set the HelpFileFormat parameter value to be Website and let builder build the help.

Sandcastle Help File Builder

You have to wait about two or three minutes until help is ready. Take a look at your documentation that Sandcastle generated – you see not much information there about code contracts and their rules.

Enabling code contracts documentation

Now let’s include code contracts to documentation. Follow these steps:

  1. Open Sandcastle folder and make copy of vs2005 folder.
  2. Open CodeContracts folder (c:\program files\microsoft\contracts\) and unzip the archive from sandcastle folder.
  3. Copy all unzipped files to Sandcastle folder.
  4. Create (yes, create new) and build your Sandcastle Help File Builder documentation project again.
  5. Open help.

In my case I see something like this now.

Code contracts are documented

As you can see then contracts are documented pretty well. We can easily turn on code contracts XML-documentation generation and all our contracts are documented automatically. To get documentation work we had to use Sandcastle help file fixes that are installed with code contracts and if we had previously Sandcastle Help File Builder project we had to create it from start to get new rules accepted. Once the documentation support for contracts works we have to do nothing more to get contracts documented.

Comments

Alexander Nowak said:

Hello,

I was wondering which version of Sandcastle  & Sandcastle Help File Builder you used for the demostration.

I can not get it to work! Sandcastle comes complaining about something he can not find during transformation.

I'm using Sandcastle-June 2010 Release (Version 2.6.1062.1) & SHFB 1.9.1.0.

Thanks in advance.

Best regards,

Alexander

# August 5, 2010 6:42 AM

DigiMortal said:

I was using earlier release and everything worked fine. You have to copy some files from code contracts folder to sandcastle folder to make sandcastle able to extract contracts information.

# August 10, 2010 5:39 PM