CruiseControl.NET Cheat Sheet

Environment

- Server:
  - CruiseControl.NET 1.4.4 SP1, instructions updated for 1.6.7981 on 7/13/11.
  - Windows Server 2008 R2 (AMD 64 bit)
  - IIS 7.5
- Client:
  - CruiseControl.NET Tray 1.4.4 SP1
  - Windows 7 Ultimate (AMD 64 bit)

Overview

CruiseControl.NET (ccnet) is a continuous integration server for Windows.

Server Setup

These steps describe how to install and configure the follow ccnet features on a Windows server:

- The ccnet server software running as a Windows service.
- The web dashboard accessible via an IIS virtual directory.
- The examples.

Download the installer from SourceForge and then perform these steps on the server:

1. Run the installer and click the Next button in the welcome window.
2. Click the I Agree button in the license window.
3. Leave all of the ccnet features checked in the components window, then click the Next button.
4. In the Additional Configuration window, leave the Windows service and IIS virtual directory options checked, then click the Next button.
5. In the Install Location window, specify the directory you would like to install ccnet to, then click the Next button.
6. In the Start Menu Folder window, click the Install button.
7. If you see a window with the following message:
  1. The installer attempted to set the ASP.NET version for the CruiseControl.NET Web Dashboard but was not successful.
8. just click the OK button and set the ASP.NET version after the installation completes.
9. Once the installation completes, click the Next button in the Installation Complete window.
10. Click the Finish button in the Completing window.

The ccnet server software is now installed. If you received the ASP.NET error message above this is because the installer tries to run this command:

"C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_regiis.exe" -s "W3SVC/1/ROOT/ccnet"

but it fails. This failure is usually due to installing ccnet on a 64-bit Windows server. You can see if this is the reason by running this command and see if the message is this:

Start registering ASP.NET scriptmap (2.0.50727) at W3SVC/1/ROOT/ccnet.

Error when validating the IIS path (W3SVC/1/ROOT/ccnet). Error code = 0x80040154

The error indicates that IIS is in 64 bit mode, while this application is a 32 bit application and thus not compatible.

Since ccnet is a 32-bit application it is necessary to configure it to run in an IIS app pool that allows 32-bit applications. Run IIS Manager and create an app pool named ccnet. If you are running ccnet 1.5 then set the pool’s pipeline mode to Classic, otherwise for ccnet 1.6 or later set the pipeline mode to Integrated. Also set the .NET version to 4.0. Go into the new pool’s advanced settings and set the Enable 32-Bit Applications option to True. Then go into the Advanced Settings of the ccnet virtual directory and change the Application Pool to ccnet.

You should now be able to use a web browser to access the http://server-name/ccnet site. If you get this error:

Server Error in Application "DEFAULT WEB SITE/CCNET"

HTTP Error 500.21 - Internal Server Error

Handler "CCNetHttpHandler" has a bad module "ManagedPipelineHandler" in its module list

then ASP.NET is not registered with IIS. To remedy this, run these commands:

%windir%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis.exe -i

%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i

Note: It’s a good idea to follow the steps in the previous paragraph and set up a specific IIS app pool for ccnet so that it is isolated from other sites on the server, even when the Windows server is a 32-bit server.

A Windows service named CruiseControl.NET Server will now be in the services control panel. Go to that service entry and change the startup type to automatic and also start the service while you are there.

Configuring the Server

Assuming that you installed the server software as a Windows service, you will find the configuration file ccservice.exe.config in the server subdirectory of the installation directory, for example:

C:\Program Files (x86)\CruiseControl.NET\server

I like to create a directory (on a disk that has plenty of free space) to hold the following:

- Project configuration information.
- The build state files.
- Dependent assemblies and other dependencies required to build projects.
- The project build directories.

I’ll use the G: drive as this disk drive and will create a top-level directory on this drive called build. I also share this directory so other developers can easily access the files. So create this directory and share it out (if you want).

In this build directory create the following subdirectories:

- ccnet—This directory holds ccnet subdirectories, the project build configuration file (ccnet.config), and the ccnet log files.
- vs8-assemblies, vs9-assemblies, vs10-assemblies (optional)—These directories will contain Visual Studio assemblies that are required to build Visual Studio projects without having to have Visual Studio installed on the build server.
- vsprojects (optional)—This directory contains a subdirectory for each Visual Studio project that is built by this ccnet server.

The last two sets of directories are optional and depend upon whether you use Visual Studio or not. You may use Mono and therefore might have a mono-assemblies directory. And you may have other development environments that require other directories. This will become clear as you finish configuring the server.

Under the ccnet directory, create the state subdirectory which will hold build state files for each project.

The ccnet server directory is typically located here:

C:\Program Files (x86)\CruiseControl.NET\server

Copy the project build configuration file (ccnet.config) that the installation placed in the server directory to the G:\build\ccnet directory you just created.

In the server directory locate the server configuration file (ccservice.exe.config) and edit it in a text editor. In the appSettings section find the ccnet.config key that is commented-out and uncomment that line and change the value to point to the new location for the project build configuration file:

Also in the appSettings section find the ServerLogFilePath key and change its value to point to the config directory you just created. The line should look like this:

The ServerLogFilePath does not change where the ccnet service logs to; this setting is only used by the web dashboard’s show log function to determine where the log file is located. Since ccnet uses log4net for its logging, you must also modify the appropriate log4net setting in this configuration file. So locate the log4net section in the file and look for the RollingFileAppender appender element and its file entry. Change the file entry to contain the same location you changed the ServerLogFilePath to point to:

Along with the log file, you will probably want to send any log4net trace output to go to this directory as well. So open up the ccservice.exe.config (in the same ccnet server directory) and local the appender section. Change the file element to move the log file to the ccnet\build directory. Something like this:

Now all of the ccnet output will be conveniently found in this one directory.

Save the changes you have made to the configuration file then go to the Windows Services control panel applet and restart the CruiseControl.NET service. This will cause the service to read these new settings. You now have ccnet installed and configured to run as a Windows service and to send all its output to the build\ccnet directory that you created. The last server setup step is to configure the projects you would like to have ccnet build.

Debugging With the Command Line Program

On my build servers, I like to keep a shortcut to the command line program on the server’s desktop. Using the command line program can be a quick way to debug project build errors.

Just go to the ccnet server directory, typically:

C:\Program Files (x86)\CruiseControl.NET\server

and drag the ccnet.exe file to the desktop and create a shortcut for it.

The command line program will, by default, read the project configuration information from the ccnet.config file located in the ccnet server directory. If that is where your config file lives then fine; if you set things up as described above you’ll need to point the command line program to your config file. So find the ccnet.exe.config file in the ccnet server directory and open it in an editor. Locate the line that points to your ccnet config file and copy the file path. Now edit the properties of the shortcut you just created and add the config file path to it. The Target field should then look something like this:

"C:\Program Files (x86)\CruiseControl.NET\server\ccnet.exe" -config:G:\build\ccnet\ccnet.config

Your ccnet Windows service and your ccnet command line shortcut now both point to the same project build configuration file.

To debug using the command line program, first stop the CruiseControl.NET Server Windows service and then simply double-click the ccnet shortcut on the desktop. A console window will appear and ccnet will start up in that window and display all output there. Now go and force a build of one of your projects and watch the output from ccnet in the console window.

.NET Remoting

If you are going to allow users to connect to the server using .NET Remoting be sure to open TCP port 21234 for inbound connections on the server.

NuGet

Create the system environment variable EnableNuGetPackageRestore and set it to true.

Configuring the Projects

TBS.

To build VS projects, need: Windows SDK (to get the gacutil utility, among other things).

If your build server does not have Visual Studio installed then you may need to manually place some Visual Studio assemblies into the global assembly cache (GAC) on the server. For example, while the Windows SDK provides most of the Visual Studio assemblies it does not provide those Visual Studio assemblies used by the Visual Studio test framework. This is where the vs8-assemblies and vs9-assemblies directories that you created above come in. I like to copy the Microsoft.VisualStudio.QualityTools.Resource.dll and Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll files from the VS8 and VS9 versions of Visual Studio and place them in these directories. Then, on the build server, just drag-and-drop these files into the server’s GAC. If you do not have these files and in the build server’s GAC and you try to build a Visual Studio project that uses the Visual Studio test framework you will receive this error message:

The "ResolveKeySource" task failed unexpectedly.

System.InvalidOperationException: Showing a modal dialog box or form when the application is not running in UserInteractive mode is not a valid operation. Specify the ServiceNotification or DefaultDesktopOnly style to display a notification from a service application.

You will probably find that over time there are other such assemblies that you need to keep a copy of and place on the build server. Keeping these files in the ccnet-builds directory ensures you have them when you need them.

With .NET 4.0 and later, the GAC has moved from C:\Windows\assembly to C:\Windows\Microsoft.NET\assembly. Further, the Explorer extension that allowed you to drag-and-drop files into the old GAC no longer works with the new GAC. To install an assembly into the new GAC you must use the gacutil.exe utility that comes with the Windows SDK. So to install the VS2010 assemblies into the .NET 4.0 GAC you can use these commands:

cd/d C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\NETFX 4.0 Tools\x64

gacutil -i G:\build\vs10-assemblies\Microsoft.VisualStudio.QualityTools.CodedUITestFramework.dll

gacutil -i G:\build\vs10-assemblies\Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll

Building Signed Assemblies

In order to build .NET projects that are signed you must first register the signing key on the build server. One way to do this is to install Visual Studio, open the project’s solution, when Visual Studio prompts for the signing key’s password enter it. This registers the key on the computer and then ccnet will be able to automatically build the project. However, you may not want to have Visual Studio installed on the build server. This section describes how to register the signing key on the build server without having Visual Studio installed.

If you try to use MSBUILD from ccnet on a build server that does not have the signing key already registered you will get this error message:

The "ResolveKeySource" task failed unexpectedly.

ccnet is correctly invoking MSBUILD and MSBUILD then tries to display a popup window asking for the password for the signing key. Since there is no console available this error message is displayed. So you must register the signing key on the computer before ccnet will be able to successfully invoke MSBUILD to build the project.

Run mmc.exe and add the Certificates snap-in, specifying Service account when asked what the snap-in will be used to manage certificates for as well as CruiseControl.NET Server as the service account to manage. Right-click the CCService\Personal certificate node and select All Tasks → Import. Browse to the project’s key file then click the Open button then click the Next button.

If the error message is similar to this:

Cannot import the following key file: <file-name>.pfx. The key file may be password protected.

To correct this, try to import the certificate again or manually install the certificate to the Strong Name CSP with the

following key container name: VS_KEY_D4D1AF76A539DXYZ

then do this:

sn -i <file-name>.pfx VS_KEY_D4D1AF76A539DXYZ

References Via Shares

You may have some projects that references assemblies that reside on a shared network drive. In such a case, you must be sure to define the mapped drive while logged on under the build account.

V: = \\S2\build

Note: Be sure to use the server name when defining the mapped drive because the ccnet build process apparently cannot resolve the host name \\localhost.

Visual Studio 2010 (a/k/a 10.0) Builds

Once you convert a project to Visual Studio 2010 and if that project uses Web Application project types, you’ll have to edit the Microsoft.WebApplication.targets file located here:

C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\WebApplications

as described in these posts:

http://www.dotnetlite.com/2010/06/29/how-to-make-cruisecontrol-net-build-successfully-after-upgrading-to-visual-studio-2010/

http://codepolice.net/2010/02/22/problems-with-msbuild-tasks-after-playing-with-visual-studio-2010/

Also see the post by Chris S here - simply copy the Visual Studio files (vs10-assemblies, etc.):

http://stackoverflow.com/questions/3980909/microsoft-webapplication-targets-was-not-found-on-the-build-server-whats-your

Client Setup

With your ccnet server up-and-running you’ll want to install the ccnet Tray app on your development box. This application allows you to monitor your project builds as they happen on the server, allowing you to find out about and fix build errors as they occur. Download the Tray app from SourceForge and follow these steps:

1. Click the Next button in the Welcome window.
2. Click the I Agree button in the License window.
3. Choose the components you would like (typically all of them), then click the Next button.
4. Specify the directory you want to install to in the Choose Install Location window, then click the Next button.
5. Click the Install button in the Start Menu window. If you receive any of the following error messages:
  1. Error opening file for writing: Interop.SpeechLib.dll
  2. Error opening file for writing: CCLib.dll
  3. Error opening file for writing: ThoughtWorks.CruiseControl.Remote.dll
  4. Error opening file for writing: cctray.exe
6. just click the Ignore button.
7. In the Installation Complete window, click the Next button.
8. Click the Finish button in the Completing window.