When you think ASP, think...
Recent Articles
All Articles
ASP.NET Articles
Message Board
Related Web Technologies
User Tips!
Coding Tips

Book Reviews
Sample Chapters
Commonly Asked Message Board Questions
JavaScript Tutorials
MSDN Communities Hub
Official Docs
Stump the SQL Guru!
Web Hosts
Author an Article

ASP ASP.NET ASP FAQs Message Board Feedback ASP Jobs
Print this Page!
Published: Wednesday, December 1, 2004

A Brief Introduction to NAnt

By Eric Desch


NAnt is a free .NET build tool based on Ant (a build tool for Java). NAnt, like Ant, is similar to Make in that it is used to generate output from your source files. But where Ant is Java-centric, NAnt is .NET-centric. NAnt has built-in support for compiling C#, VB.NET, and J# files and can use Visual Studio .NET solution files to do builds. NANt also has built-in support for NUnit and NDoc (.NET version of JUnit and JDoc, respectively).

NAnt is a useful tool for automating the build process. The build process can include tasks such as compiling source code and resource files into assemblies, running unit tests, configuring build-specific settings, and so on. The benefit of tools like NAnt is that they help automate the build process by providing enough power and flexibility to highly customize build actions for specific applications. This article provides an overview of NAnt, including its purpose, how to download and install NAnt, using NAnt, and other NAnt essentials. Read on to learn more!

- continued -

What is a Build Tool?

As its name suggest, NAnt, or any tool labeled a "build tool" is a tool that you use to build your source code and resource files into assemblies. Sounds obvious? Maybe, but what is involved in making a build? Here are some common tasks you might perform when doing a build (your builds might exclude some of these steps or include additional steps):
  • Get the latest source from source code control
  • Configure the build (you probably want to put the output of the build into a directory that identifies the version of the software, the build number, and whether or not this is a debug build)
  • Compile the code
  • Run unit tests
  • Create documentation from source code comments
  • Include non-code output files in the output of the build (images, .aspx files, configuration files, etc)
  • Package the output for deployment
Build tools enable you to automate all these steps. Instead of manually running commands and copying files, you can set everything up in a build tool and have it all run automatically.

Why use NAnt?

Why use NAnt? Of course you can build from within Visual Studio, but as described above, build tools like NAnt offer you much more power and flexibility. For starters, NAnt doesn't require Visual Studio .NET. As long as you have the .NET Framework, you can do builds. Here is a partial list of things you can do with NAnt:
  • Use its built-in support for CVS updates and checkouts to automatically get the latest source files
  • Use it to configure builds
  • Use it to compile .NET languages, including C#, VB.Net and J#
  • Use it's built in support for NUnit to automatically run unit tests
  • Use it's built in support for NDoc to automatically create documentation from source code comments (currently C# only)
  • Use it to copy non-code output files to the build directory
  • Use it to package builds into .zip files (or even .msi files) for deployment
Additionally, NAnt is extensible. It allows you to write your own tasks (tasks are described later in this article) or to use the <script> task to embed any .NET code into your build files.

An example of NAnt's capabilities were demonstrated in a project I recently worked on. In this project I needed it to be built for development, stage, and production environments and the configuration data (connection string, for example) differed for each environment. I used NAnt to do the builds and used the <style> task to transform XML files with XSLT to generate the various Web.config and App.config files. A much better solution than editing configuration files by hand for each environment.

Downloading and Installing NAnt

NAnt is available for free from http://nant.sourceforge.net. Follow these steps to download and install NAnt:
  1. From http://nant.sourceforge.net, click the link for the current stable release. Your browser displays the NAnt project on sourceforge.net.
  2. Click the link for the build that you want (at the time of this writing, the latest stable build is nant-0.84.zip).
  3. Click the download icon next to the mirror closest to you. You should be prompted for a location to save the .zip file. If not, click the link at the top of the page.
  4. Save the .zip file.
  5. Unzip the file and save its contents to a suitable location (I use C:\nant-0.84).
  6. Update your PATH environment variable to include <nant dir>\bin (for my setup, that's C:\nant-0.84\bin).
That's it. Open a command window and enter: nant -help to verify that everything is set up properly. If you see the NAnt help screen, the PATH environment variable is setup correctly.

One note: NAnt may be configured out of the box to use a different .NET Framework version than you would like. For example, NAnt 0.84 is configured to use .NET Framework version 1.0 by default. If you only have version 1.1 of the .NET Framework installed on your machine and you try running NANT 0.84 on a task that requires the framework, you will get an error similar to this one:

[csc] C:\WINDOWS\Microsoft.NET\Framework\v1.0.3705\csc.exe failed to start.
                        The system cannot find the file specified

To change the default framework version, you need to edit NAnt.exe.config in the <nant dir>\bin directory. Change the default argument in the platform tag to the .NET Framework version you would like to use as the default. The following example sets the default Framework to use to 1.1:

    <platform name="win32" default="net-1.1">

In the event that you want to use a different .NET Framework version in one of your build files, you can override his setting by setting the nant.settings.currentframework property:

<property name="nant.settings.currentframework" value="net-1.0" />

How Does it Work?

NAnt is a command-line application that acts on build files that you write in XML. Each build file contains one project and any number of properties and targets. A property is a variable and a target is a set of tasks. An example is worth a thousand words, so here is Hello World as an NAnt build file:

<?xml version="1.0"?>
<project name="Hello World" default="hello">
    <property name="hello.string" value="Hello World" />
    <target name="hello" description="Echoes 'Hello World'">
        <echo message="${hello.string}" />

NAnt looks for build files in the current directory with a .build extension. If there is more than one build file in the current directory, NAnt looks for one named default.build and, if present, uses it. You can explicitly specify the build file to use with the -buildfile:<filename> command line argument.

All NAnt build files require one (and only one) <project> tag. In the 'Hello World' example, the <project> tag contains the default argument. The default argument specifies which target NAnt is to execute by default. In this case, NAnt will execute the hello target by default.

The 'Hello World' example defines one property and one target. The property is named hello.string and its value is 'Hello World'. (Properties don't have to be named with periods, but often are in NAnt build files). The 'Hello World' example's one target is named hello and it contains one task. The <echo> task echoes the string indicated by the message argument. The syntax ${hello.string} may be confusing at first, but this syntax is simply telling NAnt to substitute the value of the hello.string property in its place.

Assuming you named the 'Hello World' example build file default.build, you would simply enter nant at the command line to build it:


(You could specify the 'hello' target on the command line (C:\> nant hello), but since this is the default target, this is unnecessary.)

How About a More Practical Example?

Here's a build file (based on the excellent article by Giuseppe Greco, Building Projects With NAnt) that compiles a HelloWorld.cs source file. In addition to the build target, it includes a debug target. This enables you to specify whether or not this build should including debugging information:

<?xml version="1.0"?>
<project name="HelloWorld" default="build">
  <property name="project.version" value="1.0" />
  <property name="project.config" value="release" />

  <target name="init">
    <call target="${project.config}" />

  <target name="debug">
    <property name="project.config" value="debug" />
    <property name="build.debug" value="true" />
    <property name="basedir.suffix" value="-debug" />

  <target name="release">
    <property name="project.config" value="release" />
    <property name="build.debug" value="false" />
    <property name="basedir.suffix" value="-release" />

  <target name="build" depends="init" description="compiles the source code">
    <property name="build.dir" value="${nant.project.basedir}/${nant.project.name}_${project.version}${basedir.suffix}"/>
    <mkdir dir="${build.dir}" />
    <csc target="exe" output="${build.dir}/HelloWorld.exe" debug="${build.debug}">
        <includes name="HelloWorld.cs" />

Things to notice about this build file:

  • There are targets for debug and release. You include these targets on the command line to specify the type of build configuration. Notice that release is the default configuration.
  • The build target has a depends argument. This tells NAnt to make sure the init target is up to date before calling the build target.
  • The init target calls another target explicitly. In this case, it calls either the release or debug target.
  • The output is put into a directory that is named with the project version and configuration (1.0_HelloWorld-release or 1.0_HelloWorld-debug)
Assuming you have a valid HelloWord.cs file in the same directory as the build file, you can build the release version of this project just by entering nant at the command-line. This is equivalent to entering nant release build, but because project.config is set to release by default and the default target is build, this isn't necessary.

If you want to do a debug version of this project, use the following command: nant debug build. Note that you must specify the build target in this case. If you specify any targets on the command line, NAnt ignores the default target. If you just entered nant debug, NAnt would have executed the debug target and then exited. If you notice that the debug target is called twice when doing a debug build, you can move to the head of the class. It is called first because you specify it on the command line and a second time by the init target. This is not as efficient as it could be, but I left it this way for simplicity.

Obviously we are just scratching the surface of what NAnt can do with the above example. Check out the links in the Where Can I Get More Information section at the end of this article to see more examples of what you can do with NAnt.

What is the Workflow of a Build Using NAnt?

Once you have your build file(s) written and tested, you will want to start using them for your builds. Performing a build with a build tool like NAnt usually involves these steps:
  1. Set a version property in your build file to the value for the current build (you could also pass this to NAnt on the command line)
  2. Get the latest source from source code control (if you do not have NAnt do this for you)
  3. Run NAnt with appropriate command line targets (debug build, for example)
  4. Wait for the build to complete (you can use NAnt's <mail> task to have NAnt notify you by email when the build completes; this is useful for solutions that require especially long builds)
  5. Handle any build errors. NAnt will fail if it encounters any errors. If a file fails to compile, for example, NAnt will fail. You can configure some tasks to either fail or not fail on error. The <copy> task is an example.
  6. If the build succeeded, deploy the build output. (NAntContrib includes an <msi> task if you want to create .msi installation packages from NAnt.)
You can actually automate the NAnt build process using continuous integration tools like Draco.NET and CruiseControl. These tools monitor your source code and automatically perform builds when they detect changes. Continuous integration is outside the scope of this article, but check out the Where Can I get More Information? section at the end of this article for some links to get more information on continuous integration.

What about MSBuild?

Ant was such a good idea that NAnt was created for .NET developers. Microsoft recognized a good idea when it saw it and have announced their own build tool called MS Build (due to ship with the .NET Framework redistributable starting with Longhorn). It's hard to speculate on MS Build since it hasn't been release yet, but it looks promising. Like NAnt, MS Build will use XML files to specify targets and will be extensible (you will be able to create your own tasks). MS Build also addresses one shortcoming of NAnt: MS Build promises to be tightly integrated into Visual Studio .NET. In fact, MS Build will be integral to Visual Studio: project files will actually be MS Build files.

So does this spell the end for NAnt? Well, maybe, eventually, MS Build could make NAnt redundant. But in the near-term, MS Build is unlikely to offer the breadth of built-in tasks that NAnt does. I don't see Microsoft including tasks for checking source out of CVS, for example. Even if MS Build ends up eclipsing NAnt, the two build tools will be more similar than different, so it is still worth learning NAnt now since you will be able to leverage your NAnt skills when MS Build becomes available.

Where Can I get More Information?

This article is a short introduction to NAnt. For more information on NAnt, including complete reference information for all NAnt tasks, check out NAnt's homepage at sourceforge http://nant.sourceforge.net and the NAnt Wiki and the NAnt Usage articles.

NAntContrib (a separate sourceforge project that includes non-core tasks) is available at http://sourceforge.net/projects/nantcontrib. For more information on continuous integration see http://www.martinfowler.com/articles/continuousIntegration.html, Draco.NET and CruiseControl. For more on MS Build (including a table comparing MS Build tasks to NAnt tasks), check out http://channel9.msdn.com/wiki/default.aspx/MSBuild.HomePage.

Happy Programming!

  • By Eric Desch

  • ASP.NET [1.x] [2.0] | ASPMessageboard.com | ASPFAQs.com | Advertise | Feedback | Author an Article