Building and Deploying Using NAnt

NAnt is a deployment tool for building and deploying .NET projects. While there's nothing wrong with building projects from within your IDE, which is most likely Visual Studio, when working in a corporate environment, it can be useful to have your source code available for download from your source repository (Source Safe, for example) in a format that allows it to be built without such an IDE. NAnt is a fairly standard .NET tool for such a task.

Where to Find NAnt

The NAnt project web site is at http://nant.sourceforge.net where you can download the latest set of binaries. I would also recommend that you download the latest contrib tasks from http://nantcontrib.sourceforge.net/ because several useful tasks are not included in the core NAnt build.

Building Your Build File

NAnt is basically an executable that is driven by an XML file containing instructions on how to build your project. Writing the XML file is a task that can take anywhere from a few minutes to a few days, depending on the complexity of your project. You'll also need to become familiar with a few of the common elements available in NAnt.

A good way to learn the XML tasks is to download a visual GUI for writing your build file. NAntbuilder is a really good UI (available from here) which is free for a 30 day trial period. It looks and feels a lot like Visual Studio, with drag and droppable tasks which build the XML for you. You can also look at and edit the XML code directly. By the end of your 30 day trial, you can choose to buy and register the software, but I'm betting that you will have learnt a lot of the necessary XML by that time so that you'll feel reasonably confident writing the XML yourself by that time.

You will probably want to get a little bit of help if you choose to do the latter and limited intellisense help can be gained in Visual Studio by registering the NAnt.xsd file in the Visual Studio schema directory. Check out this link for instructions on how to do this.

Basic NAnt Tasks

The top level element in the common build file is the <project> </project> element, which looks like this:

<project default="build" 
xmlns="http://nant.sf.net/release/0.86-beta1/nant.xsd"></project>

The default="build" attribute points to the default target for the build file. There can be as many targets as you want in your build file, which provide a useful means for modularising your build. For example, you could have a target that creates an output folder and builds your .cs or .vb files into that folder. You would call this target "build". You may then have another target called "deploy" that then moves the files into a specified deployment folder. Targets look like this:

<target name="build"></target>
<target name="deploy"></target>

etc.

Nested within the target elements are then all of the elements that describe the tasks you want that target to accomplish when called.

Common and powerful tasks (further reading will be required on your part) are <csc/> for calling the C# compiler, <exec/> for executing just about any executable you can call from the command-line, <if/> for nesting conditional tasks, <call/> for calling other targets, <mkdir/> for making directories, and <echo/> for outputting messages during the execution of the build file.

Another extremely useful part of NAnt is the ability to declare variables, called properties:

<property name="web_site_target" value="./Web Compiled" />

You can refer to your variables using the syntax ${variable_name} as follows:

<property name="business_objects_target" value="${web_site_target}/bin" />

Because NAnt executes the build file in a sequential order, you can only refer to properties that have already been declared earlier in the execution of the file, but other than this cautionary note, properties should be used as much as possible. If, for example, you find yourself hard-coding paths to files into tasks such as the <csc/> task, which, as you might imagine runs the C# compiler, it is always better to put that path into a property and then use the property in the task. The main reason for this is that properties can be set by the user when running NAnt from the command line.

I guess I could go on for pages documenting all of the different tasks available to NAnt, of which there are many. But this isn't a NAnt tutorial. If you don't mind a bit of reading, check out a fairly comprehensive tutorial here.

A Couple of Gotchas I Discovered Along the Way

1) Put Nant somewhere easy to remember

Once you've downloaded and unzipped the NAnt binaries zip, put the extracted folders somewhere predictable, like "C:\Program Files\Nant" for example.

2) Register NAnt's path on your Path

What? - Path is one of your Environment variables (in Windows) that contains common file paths. If your Nant program folder is included in the Path Environment variable, you'll be able to execute NAnt from the command line regardless of which directory you're currently in without having to type the full path to the NAnt executable. To change your Path Environment variable, you'll need to go into "System" from the Control Panel, click on the Advanced tab, and then click the "Environment Variables" button and then scroll down to the "path" system variable. I'll assume you can figure the rest out from there...

Caution: Don't mess up your existing Path settings. Since the path will be fairly long, I would recommend copying its contents into a text editor, such as Notepad where you'll be able to save it as a txt file as a back up. Add the path to NAnt to the end of the path, separated from the rest of the path by a semi-colon (;), copy the new path back into the environment variables dialog and save it away.

3) Include Nant and/or Nant.Contrib in your source

Unless Nant is already well established in your development environment and you can rely on the target machine having NAnt installed on it, you might find it easier to simply include NAnt in the download than write detailed instructions in a readme.txt file to explain how and why to download NAnt.

4) Create a build.bat file rather than relying on the user to correctly run NAnt

A build.bat file will allow you to make sure that NAnt is corrently called with any additional parameters in the command line, such as the target .NET framework.

5) If using additional tasks from Nant.Contrib, or any other external Nant libraries, use the <loadtasks>task.

The <loadtasks> element allows you to add a reference to the library(ies) that you want need to use within the NAnt build. The alternative is to use the -t switch when calling NAnt (ideally from a batch file). The syntax is -t:net-2.0 for .NET framework 2, -t:net-3.5 for version 3.5, etc.

CodeProject