Hudson: Installation and Configuration for Dot.NET Projects

Hudson is a tool for continuous build, integration and deployment widely used in the Java world. Hudson can be used also with other platforms and programming languages and on many operating systems. A lot of plug-ins are available for Hudson.

For the Dot.NET world Hudson provides complete environment for continuous integration. The tool compile code with MSBuild, can run NAnt scripts, can run NUnit tests, check for code rules with FxCop or Gendarme, create documentation with Sandcastle.

The Hudson server by default provides integration with Subversion. It can be installed on Windows to run as a windows service.

The configuration of the jobs to run on the Hudson server is done completely from the web-based console of the tool. Also from there we install plug-ins.


Installing Hudson: Prerequisites

Installing Hudson on Windows is easy task. Following are the steps we needed in our case.

In this scenario we'll be using Hudson for Dot.NET development in conunction with the following tools: MSBuild, NUnit, FxCop, Gendarme, Sandcastle, so that we'll build, run unit tests, check code styles and create API documentation for our projects.

I will demonstrate using Subversion for source control system. But with Hudson you can easily use other version control systems too.

• Install Java. Hudson is a Java application.

Download Link: http://www.java.com/en/download/ie_manual.jsp

Add to the system environment variable %PATH% the directory name where the java.exe is:

"C:\Program Files (x86)\Java\jre6\bin"

Open new command window and try to check the version of Java installed:

C:\>java -version
java version "1.6.0_26"
Java(TM) SE Runtime Environment (build 1.6.0_26-b03)
Java HotSpot(TM) Client VM (build 20.1-b02, mixed mode, sharing)

• Install the Dot.NET SDKs you need.

You can install all together 2.0, 3.5, 4.0 and use one or another as needed. Check if the MSBuild is installed:

C:\Users\Administrator>"C:\Windows\Microsoft.NET\Framework\v2.0.50727\MSBuild"
Microsoft (R) Build Engine Version 2.0.50727.4016

C:\Users\Administrator>"C:\Windows\Microsoft.NET\Framework\v3.5\MSBuild"
Microsoft (R) Build Engine Version 3.5.30729.1

C:\>"C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild"
Microsoft (R) Build Engine Version 4.0.30319.1

You can even leverage this on that MSBuild version depending on the different projects you integrate in Hudson.

Add though the directory where the 4th version of Dot.NET is to the system PATH variable:

"%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\"

then test if you can run the MSBuild from new command prompt:

C:\>msbuild
Microsoft (R) Build Engine Version 4.0.30319.1
...

• Install the NUnit framework.

NUnit is a unit-testing (xUnit) framework. It comes with GUI tests runner and command line test runner.

Download Link: http://www.nunit.org/
In our case it is the version 2.5.10 from the URL:
http://launchpad.net/nunitv2/2.5/2.5.10/+download/NUnit-2.5.10.11092.msi

Once the NUnit is installed, configure a version of the runner for the Dot.NET 4.0 framework. Copy directory:

C:\Program Files (x86)\NUnit 2.5.10\bin\net-2.0

to:

C:\Program Files (x86)\NUnit 2.5.10\bin\net-4.0

Edit the nunit.exe.config file from the new directory and add at the end of that file:

<startup>
  <requiredRuntime version="v4.0.30319" />
</startup>

just before the closing "configuration" tag. Please note the version number, make the same as you've got installed.

Add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\NUnit 2.5.10\bin\net-4.0"

Open new console window and check to see if the command line test runner is in the %PATH%:

C:\>nunit-console-x86.exe
NUnit version 2.5.10.11092
Copyright (C) 2002-2009 Charlie Poole.
...

• Install FxCop.

FxCop is a tool from Microsoft that analyzes managed code assemblies and reports information about design, localization, performance and security improvements.

The tool comes a part of the Windows SDK for Windows 7 and Dot.NET 4.
All other installers of the FxCop are outdated, that's why we have to get the SDK on the machine.

Download the SDK from URL:
http://www.microsoft.com/downloads/en/confirmation.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b

Install with the default options.

The SDK was in our case installed into:

C:\Program Files\Microsoft SDKs\Windows\v7.1

The Samples into:

C:\Program Files\Microsoft SDKs\Windows\v7.1\Samples

A part of the SDK is the help library manager that gives you a chance to download locally on your computer part of the SDK documentation. The help library will be installed into:

C:\ProgramData\Microsoft\HelpLibrary\

and you (optionally) can install help content in there.

After this install finished, there is yet another installer now to run. The FxCop installer will be into directory:

C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\FXCop

Run the FxCopSetup.exe file from there.

The installer suggested in our case the following install folder:

c:\Program Files (x86)\Microsoft Fxcop 10.0\

After this installation finished, add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\Microsoft Fxcop 10.0"

Open new console window and test if you can run the application:

C:\>FxCopCmd.exe
Microsoft (R) FxCop Command-Line Tool, Version 10.0 (10.0.30319.1) X86
Copyright (C) Microsoft Corporation, All Rights Reserved.
...

• Install Gendarme.

Gendarme is part of the mono-tools. It a rule based tool for finding problems in .NET applications and libraries much like the FxCop is.

Download and install the tool from the following URL:
https://github.com/downloads/spouliot/gendarme/gendarme-2.10-win32-setup.zip


The installer suggested to following target folder:

C:\Program Files (x86)\Gendarme\

After this installation finished, add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\Gendarme"

Open new console window and test if you can run this application:

C:\>gendarme.exe
Gendarme v2.10.0.0
Copyright (C) 2005-2011 Novell, Inc. and contributors
...

• Install Sandcastle, htmlhelp and SHFB.

Sandcastle produces MSDN style documetation from the source assemblies integrating the XML documentation from the source code.

Download and install Sandcastle from:
http://sandcastle.codeplex.com/

In our case the installer suggested by default the following install directory:

C:\Program Files (x86)\Sandcastle\

Download and install the Microsoft HTML Help Workshop from:
http://go.microsoft.com/fwlink/?LinkId=14188

Run the downloaded file htmlhelp.exe and follow the instructions.

The default installation path was in our case:

C:\Program Files (x86)\HTML Help Workshop

Download and install the Sandcastle Help File Builder from:
http://shfb.codeplex.com/

Unpack the downloaded zip file and run the SandcastleInstaller.exe installer application. It comes with nice wizard GUI. Follow the instructions. The installer will ask you to download and install for you all the additional applications it will need in order to work. Just answer with "Yes" on those questions.

You will skip the installation of Microsoft Help 2, this is not a necessary part to have.

It also will ask you to apply a patch to Sandcastle. Answer with "Apply Patch" on this screen.

If you wish you can install also language pack for German language.

Optionally it will download for you the MAML guide - the guide from Microsoft for the documentation markup language, web project custom providers - a package with information for producing XML documents for web applications and website projects, a HTML to MAML converter.

If you don't have Visual Studio installed skip the section :MAML Schema InteliSense"

After this step it will suggest to install for you the SHFB - Sancastle Help File Builder. Cilck on "Install SHFB" on this screen.

The SHFB in our case was installed into:

C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\

On the last screen of the wizard click on the 'Reboot' in order all the changes to take effect on your system.

• Visual Studio Templates

If on the machine where Hudson will be running the visual studio is not installed you may need to come some Visual template files from developer's machine. For example copy to the machine the complete directory:

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

as for Visual Studio 2010 Express Edition with default installation path.



Installing Hudson: Prepare Visual Studio Project Structure for Hudson


To easily integrate a Visual Studio Project into Hudson, I would suggest the following project structure and files to be created.

Suppose we've got a project named "WebAPI"

In my project directories in Subversion I would prefer having structure like:

directory .\References - copy here all the third party DLLs you'll be referencing from the project

directory .\WebAPI - here is the project with the production code: a Visual Studio project named like the directory - WebAPI.csproj

From project properties in the Visual Studio, in section "Build" go to sub-section "Output" and enable check the box "XML documentation file". The name of the output file in "Debug" target build configuration should be the same as the specified in the Sandcastle project (below).

directory .\WebAPITests - contains the project with the unit tests for the WebAPI project: another Visual Studio project with Visual Studio project file named WebAPITests.csproj

The project with the unit tests references the project with the production code.

file WebAPI.sln - the Visual Studio solution file.

file WebAPI.shfbproj - the Sandcaslte project file

To create the Sandcastle project file run the "Sandcastle Help File Builder GUI" application. From the project properties the make the HelpFileFormat to be "HtmlHeml 1, Website".

Documentation sources are:

WebAPI\bin\Debug\WebAPI.dll
WebAPI\bin\Debug\WebAPI.XML

which is the output after compiling the WebAPI.csproj with target build configuration "Debug".

note the OutputPath from the "Project Properties" panel. The output goes to:

.\Help\

This is the directory to which we'll make link in Hudson for the API documentation of our project once the documentation is generated. That way we'll publish the generated from the continuous integration API documentation as a web-site.

file run-fxcop.bat - a batch command to run FxCop from Hudson. Example:

FxCopCmd.exe /file:WebAPI\bin\Debug\WebAPI.dll  /rule:DesignRules.dll /out:fxcop-result.xml

exit 0

note it takes the Debug output from the the WebAPI project and the output of running the FxCop application goes to file fxcop-result.xml.

file run-gendarme.bat - a batch command to run Gendarme from Hudson. Example:

gendarme.exe --xml gendarme-result.xml WebAPI\bin\Debug\WebAPI.dll

exit 0

note it takes the Debug output from the the WebAPI project and the output of running the Gendarme application goes to file gendarme-result.xml

file run-nunit.bat - a batch command to run NUnit tests from Hudson.

nunit-console-x86.exe WebAPITests\bin\WebAPITests.exe /xml=nunit-result.xml

exit 0

note it takes the Debug output from the the WebAPI project and the output of running the NUnit console goes to file nunit-result.xml

file run-sandcastle.bat - a batch command to generate documentation

MSBuild.exe /p:CopyrightText="Copyright Company" /p:FeedbackEMailAdress="address@company.com" WebAPI.shfbproj

exit 0

note we specify the MSBuild from the version 4.0 of Dot.NET and as a project file for the build project we point to the file WebAPI.shfbproj


And here we've got structure similar to this:

All the output xml files from the batch commands will be used by Hudson to show us results of running unit tests, checking code style, etc.



Installing Hudson: Installation

At this point we are ready to install the Hudson. We'll install Hudson as a Windows service on Windows.

• Prepare working directory

Create directory

C:\Hudson

In this directory Hudson will be installed. From the Windows control panel set up system environment variable:

HUDSON_HOME=C:\Hudson

Open new command prompt and test the new variable:

C:\>echo %HUDSON_HOME%
C:\Hudson

In this directory Hudson will check out from Subversion our code and will run the jobs to compile and run unit tests. So, this will be the Hudson's working directory. There Hudson will accumulate files with historical information.

• Install Hudson

Create directory where to install the Hudson server:

C:\Program Files (x86)\Hudson

Download into this directory the latest version of Hudson from:
http://java.net/projects/hudson/downloads/download/war/hudson-2.1.0.war

Note: you can always upgrade Hudson automatically to the latest version directly from the Hudson's web console - after the Hudson installed as windows service.

Rename the file as removing the version information from the file name. Check the install directory of the Hudson server:

C:\Users\Administrator>dir "C:\Program Files (x86)\Hudson"
08/20/2011  09:24 AM    <DIR>          .
08/20/2011  09:24 AM    <DIR>          ..
08/20/2011  09:23 AM        38,948,136 hudson.war

• Run Hudson

Now open a command prompt and go to this directory, run the Hudson server from there:

java -jar hudson.war
C:\Program Files (x86)\Hudson>java -jar hudson.war
Running from: C:\Program Files (x86)\Hudson\hudson.war
[Winstone 2011/08/20 14:11:50] - Beginning extraction from war file
Aug 20, 2011 2:11:52 PM hudson.WebAppMain contextInitialized
It will start doing  thinks, just wait until it says: "Completed initialization".
...
INFO: Home directory: C:\Hudson
...

note: look on the log messages, somewhere at the beginning it should say:

hudson home directory: C:\Hudson

Hudson will start by default HTTP web server on port 8080, open the following URL into your web browser, this is the Hudson's console there:
http://localhost:8080

• Install as windows service

Click on Hudson/Manage Hudson, then on “Install as Windows Service”. It will take time to finish.

Watch the application on the command prompt, it will restart as windows service. After the installation complete confirm to restart.

You can close the window with the command prompt. From here on only work happens on the web interface of Hudson!


Note: You can delete the service using this command:

sc delete hudson

Note: Later you can always upgrade to the latest version your copy of Hudson.

From the web console of Hudson go to Hudson\Manage Hudson and click on "Upgrade Automatically".
Wait for Hudson to finish the installation.
Click on "Restart when no jobs are running".

• Install Plug-Ins

Go to Hudson\Manage Hudson and click on Manage Plugins. Click on "Available" and select:

MSBuild Plugin
NAnt Plugin
NUnit Plugin
Analysis Collector Plugin
Static Code Analysis Plug-ins
Task Scanner Plugin
Violations
Warnings Plugin

Scroll down the page and click on "Install". After Hudson installed all those plugins, click on "Restart when no jobs are running".

Go to Hudson\Manage Hudson\Pugin Manager, open tab Installed and check if all these Plugins are installed:

Go to Hudson\Manage Hudson and click on "Configure System".
Scroll down to "MSBuild Builder" and click on "Add".

Write for name "MSBuild Dot.NET 4.0".
Write for path the full path name of the msbuild.exe file for Dot.NET 4.0, in our case it was

"C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe"

You can add for other Dot.NET frameworks if you need. Later from the concrete jobs you'll use them as appropriate in your case.

Scroll down, click "Save".


Configure Hudson: Add Jobs

Now we can add our project for continuous integration as a job on the Hudson server.

• Continuous build

This is a build which will be checking every minute for changes in the Subversion repository, if they are some changes will check out the latest changes, build our project and run the unit tests.

Click on Hudson\New job. Set the name of the job, in this example "WebAPI continuous build" and select the option "Build a free-style software project". Click on "OK".

In section "Source Code Management" select "Subversion". Set the Repository URL as appropriate.

Move the focus to another field. Hudson will try to access your Subversion server and if the authentication failed will show red colored message next to the text box with the repositiry URL. The message should contain an html link "enter credentials". Click the link and follow the instructions. Eventually you'll be able to give your user name and password if you choose this form of authentication.

Once you successfully finish this, you'll come back to the previous page.

In section "Build Triggers" select "Poll SCM" and specify "*/1 * * * *" to check every minute for changes in the source repository.

In section "Buld" click on "Add build step", then "Build a Visual Studio project or solution using MSBuild". Select/write (we are following the example file and VS project names from above):

MsBuild Version   : MS Buld Dot.NET 4.0
MsBuild Build File :  WebAPI.sln
Command line arguments :  /p:Configuration=DEBUG

Click on "Add build step", then on "Execute Windows batch command". Write:

run-nunit.bat

In section "Post-build Actions" select "Publish NUnit test result report and enter for "Test report XMLs:

nunit-result.xml

Click on Save to save the job. In short time Hudson should start a build for this job. If the build failed, check the "Console Output" from the job menus.

Note: you can at any time schedule run for a job. Go to the home page of the tool, click on the link to the job "WebAPI continuous build", from the left-side menus click on "Build now".

You can check the result of your unit tests from the link "Latest Test Result". Also you can browse your source code tree from the "Workspace" link and check for latest changes from the link "Resent Changes".


Now that we added a build project we've got nice dashboard on the home page of our Hudson server:

• Extended build

This is a build which will run once in a day and will run code-style checks and will create documentation for the API.

Click on Hudson\New job. Set the name of the job, in this example "WebAPI extended build" and select the option "Build a free-style software project". Click on "OK".

In section "Source Code Management" select "Subversion". Set the Repository URL as appropriate.

Move the focus to another field. Hudson will try to access your Subversion server and if the authentication failed will show red colored message next to the text box with the repositiry URL. The message should contain an html link "enter credentials". Click the link and follow the instructions. Eventually you'll be able to give your user name and password if you choose this form of authentication. Once you successfully finish this, you'll come back to the previous page.

In section "Build Triggers" select "Build periodically" and specify "40 02 * * *" - just an example - to run the job once a day at 02:40 PM.


In section "Buld" click on "Add build step", then "Build a Visual Studio project or solution using MSBuild". Select/write (we are following the example file and VS project names from above):

MsBuild Version   : MS Buld Dot.NET 4.0
MsBuild Build File :  WebAPI\WebAPI.csproj
Command line arguments :  /p:Configuration=DEBUG

Note: this only is going to build the project with production code, we don't need to build the complete Visual Studio solution, but won't be wrong as well.

Add one after other the following Windows batch commands clicking on the button "Add build steps" as "Execute Windows batch command":

run-fxcop.bat

run-gendarme.bat

run-sandcastle.bat

From the "Post-build Actions" section select "Publish Javadoc" and enter "help" as "Javadoc directory".

Then select "Report Violations" and configure the rows for fxcop and gendarme reports as appropriate.

Click on "Save" button down the page.


Click on "Build now" from the left-side menus of the project.

Once the build finished you can check for the generated documentation and the code violations.

Take some time to explore both of them, you'll find very useful suggestions in there.


Hudson: Links

Hudson CI Server: http://hudson-ci.org/
FxCop: http://msdn.microsoft.com/en-us/library/bb429476%28v=vs.80%29.aspx
NUnit: http://www.nunit.org/

Links to some of the Plugins we mentioned:
MSBuild Plugin: http://wiki.hudson-ci.org/display/HUDSON/MSBuild+Plugin
NAnt Plugin: http://wiki.hudson-ci.org//display/HUDSON/NAnt+Plugin
NUnit Plugin: http://wiki.hudson-ci.org//display/HUDSON/NUnit+Plugin
Analysis Collector: http://wiki.hudson-ci.org//display/HUDSON/Analysis+Collector+Plugin





Atanas Hristov

Design Patterns – State Pattern

The State design pattern is a behavioural pattern. The behaviour of object changes accordingly to its internal state. Instead of implementing if-then-else like structure inside the object to switch the behaviour, we move the logic to property "State" which has method Handle() and call this method. We change the behaviour of the object as we just switch the value of the "State" property.

The class which behaviour will change accordingly to its state is named Context. The Context class contains property State which is of type that implements common IState interface.

We have different implementations of IState - StateOne, StateTwo etc. We assign new IState object to the property "State" of the Context object and the behaviour of the Context object changes.

Traffic Light

Imagine we are going to implement traffic light. Accordingly to Wikipedia we have three possible lights: red; amber and green. The traffic light cycle may vary, but we are going to implement 3-way traffic light cycle.

• Red light - Means prohibits the traffic from proceeding.


• Green light - Then follows the green light that allows to proceed.


• Yellow light - Next is yellow light denoting if safe to, prepare to stop.

We will use the State pattern to implement a traffic light. The traffic light (TrafficLight) object is the context object. The traffic light has public properties for the color of the light currently turned on, it knows for how long this light should stay, and knows light of which color will follow after that. But setting these properties is done by State object.

We have 3 different states for the three traffic light colors. All they have method Handle() which is invoked by the TrafficLight object.

IState interface

All the concrete State classes have to implement interface ITrafficLightState. The concrete traffic light state handles request from the Context object and thereof the behaviour of the Context object changes.

        interface ITrafficLightState
        {
            void Handle(TrafficLight trafficLight);
        }

State implementations

For the different traffic light colors we implement three different State objects. All they implement interface ITrafficLightState:

        // State "Red Light"
        class RedLightState : ITrafficLightState
        {
            public void Handle(TrafficLight trafficLight)
            {
                trafficLight.Color = "Red"; // Switch the traffic light color
                trafficLight.Pause = 5; // For 5 seconds
                trafficLight.NextState = new GreenLightState(); // Then green light follows
            }
        }

        // State "Amber Light"
        class AmberLightState : ITrafficLightState
        {
            public void Handle(TrafficLight trafficLight)
            {
                trafficLight.Color = "Amber"; // Switch the traffic light color
                trafficLight.Pause = 2; // For 2 seconds
                trafficLight.NextState = new RedLightState(); // Then red light follows
            }
        }

        // State "Green Light"
        class GreenLightState : ITrafficLightState
        {
            public void Handle(TrafficLight trafficLight)
            {
                trafficLight.Color = "Green"; // Switch the traffic light color
                trafficLight.Pause = 5; // For 5 seconds
                trafficLight.NextState = new AmberLightState(); // Then Amber light follows
            }
        }

TrafficLight context object

How we are ready to implement the TrafficLight context object:

        // Context - "Traffic Light", has internal state - one of the above.
        // The behaviour changes accordingly to the current state
        class TrafficLight
        {
            // Has properties that define it's behaviour
            public int Pause { get; set; }
            public string Color { get; set; }

            // Has internal State
            public ITrafficLightState NextState { get; set; }

            // Sets the default state
            public TrafficLight()
            {
                this.NextState = new RedLightState();
            }


            // Receives request ...
            public void Request()
            {
                // ... then:
                // Delegates to the internal State to handle.
                NextState.Handle(this);

                // The behaviour has changed, color, time of light, etc.
                Console.WriteLine(Color);
                System.Threading.Thread.Sleep(Pause * 1000);
            }
        }

And with this we are ready to give a try of our implementation, which looks like this now:





To demonstrate the traffic light we run an infinite loop and call the method Request() on instance of TrafficLight:

        static void Main(string[] args)
        {
            // Demonstrate how TrafficLight works
            TrafficLight trafficLight = new TrafficLight();
            while (true)
                trafficLight.Request();
        }

Usage of State pattern

In our example the state of the Context object was changed from the state object itself. But it is not necessarily to be done this way. We can implement a Coffee Machine to run Short, Tall, Grand coffee. Then the state would be changed pressing a button on the Machine. Or we could use State pattern to switch between simple and advanced preview on a form. Then probably the Handle() function will just change the preview but not the user preferences.

Atanas Hristov