Albacore: Building .NET Applications with Rake

If you’re a .NET developer looking to move to Ruby, one of the ways you can start using Ruby straight away is with Albacore. In this article, we’ll look at how you can take an existing ASP.NET web application project, add a Rakefile, and build the project using Albacore.

What is Albacore?

Albacore is a set of extensions to Rake that deal specifically with building .NET-based projects. It has tasks to build, rebuild, and clean projects, run nunit, xunit, or mstest unit tests, copy files and expand templates, and generate assembly info.

.NET does come with it’s own build system called MSBuild. If you’re perfectly happy using this to build your projects, then that’s fine. You probably won’t get much from the rest of this article. If you like the sound of Albacore though and think it might be for you, then read on.

Background

First though, a bit of background in case you’re not familiar with Rake (if you do know what Rake is, feel free to skip this section). Rake is Ruby Make, a Ruby build program similar to Make. It revolves around tasks, which live in a Rakefile.

A simple example Rakefile looks something like this:

[gist id=”2878894″]

Here we have 3 tasks: foo, bar, and default. default has two dependencies: the foo and bar tasks. To run Rake, you type rake at the command-line. It then looks for a Rakefile in the current directory, and runs the default task by default. To run another task, you’d pass the task name as an argument to Rake e.g. rake foo. Using the example Rakefile above, you can see how the output differs:

[gist id=”2878949″]

Installing Albacore

As Albacore requires Rake (and, thus, Ruby), you’ll need to make sure you have Rake installed first. You probably have, but if you don’t, installing it is easy enough:

gem install rake 

With Rake installed, all that remains is to install Albacore:

gem install albacore 

Once you have Albacore installed, the only other proviso is to make sure you add require 'albacore' to your Rakefile, otherwise you won’t have access to the Albacore Rake tasks.

Converting an existing project to Albacore

To give you an idea of how you can use Albacore, we’ll create a new project in Visual Studio, add a Rakefile, then add some tasks to handle compiling the project, running unit tests, managing AssemblyInfo.cs, and preparing the project for deployment.

We’ll start by creating a default ASP.NET MVC application in Visual Studio. I went File -> New Project, and created a new ASP.NET MVC 4 Web Application (if you don’t have ASP.NET MVC 4 installed, any other ASP.NET web application should work just as well):

When prompted, I chose the Internet Application template, and created a unit test project as well:

You’re project should look something like this:

[gist id=”2878951″]

Now let’s create our Rakefile and start adding some tasks:

1. Create a text file called Rakefile in the root folder of your project (you can optionally give it an .rb file extension if you wish).
2. Add the following lines:

[gist id=”2878904″]

The first line makes the Albacore tasks available to us. Next, we create a default task and set the msbuild task as a dependency. Then we define the msbuild task, which will compile our code for us, using the solution and project files already created by Visual Studio. We set the build properties to use the debug configuration, set which targets we want to call, and tell the msbuild task where to find the solution file. Note that the path to the sln file is relative to the location of the Rakefile.

Verify this works by opening the command prompt, changing into your project’s root folder, and typing the following at the command prompt:

$> rake 

This calls the default task, which in turn will call the msbuild task and compile our project.

1. Next, create an mstest task to handle running our unit tests:

[gist id=”2878906″ ]

We tell the mstest task where to find the mstest executable, and give it the path to the dll file containing the tests we want to run. We’ve also given the task a dependency on the msbuild task, as we won’t be able to run the tests if the project hasn’t been compiled. To check this works, switch back to the command prompt and type the following:

$> rake mstest 

You should see the test output, and everything should pass.

1. Let’s add a task to populate our AssemblyInfo.cs class with the correct information. First, you’ll need to install the version_bumper gem:

$> gem install version_bumper

version_bumper requires a text file to hold the current version number. Create a text file called VERSION in the root folder of your project, and add the version number for your project in the format #.#.#.#. Mine looks like this:

[gist id=”2878920″]

Load the version_bumper using require, then add the assemblyinfo task:

[gist id=2878908]

To check this works type the following at the command prompt:

$> rake assemblyinfo 

then open up the AlbacoreDemo/Properties/AssemblyInfo.cs file and you should find the relevant properties have been set accordingly:

[gist id=2878899]

We’ll probably want the assemblyinfo task to run each time we compile our project, so add it as a dependency for the msbuild task:

[gist id=2878911]

1. Finally, let’s add an output task that will prepare all the files we’ll need to deploy the site:

[gist id=”2878912″]

First, we tell the task where we’re copy from, and to. Then we specify the files we want to copy using out.file, and the directories we want to copy with out.dir. Note the line out.file 'Web.Debug.config', :as => 'Web.config'.

This is similar to web.config transforms, but AFAIK doesn’t actually run the transforms; it just copies the file. Depending on how reliant you are on web.config transforms, YMMV with this, and you might get better results adding the config transforms as another target in your msbuild task.

1. Now we’ve added the tasks we need, we can tidy them up a bit by adding
   a configure block:

[gist id=2878915]

Here, we set the path to the mstest executable, and set the default targets for msbuild. The corresponding lines in the msbuild and mstest tasks can be removed.

The full Rakefile now looks like this. Note that we’ve changed the default task so that it builds, tests, and gets our site ready for deployment:

[gist id=”2878918″]

Albacore is available on GitHub. The wiki has extensive documentation on all supported tasks, so is a good place to find out more info. It also contains a link to some projects using Albacore in real life, so you can see how it’s being used in production.

Hopefully this has given you a taster for what you can do with Albacore, and how you could use it to start building existing .NET projects.