Any comments on Sandcastle?

By Henning Eiben in .Net, Programming 0 Comment

To be honest – even though I installed Sandcastle quite a while ago I didn’t really got around to use it.

But since Kevin Downs announce the discontinue of NDoc I had to come up with some kind of replacement. So how about this castle-thinggy? So I hooked up with some MSBuild-script to get my documentation rolling.

Some 30 minutes later – and the vast peak of 650 MB of RAM which where consumed by the processe (thanks to Process-Explorer for providing this insight!) I finally had some nice CHM-file representing the documentation of one of my projects. I was already quite exited to finally see some light of documentation again.

When I looked at the documentation I realized, that everything from my projects was neatly documented – just as promised; well – everyting? Not really, there was some small piece missing: like all the code-comments that where supposed to be in the documentation!!!

Well, what the heck was BuildAssembler doing the last 30 minutes? It sure as hell was doing any documentation!! So after a periode of denial and disbelief I finally started to do some research on why this strange behavior would be.

It turned out, that Sandcastle would expect a comments.xml file in the directory from which Sandcastle is being started (not the directory where the tools reside!). OK – so what next? I don’t have just one XML-file containing my documentation, and it’s not even called comments.xml.

After digging deep into the config-files of sandcastle I finally figured that I could change comments.xml in the sandcastle.config and replace that with an expression (containing wildcards) which would identify my own XML-files.

So some 30 minutes later I finally found myself with a brand new documentation …

MSBuild vs. NAnt

By Henning Eiben in .Net, Programming 0 Comment

OK, this is probably the 1.000 blog post concering whether to choose MSBuild vs. NAnt.

I had quite a though time fighting my build-environment with MSBuild, after starting out with NAnt (even before MSBee was available). But not I got a couple of things worked out: I can build and do some sort of xcopy-deploymend, I can run NUnit and NCover (even though I had different results from running the gui-runner and the automated nunit-target from my MSBuid-script ?!). But adding more features to this build-process seems be a much bigger burden, that doing the same with NAnt.

So I figured: I will use NAnt for the overall build-process and I will only consider MSBuild for build my solution. I’ll see how this side-by-side usage will work out.

Sandcastle released

By Henning Eiben in .Net, Programming 0 Comment

Finally! On Janury 16th Sandcastle was released!! So good bye CTP and hello Release!

Make sure to grab your copy on codeplex!

A big stop forward is also, that there are some examples to get your help-doc started from within MSBuild. Previously I used some MSBuild scripts, which are also available on codeplex, but since they were tailored for a specific CTP (the march 2007 CTP), they didn’t work with the last november CTP anymore.

OK, so I’m looking forward to get all my code documented :); a quick test on my recent project at least showed no errors on the first run … that’s quite impressive!

Versioning Assemblies with MSBuild

By Henning Eiben in .Net, Programming 0 Comment

OK, so I try doing more with MSBuild … like: bumping the version number of my assemblies 🙂

So far so good – so let’s get startet. First of all you need to grab a AssemblyInfoTask extension for MSBuild. Just install it and you’re all set.

Next you have to modify your *.csproj file. Just add:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\AssemblyInfoTask\Microsoft.VersionNumber.Targets"/>

to the end of the file. OK, this could already be all. But wait – what are all those errors in my newly build?

First I use subversion for source-control, so I have an addition AssemblyInfo.cs somewhere in my .svn folder-structure. This is not working with the AssemblyInfoTask :(. So navigate to your ‘$(MSBuildExtensionsPath)\Microsoft\AssemblyInfoTask\Microsoft.VersionNumber.Targets’-file and edit it (with notepad or whatever). Then lookout for the itemgroup defining the files to process and modify it to exclude any .svn folders. This could look like this:

<!-- The items that get processed by the task -->
<ItemGroup>
<AssemblyInfoFiles Include="**\AssemblyInfo.*" Exclude="**\.svn\**\AssemblyInfo.*"/>
</ItemGroup>

OK, for now you’re set – it compiles!! At least kinda. So next you’ll get some error about the version-number not being correct. Well no error without a fix :). There have been quite some discussions about this problem and a lot of various fixes. Well, Neil explains in his blog about why this is, and makes the point “So, I’m sad to say, we will be stuck with 16-bit build numbers forever.”. So this means no cure for this error.

OK, for me I just wanted to control the version number of my assemblies from outside visual studio. So I want to fix the version number. So I though adding the properties:

<AssemblyBuildNumberType>NoIncrement</AssemblyBuildNumberType>
<AssemblyFileBuildNumberType>NoIncrement</AssemblyFileBuildNumberType>

would do the trick. But far from right. I still would get at least incremented revisions. Looking at the code I noticed that:

<AssemblyRevisionType>NoIncrement</AssemblyRevisionType>
<AssemblyFileRevisionType>NoIncrement</AssemblyFileRevisionType>

would solve my problems. So my complete PropertyGroup looks like this (with a version number of 2.1.1.1 for my Assembly, and 1.0.0.0 for my File-Version):

<PropertyGroup>
<AssemblyMajorVersion>2</AssemblyMajorVersion>
<AssemblyMinorVersion>1</AssemblyMinorVersion>
<AssemblyBuildNumber>1</AssemblyBuildNumber>
<AssemblyRevision>1</AssemblyRevision>
<AssemblyRevisionType>NoIncrement</AssemblyRevisionType>
<AssemblyBuildNumberType>NoIncrement</AssemblyBuildNumberType>
<AssemblyFileRevisionType>NoIncrement</AssemblyFileRevisionType>
<AssemblyFileBuildNumberType>NoIncrement</AssemblyFileBuildNumberType>
</PropertyGroup>

You might notice that I don’t set the Assembly-File version in the PropertyGroup. This is still managed from visual-studio (you don’t have to understand why I would wanna do this).