Nant Task for Sandcastle

I have been thinking of writing a Nant task for Sandcastle for quite some time so I decided to knock something up . I have been fairly busy at work and havent been able to spend time on this. As i find some time on the train I just finished this piece of code.

I am quite a fan of Nant and the Nant contrib project has a task for NDoc which kind of inspired me to do one for Sandcastle. Sandcastle supports the new frameworks in .Net quite well and most people who were using NDoc would have migrated to Sandcastle due to its capabilities for build purposes.

This task is intended to allow users who do not want to use sandcastle command line builder in there nant scripts as an external process. The logging of this task and the sandcastle output is also streamed into the nant log.

I have based my task schema on the bare minimal that will require direct configuration in nant. In any case you should be able to do all the configuration in the sandcastle project. What’s shown below is purely a because i am a developer and I need these features and so i think everyone is going to be happy with it :). '

The following readme is placed in a text file along side the installer zip file.

The Sandcastle for task is built using the following components
Nant 0.86
Sandcastle Help File Builder
Sandcastle UI Builder

The core components required by the task are installed by the installer.

The installer allows you to install the task into a folder that you choose but does not check to see if Nant is installed in the same directory
Generally C:\Program Files\Nant\bin
Installing the task in the same folder as Nant is the only scenario that has been tested.

The path of nant should be added to the path variable as instructed in the Nant installation instructions

In addition to installing the task the following configuration for the Nant.exe.config file needs to be added.

Under the elements
<configuration>
...<nant>
......<frameworks>
...........<platform>
................<task-assemblies>
                    <!-- Nant sandcastle task-->
                  <include name="NAnt.Contrib.Tasks.Sandcastle.dll"/>
If you wish to add the Sandcastle task into another folder, the Nant probing paths need to be set to look at this folder. It is not recommended however

Source code is also provided and feel free to customise it or edit it , The source code is present at Install folder\sandcastle task\Src

I have tested this on my system by installing sandcastle, nant and this task and it works fine. Obviously i am saying “Works on my machine”, if you see any problems using it please let me know about it.

The Sandcastle task schema for the Nant script should be as below, project and output are the only two required attributes,

<sandcastle 
    project="${Sandcastle project file path}" 
    output="Output location for Sandcastle files">

    <showMissing 
        remarks="false" 
        params="false" 
        returns="false" 
        values="false" 
        namespaces="false" 
        summaries="false">
    </showMissing>
    
    <document 
        internals="false" 
        privates="false" 
        protected"="false" 
        attributes="false"
        copyrightText="" 
        feedbackemail="" 
        footer="">
    </document>
</sandcastle>

e.g Nant build file

<?xml version="1.0"?>
<project name="Hello World" default="build">
    <property name="projfile" value="C:\Documentation.shfb"/>
     <target name="build">
        <sandcastle project="${projfile}" output="C:\Documentation\Help">
<document copyrightText="Copyright@ TSQLDOTNET Limited" feedbackemail="srinivas.s@tsqldotnet.com"/>
 </sandcastle>
    </target>
 </project>

Link: Nant Sandcastle Installer

The download consists of the prerequisites hence it is bulky at 40MB, The prerequistes include Sandcastle installer , Win 3.1 installer and DotnetFx

Cruise Control .Net farms

In the present organisation that i work for , we work as four teams continuously developing code and checking it into TFS and as a consequence of this we have adopted the process of continuous integration using Cruise Control.Net . Well using Cruise Control.Net along side Nant to have automated build processes is nothing new, but what we have achieved and are planning to achieve is hopefully a unique implementation of a automated build platform. We have about nine different projects having there own automated builds and since Nant is not able to scale across multiple CPUs, the resources on the server are underutilized and wait times have increased considerably. So as a solution to this we have not installed two instances of Cruise Control on the main build server one called the current build which developers use to build binaries and test , while the nightly build runs on a scheduled basis generating the end product installers. Sometimes people may still need a setup and nightly build allows forcing builds manually using the CC Tray application.

So to achieve this there were a few bottle necks we had to work around.

• Cruise Control does not install two instances completely, for starters it does install the windows service for itself when you install a second instance. So you have to manually install the service using the installutil.exe in the .Net framework.
• Since you will have two instances building simultaneously you will need to isolate the identities under which these build run and the physical locations of these builds.
• The cruise control server web dashboard also has to be configured manually as separate virtual directories.
• The cruise control manager for each instance has to be configured to use a different port, the default install of CC.Net using 21234, we could use something like 21244 as a series . In case you have a firewall make sure your network admin allows requests to this port (CC Tray uses these ports to communicate with the server)

Now that said we have a single server which has two instances of Cruise Control, The build outputs are copied on to a network share. We now have another build server where we are going to replicate the set up of the first server and then split the CC projects across the two physical servers to share the load of the builds. It all looks simple, but thanks to the guy who authored a Templated build where I have been able to enhance it to achieve the following,  We have been constantly updating the build or the last one year and we are close to achieving end to end automation for the product, so when we check-in code to TFS , we are able to dish out a CD ISO image for the products to the network share in the nightly build. We also have switches as properties in the build scripts which can allow the current builds to create setups incase the nightly build is overloaded. Due to constant development work and support issues we have to squeeze work like this as part of our non functional sprint work. But then scrum treats engineering work as Non functional and is rightly justified in doing so.