SandCastle and DocProject

Having used SandCastle for generating all my code documentation for almost a year. I must say that it have done a great job for me (not sure for those consuming the documentation), as everything is automated using NAnt with CruiseControl.NET.

However, the initial setup is not easy, as there are a few things that need to be installed before it can work. Starting with the GUI will be the easiest but it cannot be automated. Therefore, the integrating of the generating of the documentation using NAnt is one of the option. CodeProject have any excellent article with a sample of a NAnt script for generating the help file. Be warned that the script is very long and might take a while to understand and know what changes are required for it to work in your environment.

Recently, due to too much parallel development work, this documentation have to be generated ASAP, so that my colleagues can consume them. Developing a project with distributed teams in different geographical location and time zone is a challenge and this document need to be shared in a more efficient way. So I was searching around and found DocProject which can publish the help file as a web application. Interestingly, I did not see much blog talking about the use of the DocProject, so decided to shared some opinions about it as I think it just great tool to have.

With the used of this tool, hopefully it will help to save my colleagues having to download a new version of the help file every time it is generated by SandCastle. To get the DocProject running is much easier than I thought as it integrated with the Visual Studio, except for a few more things to be installed. Of course the only setback I have now with this tools is that I need to integrate with CruiseControl.NET and using NAnt with msbuild task is sweet and easy except that I do not want to install VS on the CC server. Looking at the roadmap of DocProject, I do hope that this is part of the pirority.


Looking at the above image the whole NHibernate API is clearly visible. This is all done by creating a DocProject and include the NHibernate dll to the VS->tools->options->DocProject->External Sources. For those that are interested to provide some documentation to your code, I do urge you to look into the DocProject. Meanwhile, I will continue to try if I can setup the documentation generation with NAnt without the installation of VS but just the SDK.

Upgrading to NANT 0.86 for .NET 3.5

Recently, having to upgrade the project I am working on from .NET 3.0 to 3.5, I did not realize that the NANT 0.85 is unable to support the building of .NET 3.5 project till I tried to build the project. In order to continue to automate the build process of the project, NANT 0.86 beta 1 have to be used. During the upgrade I have hit some problem and will like to share the problem I have and how to workaround them.

If you are using previous version of NANT 0.85 to build on .NET 3.0 and 2.0 project, you need to download the NANT 0.86 and unzip to your machine. Next, you will be required to change the environment variable of the NANT path to the bin folder location of the latest version of NANT. Restart your computer and add the following "<property name="nant.settings.currentframework" value="net-3.5" ⁄>" just after the project of the build files. This is enough for you to get your .NET 3.5 project built.

For project involving the reference of System.ServiceModel.dll, you might get some error message will trying to build the project. You will be required to change the referenced dll from the above mentioned to System.ServiceModel.Web.dll which usually can be found in the “Drive:\Program Files\Reference Assemblies\Microsoft\Framework\v3.5\”.

Also, the nunit2report is also not working with the current version of NANT. For those preferring to run nunit test report with the nunit2report, you can just copy the following list of files found in the NANT 0.85 bin folder to the 0.86 bin folder and it should work fine:

1. NAnt.NUnit2ReportTasks.dll
2. i18n.xsl
3. NUnit-Frame.xsl
4. NUnit-NoFrame.xsl
5. toolkit.xsl

With all this minor changes… everything should be up and running.

Assembly analyzer

Release of Framework Design Studio!

Trying out this new tool to compare a class in two different assemblies, red and green colour are used to differentiate the line of codes on what is added and removed respectively. More significantly, what is inherited was also displayed in grey and this greatly improves the analyzing of the assemblies without hunting down other class to get a picture of what is inherited. Comments can also be added during the review of the assembly and even be exported. This will definitely be helpful when code reviewing is required.

The diff GUI is something difference from the usual text comparison tools (such as beyond compare and win merge) where the two different versions are displayed side by side. Personally, I am still trying to get use to it, as it does not allow me to compare the difference on each line of code but rather it will displayed line in different colour. The tree can also provide some information on whether any difference found in each class. This will speed up on the filtering process since an assembly has many classes and going thru each one will be time consuming.

On the other hand, the Reflector for .NET has been my favorite assembly analyzing tool so far as it allows me to analyze assemblies and even the resources files in it. Another great feature provided, is the analyzer also show the dependency on other assemblies. With these two great tools available, they will definitely improve the life of many developers. All thanks to everyone involved in getting these two great tools developed. For those that still unaware of these two tools, I do urged you to check them out if you ever need to analyze any assembly for good.