CruiseControl.NET from Scratch - Version 1.0

Introduction

The idea of this article is to help you get started with CruiseControl.NET.  I’m assuming that you already know a bit about Continuous Integration and Test Driven Development and that you want to get up and running with CruiseControl.NET as quickly as possible.

I’m going to concentrate on setting up a system based on this environment:

·         .NET Framework v1.1

·         Visual Studio .NET 2003

·         Visual SourceSafe 6.0

This is a pretty common set-up at the moment.  However a lot of the ideas in this article are equally applicable to different versions of the CLR and Visual Studio .NET, and to different source control providers.

I’ve found that the many configuration options available in CruiseControl.NET can be a bit daunting so we are going to create a simple CruiseControl.NET setup by performing a series of steps.  You will end up with a working system which you can refine to meet your own needs.  Our configuration will consist of:

·         the CruiseControl.NET continuous integration server, initially running from the command prompt and later as a service

·         the Web Dashboard application which provides detailed information about completed builds

·         the CCTray system tray application, which runs on client machines and permits easy launch of the web application, forcing of builds etc

I have found these three applications to be excellent for the purposes of our development team.

Hardware

We are going to work with three machines:

·        the CruiseControl.NET build server, which will run the continuous integration server and the Web Dashboard – referred to in the configuration files that follow as "%buildserver%"

·        the server which hosts the SourceSafe database – referred to in the configuration files as "%sourceserver%"

·         a client machine which will run the CCTray system tray application and also view the CruiseControl.NET Web Dashboard using its browser

You can run everything on the same machine if you wish.

Software

To start with you’ll need the bits and pieces:

·         Visual Studio .NET 2003

·         Visual SourceSafe.  Version 6.0.

·         CruiseControl.NET.  Version 1.0 from: http://ccnet.thoughtworks.com.  It now comes with a neat installer (CruiseControl.NET-<version>-setup.exe)

·         NAnt for running build scripts.  Version 0.85-rc3 from: http://nant.sourceforge.net

·         NAntContrib for Visual SourceSafe support.  Version 0.85-rc3 from:  http://sourceforge.net/projects/nantcontrib

·         NUnit for adding test fixtures to Visual Studio .NET projects.  Version 2.2.0 from: http://www.nunit.org

The more recent versions of CruiseControl.NET can dispense with the need for NAnt, as they talk to SourceSafe directly for source retrieval and use Visual Studio .NET for the builds.  However I have not yet fully investigated this scenario, so we'll stick with NAnt for this article.

I’m also assuming that you have an IIS web server on your build server correctly configured to dish up ASP.NET pages.

Installation: Build Server

Your build server needs to have, at the least, a Visual SourceSafe client installation.  It does not, however, need a Visual Studio .NET installation as we will be using the NAnt solution task to build our project.

Create a directory on your build server to hold all the bits and pieces.  Mine is C:\Projects\CI (short for Continuous Integration).  In this directory:

·         Unzip NAnt to C:\Projects\CI\

·         Unzip NAntContrib to C:\Projects\CI\.  Then copy the contents of the nantcontrib-0.85-rc3\bin directory to the nant-0.85-rc3\bin directory.  This will enable NAnt to use the "vssget" task later on.

Now run the CruiseControl.NET installer on the build server and accept all the default settings except for the destination folder.  I like everything in the same place, so enter "C:\Projects\CI\CruiseControl.NET".

You now have a single directory on the build server containing your continuous integration environment.

Installation: Source Server

Your source control server needs a Visual SourceSafe server installation.

Installation: Client

Your client machine needs a Visual Studio .NET installation in order to create the project in this example.

It also needs NUnit 2.2 installed so that we can write some tests.

You will find the installer for the CCTray application inside the webdashboard\cctray folder in the build server installation.  Run this on the client, installing it to any destination folder you like.

Towards Our First Successful Build

We are going to run the continuous integration server from the command line at first – it's easier to see what's going on.  Open a command prompt window and navigate to C:\Projects\CI\CruiseControl.NET\server.  Run ccnet.exe.  You will see this output a bit like this:

[CruiseControl Server:Debug]: The trace level is currently set to debug...

[CruiseControl Server:Info]: Reading configuration file "C:\Projects\CI\CruiseControl.NET\server\ccnet.config"

[CruiseControl Server:Info]: No projects found

[CruiseControl Server:Info]: Registered channel: tcp

[CruiseControl Server:Info]: CruiseManager: Listening on url: tcp://192.168.0.1:21234/CruiseManager.rem

[CruiseControl Server:Info]: Starting CruiseControl.NET Server

Nice and neat – a big improvement on previous versions.  Starting in version 1.0 of CruiseControl.NET debug tracing is turned on by default, so even more information is displayed to help you get up and running.  The application is reading an XML file called ccnet.config, which at present has next to nothing in it.  But it is very happily starting and waiting for something to happen.  Unfortunately nothing will happen until we put something in ccnet.config.

We will modify ccnet.config file so that it contains two things:

·         a source code repository to examine for changes

·         a nant.exe to run and also a build file to run against

Once we’ve done this we’ll get our first successful build.

Modify ccnet.config

Leave ccnet.exe running and open ccnet.config in your favourite editor.  Whenever we change and save this file it will force a restart of the continuous integration server so we'll get immediate feedback.  Modify it to look like this:

<cruisecontrol>

  <project>

    <name>CITest</name>

    <triggers>

      <intervalTrigger seconds="60" buildCondition="ForceBuild" />

    </triggers>

    <sourcecontrol type="vss">

       <project>$</project>

       <username>ccnet</username>

       <password>ccnet</password>

       <ssdir>\\%sourceserver%\vss</ssdir>

    </sourcecontrol>

    <tasks>

      <nant>

        <executable>C:\Projects\CI\nant-0.85-rc3\bin\nant.exe</executable>

        <buildFile>cruise.build</buildFile>

        <targetList>

          <target>run</target>

        </targetList>

      </nant>

    </tasks>

  </project>

</cruisecontrol>

We have created a "project" element containing three other elements:

·         triggers – which tells CruiseControl.NET what sort of source code repository checks to perform.  We have asked that a build be forced every 60 seconds.  Later on we'll modify this to check the source code repository for changes.

·         sourcecontrol - which tells CruiseControl.NET which source code repository to monitor for changes

·         tasks -  which describes the NAnt binary and build script to run when changes are detected.  We don’t have the NAnt build script yet, but that doesn’t matter right now.

Let’s look at the file in detail.

Configure Visual SourceSafe

We have added a "sourcecontrol" element for Visual SourceSafe.  This is often the tricky part of CruiseControl.NET configuration.  You should note the following:

·         The "project" element is required.  I have initially set its value to “$” representing the root project in Visual SourceSafe.  We don’t have our own SourceSafe project yet.  When we do, we'll change this value.

·         The "username" and "password" elements are also required.  If they don’t refer to a valid SourceSafe user name with a valid password then CruiseControl.NET will freeze while displaying output which looks something like this:

...

...

[CITest:Debug]: Executing process D:\Program Files\Microsoft Visual Studio\VSS\win32\ss.exe history $ -R -Vd03/12/2005;22:00~03/12/2005;21:55 -Yccnet,badpassword -I-Y in C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory

...

...

This is because (unseen by you) the SourceSafe command line application (ss.exe) is attempting to prompt you for a valid password!  You will need to break out of ccnet.exe and possibly kill ss.exe in task manager.  So set up a build user and password for CruiseControl.NET using SourceSafe Administrator, or input your own login credentials.

·         It’s a good idea to set the "ssdir" element, even though things should still work correctly without it as ss.exe will extract the server details from your build server’s copy of srcsafe.ini.  It appears to be able to locate this file by stepping up one directory in the hierarchy from where ss.exe is running!  The content of the element should be the name of the folder containing your database’s srcsafe.ini file.  Here the folder is shared as “vss” on the machine we’ve named %sourceserver%.

·         There is also an optional "executable" element which supplies ccnet with the path to ss.exe.  If you don’t supply one ccnet does some peeking in the registry to extract the path to your ss.exe, so I don’t personally bother with it.

Save the ccnet.config file.  Your console output should change immediately to something which contains lines like this.

 [CruiseControl Server:Debug]: Error loading buildfile.

[CruiseControl Server:Debug]:     Could not find file "C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory\cruise.build".

Let's view our failure in the Web Dashboard.

The Web Dashboard

There is no initial configuration required for the Web Dashboard.  Simply navigate to http://%buildserver%/ccnet in a browser.  You’ll be able to see the CITest project and view details of the failure.

Now let’s fix that build file problem.

First Successful Build

We told CruiseControl.NET that:

·         there was a build file called “cruise.build”

·         the build file contained a target called “run”

This was all lies.  Let’s remedy the situation.  Create the cruise.build file in C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory.  Mine looks like this:

<?xml version="1.0"?>

<project default="run">

  <target name="run">

  </target>

</project>

This should be enough to get us going.  The next time ccnet goes through a cycle I get this:

[CITest:Info]: No modifications detected.

[CITest:Info]: Build forced

[CITest:Info]: Building

[CITest:Info]: Build complete: Success

[CITest:Info]: Integration complete: 04/05/2005 22:44:14

Excellent!  Refresh the Web Dashboard and you’ll be able to gloat over your success.

CCNet System Tray Application

In fact I’m so pleased that I want to view my successful build another way.  Let’s set up the CCTray application.  CCTray uses .NET remoting to communicate with the build server.

We will need to tell CruiseControl.NET the URL for our particular project so that cctray can jump straight to that project's web page.  To do this add a "webURL" element to ccnet.config like this:

<cruisecontrol>

  <project name="CITest">

    <name>CITest</name>

<webURL>http://%buildserver%/ccnet/default.aspx?_action_ViewProjectReport=true&amp;server=local&amp;project=CITest</webURL>

...

...

I obtained this by viewing the CITest web page and pasting its URL into the config file, using &amp; in place of ampersands.

Now run the cctray.exe application on your client machine. (Tip: we add cctray.exe to our startup folder so that it is always running).

Double click on its system tray icon to bring up the application's main window then select Settings... from the File menu.

Now click on the Add... button to add our build server.  In the next dialog type the name of the build server in the input box and click on the Add Server button.  Select CITest from the projects list on the right and click OK.  You should now see our build server in the list on the main settings dialog.  Click OK.

Now the icon will go red if a failed build occurs.  You can also force a build by launching the main window and right clicking on the list entry for our project.  Cool!

What’s Next

Let’s summarise what we have achieved so far and what the final steps will be.  We have:

·         Configured the CruiseControl.NET continuous integration server (ccnet.exe) using the ccnet.config file.  This is nearly complete for the purposes of our project.  We are currently forcing a build every 60 seconds so that we don't have to modify our code in order to kick off a build.

·         Configured the CruiseControl.NET Web Dashboard so that it displays the results of our builds.

·         Configured the CruiseControl.NET system tray application (cctray.exe) so that remote clients are informed of build results and can view the status of their project in a browser.

Let's change the configuration so that CruiseControl.NET only runs a build when the source code repository changes.  It will then execute NAnt with our cruise.build file.  What we do inside the build file is up to us.  We are going to:

·         Clean the build directory for our project

·         Get the latest source code from the repository and compile it

·         Run tests

Remove Force Build

Modify the "triggers" element it so that it looks like this:

<cruisecontrol>

  <project name="CITest">

    <name>CITest</name>

    <webURL>http://localhost/ccnet</webURL>

    <triggers>

      <intervalTrigger seconds="60" />

    </triggers>

...

...

We have removed the force build.  From now on we will rely on checkins to start the integration process.

Add a Visual Studio .NET Project

Create a C# class library project with Visual Studio .NET called CITest.  Place it in your normal projects location – not under the CI directory.  Don’t add any code – just check that it builds.  Now, using Visual Studio, add your project to source control under the root SourceSafe project, so that we can reference its project path as "$/CITest" in our ccnet.config file.  (Tip:  When the "Add to SourceSafe Project" dialog pops up in Visual Studio, clear the "Project" text box completely, select the "$/" node and press OK.  A project named CITest will then be correctly added under the root.  If you type "CITest" in this box, you'll end up with a project called $/CITest/CITest!)

Now modify the "project" element within the "sourcecontrol" element of our ccnet.config file as follows:

<cruisecontrol>

  <project name="CITest">

...

...

    <sourcecontrol type="vss">

      <project>$/CITest</project>

...

...

You should still have a successful build!

Now we are going to modify the cruise.build file to clean the build directory, get the source and compile it.

Backtracking to NAnt

We are going to run NAnt directly against our cruise.build file for a while.  Remember that this is all that CruiseControl.NET does – so when we've got it all working smoothly we can just plug it back again.  In the meantime we will get a bit more help with diagnostics from the output produced by NAnt.

It is very useful, whenever you're experiencing problems with CruiseControl.NET, to run NAnt directly against your build file, so this technique may well save you a lot of time somewhere down the line.  if you're really having problems try running it with the "–verbose" option.

Create a batch file called startnant.bat in the C:\Projects\CI directory and insert the following line:

nant-0.85-rc3\bin\nant.exe -buildfile:CruiseControl.NET\server\CITest\WorkingDirectory\cruise.build

This will execute NAnt against our cruise.build file.  Stop CruiseControl.NET and execute startnant.bat.  You will see this:

NAnt 0.85 (Build 0.85.1932.0; rc3; 16/04/2005)

Copyright (C) 2001-2005 Gerry Shaw

http://nant.sourceforge.net

Buildfile: file:///C:/Projects/CI/CruiseControl.NET/server/CITest/WorkingDirectory/cruise.build

Target framework: Microsoft .NET Framework 1.1

Target(s) specified: run

run:

BUILD SUCCEEDED

Total time: 0.1 seconds.

Now modify cruise.build so that it deletes and creates a "Source" directory in which we are going to get and build our source.  It will now look like this:

<?xml version="1.0" ?>

<project default="run">

  <target name="run" depends="clean">

  </target>

  <target name="clean">

    <delete dir="Source" failonerror="false" />

    <mkdir dir="Source" />

  </target>

</project>

When you run startnant.bat it will delete the Source directory (if it exists) then create it.  Now add a target which uses the vssget task from NAntContrib to get the source from SourceSafe:

<?xml version="1.0" ?>

<project default="run">

  <target name="run" depends="get">

  </target>

  <target name="get" depends="clean">

    <vssget username="ccnet"

            password="ccnet"

            localpath="Source"

            recursive="true"

            replace="true"

            writable="false"

            dbpath="\\%sourceserver%\vss\srcsafe.ini"

            path="$/CITest"/>

  </target>

  <target name="clean">

    ....

</project>

The "srcsafe.ini" at the end of the "dbpath" attribute isn't required if you're using a UNC path to access your source control server.  Check that you're getting the source correctly by running startnant.bat.  At the end of the build the CITest directory should contain a copy of the source.

Finally add a target to build the solution file:

<?xml version="1.0" ?>

<project default="run">

  <target name="run" depends="build">

  </target>

  <target name="build" depends="get">

    <solution configuration="debug" solutionfile="Source\CITest.sln" />

  </target>

  <target name="get" depends="clean">

    ...

    ...

</project>

Notice that each time we modify the file we change the dependencies.  The targets will be run by NAnt in the following order:

·         clean

·         get

·         build

Later on we'll run a test target.  Note that I haven't used any NAnt properties in my build file.  I leave this for you to play with later.

When you run startnant.bat you should now see:

NAnt 0.85 (Build 0.85.1932.0; rc3; 16/04/2005)

Copyright (C) 2001-2005 Gerry Shaw

http://nant.sourceforge.net

Buildfile: file:///C:/Projects/CI/CruiseControl.NET/server/CITest/WorkingDirectory/cruise.build

Target framework: Microsoft .NET Framework 1.1

Target(s) specified: run

clean:

   [delete] Deleting directory 'C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory\Source'.

    [mkdir] Creating directory 'C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory\Source'.

get:

   [vssget] Getting '$/CITest' to 'C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory\Source'...

build:

 [solution] Starting solution build.

 [solution] Building 'CITest' [Debug] ...

run:

BUILD SUCCEEDED

Total time: 1.1 seconds.

Now restart ccnet and cctray.  You should still have a successful build.  If not, view the NAnt log (by clicking on the “View Build Log” link in the Web Dashboard) to find out the reason.

Once you have everything running smoothly, try breaking the build by checking out a file from the CITest project, adding a compilation error and checking it in again.  CruiseControl.NET will detect the modification and the build will fail.  Fix it!

NAnt and Assembly References

In previous versions of NAnt there were often problems when referencing third party assemblies installed in the GAC.  These seem to be resolved in the latest version (at least in the case of NUnit) so the simplest thing for us to do in order to be able to write some tests is:

·         add a reference to the nunit.framework assembly in the CITest directory by using the ".NET" tab "Add Reference" dialog.

Add a Test

Modify your Class1.cs to look something like this:

using System;

using NUnit.Framework;

namespace CITest

{

  /// <summary>

  /// Summary description for Class1.

  /// </summary>

  [TestFixture]

  public class Class1

  {

    public Class1()

    {

      //

      // TODO: Add constructor logic here

      //

    }

    [Test]

    public void ThisTestWillDefinitelyFail()

    {

      Assert.Fail("This test fails and I expect Cruise Control to display this message");

    }

  }

}

Now modify the cruise.build file one last time to run any test fixtures present in your dll.  Here is the final version of cruise.build, with the modifications highlighted:

<?xml version="1.0" ?>

<project default="run">

  <target name="run" depends="test">

  </target>

  <target name="test" depends="build">

    <nunit2>

      <formatter type="Xml" />

      <test assemblyname="Source\bin\debug\CITest.dll" />

    </nunit2>

  </target>

  <target name="build" depends="get">

    <solution configuration="debug" solutionfile="Source\CITest.sln" />

  </target>

  <target name="get" depends="clean">

    <vssget username="ccnet"

            password="ccnet"

            localpath="Source"

            recursive="true"

            replace="true"

            writable="false"

            dbpath="\\desktop\vss\srcsafe.ini"

            path="$/CITest"/>

  </target>

  <target name="clean">

    <delete dir="Source" failonerror="false" />

    <mkdir dir="Source" />

  </target>

</project>

I’ve added a target which runs NUnit against our assembly.  I’ve specified the “Xml” formatter, as CruiseControl.NET expects XML output.

Check in the code and run startnant.bat to check the cruise.build file.  You should see output ending like this:

...

...

   [nunit2] <failure>

   [nunit2] <message><![CDATA[This test fails and I expect Cruise Control to display this message]]></message>

   [nunit2] <stack-trace><![CDATA[   at CITest.Class1.ThisTestWillDefinitelyFail() in c:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory\Source\Class1.cs:line 22

   [nunit2] ]]></stack-trace>

   [nunit2] </failure>

   [nunit2] </test-case>

   [nunit2] </results>

   [nunit2] </test-suite>

   [nunit2] </results>

   [nunit2] </test-suite>

   [nunit2] </results>

   [nunit2] </test-suite>

   [nunit2] </test-results>

   [nunit2]

BUILD FAILED

C:\Projects\CI\CruiseControl.NET\server\CITest\WorkingDirectory\cruise.build(6,6):

Tests Failed.

Total time: 1.7 seconds.

Exactly what we want.  Your ccnet build should fail, and you will see the test failure displayed in the web application.  Now modify Class1 by adding the [Ignore] attribute like this:

    [Ignore("I wanna successful build")]

    [Test]

    public void ThisTestWillDefinitelyFail()

    {

      Assert.Fail("This test fails and I expect Cruise Control to display this message");

    }

Sit back and relax.  Your next build will succeed.  You will be able to see the ignored test in the Web Dashboard output.  We’re done!

Now that we have a working continuous integration system there are lots of possible refinements.  I won’t attempt to cover them all, but here are some candidates in no particular order of priority.

Running the CruiseControl.NET Service

An easy one this – just stop running ccnet.exe and start the Windows Service instead.  The output that we have been viewing via the console is still logged to a file called ccnet.log in the CruiseControl.NET\server directory.

Adding Visual Studio Projects

Don't forget that as you add more projects to your solution you will need to add a new "test" element to cruise.build, otherwise your tests won't be run!

Also if you want to use application configuration files (as many people do when using NUnit) you will need to reference them within your "test" element like this:

  <test assemblyname="CITest\bin\debug\CITest.dll" appconfig="CITest\bin\debug\CITest.dll.config" />

Adding Multiple CruiseControl Projects

Very handy this – multiple projects handled by the same build server – and/or multiple build servers managed by a single Web Dashboard.  See the CruiseControl.NET documentation for more detail.

Merging NAnt Output

For more control over the output from your build script send it to files and combine the files with the CruiseControl.NET log using a merge task.  This involves changing the "formatter" element in the cruise.build file so that it sends output to files:

<formatter type="Xml"

    usefile="true"

    extension=".xml" />

and adding a publishers element to the ccnet.config file so that it merges these files into the log:

...

    <publishers>

      <merge>

        <files>

          <file>Source\bin\debug\*-results.xml</file>

        </files>

      </merge>

      <xmllogger />

    </publishers>

  </project>

</cruisecontrol>

Note also that we have added a xmllogger publisher.  This is the default publisher used by CruiseControl.NET and is automatically used if you don't create a publishers element in the ccnet.config.  Once, however, you start to specify publishers you need to include it.  It also needs to be after the merge element.

Bootstrapping NAnt

In our team we maintain two NAnt build scripts.  The first one just cleans the build directory and gets the latest source from the repository.  Included in the latest source is the second build script, which is invoked from the first.  The second script compiles the source and runs the tests.

The advantage of this approach is that we can maintain the second build script as a solution item and modify it (for example by adding a new "test" element) whenever we add a new project to the solution.  When the solution is checked in CruiseControl.NET will automatically perform the modified build.

Summary

Any effort you invest in setting up CruiseControl.NET is repaid many times over, and I hope that this article has helped you on your way.