asp:ToolKit
LANGUAGES: All .NET Languages
TECHNOLOGIES: .NET Compilers | NAnt | NUnit | NDoc
Wield the NAnt Build Tool
Take total control of the build and deployment process.
By Ken McNamee
For many developers, the introduction of Microsoft's .NET Framework and ASP.NET marked the end of complicated build and deployment scripts - the end of late nights spent stopping and restarting IIS and registering COM components. Installing a .NET application usually is as simple as copying it to its destination. Sometimes, though, building and deploying a real-world .NET application isn't so simple. I have experience with several ASP.NET applications that, unfortunately, could not completely shed their ASP 3.0 origins and still require some good old-fashioned manual labor, or a complicated deployment script, to do the job right. Even a 100 percent ASP.NET build and deployment might require some operations that don't fall under the realm of Xcopy, such as adding registry entries, configuring IIS, adding event-log codes, running unit tests, setting up application permissions, and precompiling Web forms and user controls.
When faced with the additional requirement of non-Xcopy tasks, I usually developed my own custom script to handle them. It sometimes took the form of a batch file or a Windows Script Host file. I could also use third-party deployment tools, and these days there are even more options. Visual Studio .NET includes project types specifically for setup and deployment. If you don't own Visual Studio .NET, though, that doesn't mean you're out of luck.
NAnt is a free, open-source tool that provides all the power you need to handle just about any deployment scenario. It's actually a .NET port - written in C# - of a Java build tool named Ant, which has been around for a few years. Ant began life as the build manager for the Jakarta Tomcat project, the reference implementation of the Java Servlet engine. It gained popularity quickly as an all-around build and deployment tool for many Java projects, and its conversion to C# was really a no-brainer.
How It Works
If you're familiar with Ant, you'll be happy to learn that NAnt works much the same way, though it's not 100 percent compatible. It uses an XML file with a .build extension that contains all its instructions as well as controls how the build and deployment operations proceed, which files and directories to include or exclude, under what conditions the operations succeed or fail, and what to do in case of a failure. Figure 1 is an example of an NAnt build file.
<?xml version="1.0"?>
<project name="NAntExample" default="build" basedir=".">
<property name="project.name" value="NAntExample"/>
<property name="debug" value="true"/>
<property name="src.dir" value="web"/>
<property name="prod.dir" value="C:\Inetpub\wwwroot\"/>
<target name="clean" description="remove all files">
<echo message="Deleting existing assemblies..."/>
<delete file="${src.dir}\bin\${project.name}.dll" />
<delete file="${src.dir}\bin\${project.name}.pdb" />
<delete dir="${prod.dir}\bin" />
<delete file="${prod.dir}\Default.aspx" />
<delete file="${prod.dir}\Web.config" />
</target>
<target name="build" description="compiles the source code">
<echo message="Building new assemblies..."/>
<csc target="library" debug="${debug}" failonerror="true"
output="${src.dir}\bin\${project.name}.dll" >
<sources basedir="${src.dir}">
<includes name="*.cs"/>
</sources>
<references>
<includes name="nunit.framework.dll"/>
<includes name="System.dll"/>
<includes name="System.Web.dll"/>
</references>
</csc>
<echo message="Running tests..."/>
<nunit2 verbose="true" haltonerror="true">
<formatter type="Plain"/>
<test assemblyname="${src.dir}\bin\${project.name}.dll"
outfile="${src.dir}\results.xml"/>
</nunit2>
<echo message="Copying files to production..."/>
<mkdir dir="${prod.dir}\bin" failonerror="true"/>
<copy file="${src.dir}\bin\${project.name}.dll"
todir="${prod.dir}\bin" failonerror="true"/>
<copy file="${src.dir}\Default.aspx" todir="${prod.dir}"
failonerror="true"/>
<copy file="${src.dir}\Web.config" todir="${prod.dir}"
failonerror="true"/>
</target>
</project>
Figure 1. The NAnt build file is an XML document that contains all the instructions necessary to compile a .NET application, run any unit tests, and deploy to another environment.
After a few minutes spent examining the XML, you should be able to follow what's happening. The file's structure is analogous to a .NET class file. Think of the <property> elements as member variables or constants defined once and used many times throughout the rest of the document. This lets you easily change source and destination directories, the debug mode, and anything else you think is specific to the application.
The <target> elements map similarly to methods, with the Name attribute representing the method's name. When NAnt is executed from the command line, you pass in the name of the target you want to run. This command tells NAnt to execute the "clean" target in the NAntExample.build file:
nant.console -buildfile:NAntExample.build clean
The -buildfile option is necessary only if more than one file in the current directory has a .build extension. This particular command deletes the assembly and debug symbol file from the build directory and deletes all the files from the production directory.
Once you finish that bit of house cleaning, it's time to compile the application, run the unit tests, and deploy the files to the production environment. Here's the command to accomplish this:
nant.console -buildfile:NAntExample.build build
The <csc> element tells NAnt to use the C# compiler and also gives NAnt the name and type of the compiled assembly and the build location. The <sources> element defines which files to include or exclude in the build operation. In the <references> section, you must include all the assemblies used by all the source files or the build will fail.
Beyond the Build
In my last article, Find and Fix Bugs With NUnit, I wrote about the benefits of using NUnit, the unit-testing framework that provides a consistent model for testing the methods in your business objects. One of NAnt's most beneficial features is its ability to integrate NUnit tests into the build process and make the success or failure of the entire build process dependent on whether all or some of the tests pass. If you'd like, NAnt even can send an e-mail alert if a failure occurs. Depending on which version of NUnit you're using, the <nunit> and <nunit2> elements tell NAnt to run all the tests in the assembly you specify.
Finally, the <mkdir> and <copy> elements instruct NAnt to create the production environment and copy all the appropriate files. In this case, if any of these operations fail, the entire NAnt command fails. Obviously, this is a fairly simplistic example, but I'm sure you can see the potential that exists with this tool.
I'm sure those of you who have ever been responsible for building and migrating code into production at 3 a.m., running script after script, can appreciate the power, flexibility, and convenience NAnt provides. In addition to the features described in this article, NAnt has an option for generating an HTML help version of the XML documentation in the C# source files using NDoc. And, with the <zip> element, it also can create a zip file of the file set you define. NAnt even has a <script> element you can use if you need to drop down into VB .NET, C#, or JScript to provide ultimate control. I encourage you to look through the Task Reference section of the NAnt documentation. In all honesty, the documentation is somewhat lacking and, in some cases, a little misleading. But it does describe a great deal of functionality, and I have no doubt that many of you will find a place for NAnt in your ASP.NET toolkit.
References
- NAnt Home Page: http://nant.sourceforge.net
- Apache Ant Project: http://jakarta.apache.org/ant
- NUnit Home Page: http://nunit.sf.net
- NDoc Home Page: http://ndoc.sf.net
Ken McNamee is a senior software engineer with RelayHealth Corp., the premier provider of secure, Web-based doctor-patient communication services. Before this, he led a team of developers in re-architecting the Home Shopping Network's e-commerce site, HSN.com, to 100 percent ASP.NET with C#. E-mail him at [email protected].
More in asp.netNOW
Be sure to look for a working example of how NAnt makes deployment easier in an upcoming issue of asp.netNOW, the FREE e-companion to asp.netPRO. Subscribe at http://www.aspnetPRO.com today!
Tell us what you think! Please send any comments about this article to [email protected]. Please include the article title and author.
