Getting Started With CI Using Hudson For Your .NET Projects

In this post, I will explore installing and configuring Hudson as a continuous integration server for .NET projects. Why Hudson? This is good question. I know other CI servers exist, however, Hudson happens to already be an accepted solution at work. Hudson is a web application that allows you to monitor your build process. Hudson is extendable via plug-ins.

For more information about Hudson visit their website.

Installing Hudson

Hudson is a Java web application that is packaged and distributed in a ‘war’ file. This allows Hudson to be installed and running rather quickly. The only pre-requisite is that you have Java installed. Here are the links to the files:

• Java
• Hudson

Once the Hudson war file has been downloaded, you can finish the install and start Hudson by doing the following: open up a console window, navigate to the folder containing the ‘hudson.war’ file and issuing the following command:

java -DHUDSON_HOME=c:Hudson -jar hudson.war

For the purposes of this tutorial, I am unpacking the Hudson war file to the ‘c:Hudson’ folder. When configuring Hudson keep in mind that it will need disk space to pull code from source control, perform builds, and maintain a workspace. The folder selected should have the capacity required and some thought should be put into your backup strategy.

Now you should see something like the following in your console window:

Hudson is now running and can be accessed via your web browser at http://localhost:8080/

Hudson is “internet aware” and uses the web to fetch plug-ins and updates. Here is an update:

You probably don’t want to run Hudson via the command line in your production environment. To install Hudson as a Windows service use the “Install as Windows Service” option on the “Manage Hudson” page and follow the instructions.

Now you should have Hudson listed as a Service in your service panel.

Configuring Hudson

Configuration of Hudson is done using the “Manage Plugins” and “Configure System” options on the Manage Hudson page.

First visit the “Manage Plugins” option and click on the “Available” tab to display a list of plug-ins that can be installed. Again, Hudson is “internet aware” and will fetch these from the interwebs so a network connection is required. There are an ever growing number of plug-ins as the Hudson eco-system continues to evolve. Explore the list, and search the internet for possible extensions. I will focus on plug-ins to get .NET projects into the Hudson CI environment.

Select the following Hudson plug-ins and click ‘Install’:

• MSBuild Plugin – This plugin allows you to use MDBuild to build .NET projects.
• MSTest Plugin – This plugin converts MSTest TRX file metadata into a format that it can be integrated into the Hudson’s JUnit features. This will make the test reports available as build output.

I am using Subversion for source control. Hudson has built in support for Subversion. Other source control libraries may require a plugin to be selected to access your code.

These are the bare minimum to get your .NET projects built and automated tests run using Hudson. After the install, be sure to restart your Hudson service.

Now we need to configure the MSBuild plugin. Select the “Configure System” option and look for the “MSBuild Builder” section. Configure it to look like the following and click the ‘Save’ button (not shown…at the bottom of the page):

Notice that you can have multiple MSBuild configurations. This might be handy for building projects using the different versions of the .NET Framework.

Add A Build Job

Build jobs are added via the “New Job” option on the Hudson main page. Select a name and the “Build a free-style software project” option as shown below. Then click “OK”.

Now a ‘job’ will appear in the main Hudson page.

To manage the new project, click the link for the project you just created. You will get a page similar to the following:

Click the ‘Configure’ link in the list on the left. First select the “Discard Old Builds” option and configure the policy for limiting disk consumption.

Then configure your “Source Code Management” options. I am using Subversion so my configuration looks like the following:

Notice the period in the “Local module directory (optional)” field. That will force Hudson to check out the project directly into the workspace rather than into a subdirectory.

To setup the build select the “Add a Visual Studio project of solution using MSBuild” option from the “Add build step” drop down list.

After selecting the “MS Build Version” that we configured before and adding other configuration information, we have something like:

This will get the solution built. Now we want Hudson to execute the unit tests for the project. We can add a “Windows batch command” to call MSTest. Previously, I posted on using MSTest to run your .NET tests via a command line. After we add this batch command you will have something like the following:

Finally, select the “Publish MSTest test result report” from the “Post Build Actions” section and configure as follows:

This will take the ‘trx’ test results metadata file (XML), transform it into HTML and make it available as part of the build output.

Click “Save” at the bottom and the project should be ready to build manually. I found that I need to restart Hudson for the configuration to take effect.

Kick Off A Manual Build

On the main Hudson page you will see a list of all the jobs. On the right-hand side there is a button that allows you to schedule a job. Clicking that button will start the build process.

Hudson will show you a progress bar for your build…

And finally make available the build results:

This build happened to fail. To determine the cause of the failure take a look at the “Console Output” using the link on the left hand side.

In my case I see the following.

I include this error in this guide because I had the hardest time trying to fix this issue. I finally stumbled upon a post that helped. So after removing PLATFORM from my environment variables and restarting Windows the build results look like the following:

The job failed again, because 3 tests failed. This is exactly what we want. If the source code doesn’t build, the job fails and if any test doesn’t pass the job fails. Hudson provides a wealth of information. The “Console Output” window shows the commands that were issued by Hudson and the results. So I see the Hudson checking out my code from subversion….

…you see Hudson calling MSBuild to build the solution…

…you see the build succeeded and Hudson calling MSTest to start the tests…

…finally you can see the results of the tests.

As indicated above I have 3 tests that failed and the job fails as a result.

On the build status page, there is also a link to a “Test Result” report that provides a list of failed tests and links to more details.

From here you can dig right down to the stack trace information for the failed tests.

Continuous Integration

To kick off a build we can also navigate to the following URL:

http://YOURHOST/job/PROJECTNAME/build

where YOURHOST is your server / port and PROJECTNAME is the project name. You can get these parameters by looking at the URL in Hudson when your project is selected.

So in my instance I can trigger a build for this project by requesting the following URL:

http://hppav1:8080/job/Cron%20Project/build

This knowledge is key to having the source control system trigger Hudson to build a project.

Having Hudson perform builds based upon changes in the source code, requires that we install a post commit hook into the source control repository (Subversion) in my case. This will vary depending upon your source control system. For VisualSVN, I add a hook by right clicking on the repository and selecting the “All Tasks” – “Manage Hooks…” option.

I then configure a post commit hook to execute a Ruby script.

Notice in the above configuration the escape sequence for the percent sign. This took me hours to figure out. Please learn from my blood, sweat and tears.

The Ruby script takes an argument for the project name. Here is the Ruby script:

# Push a notice to the hudson server to initiate a build.

# Ensure the required libs are present
require "net/http"
require "uri"

# Get the project name
hudsonProject = ARGV[0]

# Create the uri and issue the request
uri = URI.parse("http://hppav1:8080/job/" + hudsonProject + "/build/")
Net::HTTP::get_print uri

Now whenever code is checked in, Hudson will be triggered to build and run the tests for the project.

Summary

Now we have Hudson configured to kick off a build whenever changes are committed to source control. Hudson has many other features worth exploring. For instance, the next step may be to setup email or IM notification of build results.