Channels ▼
RSS

.NET

Continuous Integration with CruiseControl.NET


Marcin Kawalerowicz runs a consultancy in Silesia, Poland. Craig Berntson has been Microsoft MVP since 1996. Marcin and Craig are the authors of Continuous Integration in .NET.


CruiseControl.NET (CCNet) is a continuous integration (CI) server that is well established in the .NET community. On one hand, it is widely adopted and used with success in the production environment, but for using it you have to "pay" a so-called "angle bracket tax" -- the additional costs that are generated if you have to fight your way manually through the configuration, which is held in XML format; hence, an angle bracket tax. With CCNet, you get the software for free but you have to deal with the configuration yourself. But on the other hand, if you are doing the entire configuration, nothing is hidden from you behind a wizard or UI. You need a thorough understanding of what you are doing to do it right. Let's try to set up a CCNet server to continuously integrate our project.

Starting with CCNet

You can get the current version of CCNet from the ThoughtWorks web site. Get the setup installation file and start it on your CI machine. The installation is straightforward. As shown in Figure 1, you have to decide what components you want to install.

[Click image to view at full size]
Figure 1: Selecting the CCNet components you need for your server. CruiseControl.NET Server is an essential part of your installation, Web Dashboard is a web page that provides build feedback, and Examples are configuration examples.

If you have Internet Information Server (IIS) installed on the same machine as CCNet, you can install Web Dashboard there. It can be installed separately, and we strongly advise you to have an instance of the Web Dashboard running somewhere. If you don't have IIS installed on your server, we strongly recommend you do it. Depending on the operating system your server is running, you will have to add Web Server (IIS) role in Server Management of Windows Server 2008 or use Programs and Features console to turn the IIS on.

Continuous Integration is all about the feedback. You should always know what is going on. Did the build fail? Why did it fail? All that information could be obtained over the Web Dashboard, and CCNet would be handicapped without it! During the installation, you will be asked whether to install CCNet as a Windows service (Figure 2).

[Click image to view at full size]
Figure 2: CCNet can be installed as a Windows service and is able to configure IIS to be ready to serve the Web Dashboard.

CCNet is able to work standalone or as a Windows service. If you plan to use CCNet as a production CI server, it surely should run as a Windows service. Standalone mode is very helpful while configuring and troubleshooting the server. Note that the CCNet Windows service will not be started automatically after the installation.

As shown in Figure 2, the CCNet installer is able to prepare everything on the IIS for the Web Dashboard. This way, you will only have to configure your CCNet instance to make it work.

Configuring CCNet

The CCNet configuration file can be accessed via the Start menu or directly edited in C:\Program Files\CruiseControl.NET\server\ccnet.config if you installed CCNet in the default location. Immediately after the installation, you have an empty configuration file such as this:


<cruisecontrol xmlns:cb="urn:ccnet.config.builder">
	<!-- This is your CruiseControl.NET Server Configuration file. Add your projects below! -->
	<!--
		<project name="MyFirstProject" />
	-->
</cruisecontrol>

CCNet lets you define multiple projects. In the CCNet nomenclature, a project is separate unit of works that CCNet performs. We will define a project for our financial calculator Framework project, as in Listing 1.


<project name="Framework">
  <workingDirectory>c:\CI\Framework\</workingDirectory>
  <artifactDirectory>c:\CI\Artifacts.Framework</artifactDirectory>
  <webURL>http://localhost/ccnet</webURL>
  <triggers>
    <intervalTrigger initialSeconds="0" />                              1
  </triggers>
  <sourcecontrol type="svn">                                            2
    <trunkUrl>https://HAL/svn/Framework/trunk</trunkUrl>                2
    <executable>C:\Program Files\Svn\bin\svn.exe</executable>           2
    <username>marcin</username>                                         2
    <password>password</password>                                       2
  </sourcecontrol>
  <tasks>
    <msbuild>                                                           3
      <executable>                                                      3
         C:\Windows\Microsoft.NET\Framework\                            3
[CA]v4.0.20506\MSBuild.exe                                              3
      </executable>                                                     3
      <projectFile>Framework.sln</projectFile>                          3
      <buildArgs>
         /p:Configuration=Release /verbosity:minimal                    3
      </buildArgs>                                                      3
      <logger>
        C:\Program Files\CruiseControl.NET\server\
[CA]ThoughtWorks.CruiseControl.MSBuild.dll</logger>
    </msbuild>
  </tasks>
</project>

<b>
1   Defines interval trigger
2   Gets the source code from SVN
3   Declares a Visual Studio project with default target
</b>
Listing 1: Project configuration in CCNet.

After defining the name for our project, we have to set some important variables like a working directory where the integration will occur. CCNet produces various artifacts while integrating. For example, build logs should be stored somewhere. You should define where using the artifactDirectory element. If you are using Web Dashboard, you should define its webURL.

The minimal configuration that lets you perform continuous integration consists of three elements:

  • The first one is an intervalTrigger (#1). It specifies that the integration should occur periodically. It means that CCNet will poll the source control system for changes periodically and trigger the build only if something new is found in the repository. Using CCNet you have to remember that not every change committed to the repository triggers a build. If two commits occur during the wait interval, both of them will be pulled and integrated after the trigger fires.
  • The second element that you have to declare is a sourceControl (#2) tag. It defines the place from which CCNet should pull the changes to feed the integration with. Subversion commits are transactional. It means that there is no way that the CI server triggers the build during the commit, so that not all the files are in the desired state. If you are using SVN, you don't have to worry.
  • The last part you have to define is what CCNet should actually do. In the tasks element (#3), we define a task for CCNet. It is the msbuild task that starts the solution file.

You can verify your configuration before you start CCNet using the Configuration Validation Tool that comes with CCNet and is available from Start menu. After loading your configuration file, it will perform the validation as in Figure 3.

[Click image to view at full size]
Figure 3: CCNet Configuration Validator can ease the angle bracket tax you have to pay using this CI server. It lets you check the configuration before you start your server.

When you are sure you have configured everything, you can start the server. You have two options. As mentioned above, CCNet could work as a Windows service or as a standalone application. We will begin with the standalone version. It gives you immediate feedback on the screen and is way better for the initial phase than the non-UI Windows service version. After starting your CCNet standalone application, you will get something like Figure 4.

[Click image to view at full size]
Figure 4: CCNet in console mode is best for initial trial-and-error configuration or troubleshooting your configuration. The CCNet console displays a lot of information about what is going on, such as how the integration is going or what the build is saying. It's great for debugging your CI process.

If you get everything right, you should get your software integrated. You can, of course, configure the interval trigger to run as often as you want. You can use another type of trigger too. Let's look at the possibilities you have.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video