1. Why AutoComplete.Net?
2. Download
3. Asp.Net Documentation
3.1. AutoCompleteTextBox
3.2. Tutorial
4. Asp.Net MVC Documentation
4.1. Extension Methods
4.2. Tutorial

1. Why AutoComplete.Net?

In this article I will introduce my CodePlex project: AutoComplete.Net.

Such project is made up of a library containing an Asp.Net WebControl and a bunch of Asp.Net MVC HtmlHelper extension methods.
Their purpose is to provide .Net developers with an easy interface to the cool JQuery UI Autocomplete Widget.

I will describe separately the Asp.Net WebControl and the Asp.Net MVC extension methods.

→ top of post

2. Download

Download the latest version of AutoComplete.Net here.
You will get a zip package containing the binary and few other files.
Unzip the release package wherever you want,
e.g. under C:\Program Files\AutoComplete.Net.
For most of the time you will need only the AutoComplete.dll but in the following paragraphs you will be instructed about when you will need the other files included in the release package.

→ top of paragraph
→ top of post

3. Asp.Net Documentation

3.1. AutoCompleteTextBox

The AutoCompleteTextBox WebControl found in the AutoComplete.dll assembly exposes the following properties:

MinCharsRequired

Specifies the minimum number of characters to digit before the autocomplete is fired and the ajax request to the server is started.
The default value is: 2, so you can ignore this property if you feel confortable with such value.

JsonDataSourceUrl

This is the most important property.
Here you must specify an Uri identifying a resource returned in Json format.
The value you will specify will represent the place to retrieve the source data from.
Tipically you will provide the address of an Http Handler.
This is a required property so you have to provide a valid url.
You can safely use the ~ (tilde) character in the url provided.

Example:
JsonDataSourceUrl=”~/CountriesHandler.ashx”

HttpMethod

Specifies the method to be used for the http invocation.
It will be used to instruct JQuery about how to send the underlying ajax invocation.
The legal values are: GET and POST.
If a value is not specified for this property it will default to GET.
I suggest not to use the POST option because the autocomplete widget works invoking an ajax request at each key pressed.
Such an high number of ajax post requests causes Internet Explorer to receive an error 12030 from the server.
I planned to refine the behavior of the control to do some more work on the client, in order to workaround this problem. In the meanwhile GET is the option to go with and also the natural choice when invoking an Http Handler.

LabelField

Specifies the name of a property of the returned object type that will be used to fill the suggestions displaied in the list.
If this property is not set, the value in the property: ValueField will be used as LabelField as well.

ValueField

Specifies the name of a property of the returned object type.
Such property will be used to fill the textbox once one of the items in the suggestions list has been selected.
If a LabelField property is not specified, this property’s value will be used as LabelField value in the autocomplete initialization.
This is a required property.

OnClientSelection

If you need some more client side processing of the data related to the item selected you can use this property to specify the name of a javascript function.
The javascript function specified will be invoked when an item in the list is selected.
You must define the javascript function with the following signature:

function OnClientSelectionHandler(selectedItem)

The argument passed to this function: ‘selectedItem’ is a client side representation of the server side object instance corresponding to the selected item.
In this way you can access all the properties (and then retrieve all available information) about the selected item.
You can, for example, set a hidden field as in the following sample code:

 // set hidden field with the value corresponding to the selected item.
 function OnClientSelectionHandler(selectedItem) {
	 var codeHiddenField = '<%=(FindControl("SelectedCountryHiddenField").ClientID)%>';
	 $('#' + codeHiddenField).val(selectedItem.Code);
	 alert("Code value is: " + $('#' + codeHiddenField).val());
 }

OnClientError

If you want to notify errors happened during the ajax request to the server, you can set this property to specify the name of a javascript function.
The javascript function specified will be invoked when an error occurs during the ajax request.
You must define the javascript function with the following signature:

function NotifyError(error)

The argument ‘error’ passed to this function is a message describing the error happened.

RegisterJQueryAndJQueryUI

Instructs the control wether to emit script tags to include references to jquery.js and to jquery-ui.js.

<script type="text/javascript" src="/Scripts/jQuery-1.4.1.js"></script>
<script type="text/javascript" src="/Scripts/jquery-ui.js"></script>

By setting this property to “true” or “false” you can decide if a reference to the jquery and jquery UI javascript libraries is required or they’re already declared in the page.
The versions bundled with the WebControl are: jquery 1.4.4 and JQuery UI 1.8.7.
The default value is false, so the control won’t work unless you drop it in a page containing the required references or you explicitly set the property as below:

RegisterJQueryAndJQueryUI="true" 

RegisterDefaultStyleSheet

Instructs the control wether to emit a link reference to the default stylesheet for the autocomplete dropdownlist.
The reference will be emitted if this property is set to “true” and it will point to a .css file embedded as resource in the AutoComplete.dll assembly.
The Stylesheet has been built with the Jquery UI ThemeRoller.
If a JQuery UI full theme has already been added to the page, setting this property is not necessary.
Worse it could override the style set at page level.
Default value is true.

If you want to have a look at the style rules applied to the AutoComplete widget you can find, in the release package, the file: jquery-ui.css and have a look.

The style relative to the Autocomplete widget starts at row: 304:

.ui-autocomplete { position: absolute; cursor: default; font: normal 82.5% inherit; }
.ui-autocomplete-loading { background: white url('images/ui-anim_basic_16x16.gif') right center no-repeat; }

/* workarounds */
* html .ui-autocomplete { width:1px; } /* without this, the menu expands to 100% in IE6 */

In the rule:

.ui-autocomplete 
{ 
  position: absolute; cursor: default; font: normal 82.5% inherit; 
}

The rule: ‘ui-autocomplete-loading’ has been removed in the stylesheet produced by recent versions of the ThemeRoller because the ThemeRoller itself is not able to produce the required image too.
I modified the stylesheet by restoring this rule, retrieved from a previous version (JQuery UI 1.8.2).
I also added to the package the corresponding image, retrieved from the same version (1.8.2).

If you want to see the spinner image in the textbox you need to place it in a folder named: ‘images’ in the root of the web application.
If you want to place it elsewhere you need to modify the stylesheet rule with the desired file path and rebuild the WebControl.

If you want to customize the stylesheet without recompiling the control, just set the
RegisterDefaultStyleSheet property to “false” and place the jquery-ui.css file you find in the release package wherever you want in the website directory structure, e.g.: {root}\Style.
Then add to the head of the page the following snippet:

<link href="/Style/jquery-ui.css"
	  rel="stylesheet" 
	  type="text/css" />

You can then modify the stylesheet as you like.

NoResultsMessage

If the letters you typed in the textbox led to no results, the textbox will still be empty and no suggestion list will popup.
With this property you can provide an informational message, to be displaied in the autosuggest list in case the ajax request returns an empty resultset, as you can see in the image below:

Obviously if the user selects the item in the suggestion list, nothing will happen: the TextBox will not be filled with the value and the OnClientSelection handler will not be invoked.

ErrorMessage

This property specifies the text to be displaied in the autosuggest list when an error occurs during the ajax request.
Such property will be used to display an informational message in the suggestions list, in case of error.
The behavior is the same as in the previous property.

→ top of paragraph
→ top of post

3.2. Tutorial

Let’s see how to create an example application to test the AutoCompleteTextBox WebControl for Asp.Net.

First of all create a new Visual Studio Solution and add a new Asp.Net Web Application project.
Download the latest version of AutoComplete.Net and unzip the release package wherever you want.
Browse to the folder in which you unzipped the release package and locate the AutoComplete.dll assembly. Copy and paste it in the folder in which you want your Visual Studio Solution to find it.
You can then place it in a folder common to all projects on the machine (it can be even the same: C:\Program Files\AutoComplete.Net) or in a folder specific to the current solution.
I usually create a Libs folder in the root of the solution and show its contents in Visual Studio by adding a Solution Folder with the same name.

Add a reference to the assembly in your web application project.

Go to the ToolBox and select the Tab in which you want the AutoCompleteTextBox to appear (create a new tab if you want), then select:

Tools –> Choose ToolBox Items…, browse to find the AutoComplete.dll and confirm.

Now you’re ready to drag and drop the AutocCompleteTextBox control.
Go to the Web page in which you want to add the control, e.g.: Default.aspx.
Place the cursor in the exact position in which you want to drop it, go to the ToolBox window and double click the control.

As you can see in the image above you will find the control registered at the top of the page:

<%@ Register Assembly="AutoComplete" Namespace="AutoComplete" TagPrefix="IM" %>

and a control instance declared at the row where you placed the cursor:

<IM:AutoCompleteTextBox ID="AutoCompleteTextBox1" runat="server" 
                        JsonDataSourceUrl=""
                        ValueField="" />

Maybe you need some formatting to see it exactly as above and maybe you want to change the ID (by removing the ’1′ at the end for example!).

The control instance requires you to provide a value at least for the two properties you find explicitly set in the control declaration: JsonDataSourceUrl and ValueField

If you run the page as is, you will get the following exception:

Required property: JsonDataSourceUrl for: AutoCompleteTextBox1
A value must be provided for the specified property.

You need to provide an url address to a resource returning a result in JSon format, as a value for the property: JsonDataSourceUrl.
Below you will se a simple way to provide such a resource just to test the WebControl.
You can add few simple classes to your web application (remember to add using statements as needed).

First add an IHttpHandler to your project, name it CountriesHandler and replace the ProcessRequest method with the following code:

public void ProcessRequest(HttpContext context)
{
	context.Response.ContentType = "application/json";
	context.Response.ContentEncoding = Encoding.UTF8;
	string startsWith = context.Request["startsWith"];

	CountriesRepository repository = new CountriesRepository();
	IEnumerable<Country> countries = repository.GetCountriesStartingWith(startsWith);

	JavaScriptSerializer serializer = new JavaScriptSerializer();
	context.Response.Write(serializer.Serialize(countries));
}

then add a new class named: Country defined as below:

public class Country : IEquatable<Country>
{
	public Country(RegionInfo region)
	{
		Name = region.EnglishName;
		Code = region.TwoLetterISORegionName;
	}

	public string Name { get; set; }

	public string Code { get; set; }

	#region IEquatable<Country> Members

	public bool Equals(Country other)
	{
		if (ReferenceEquals(other, null)) return false;
		return Code.Equals(other.Code) && Name.Equals(other.Name);
	}

	#endregion

	public override int GetHashCode()
	{
		return Name.GetHashCode() ^ Code.GetHashCode();
	}
}

The IEquatable implementation and the GetHashCode override are needed to avoid duplicate countries in the lists.
Then add another class: CountriesRepository defined as below:

public class CountriesRepository
{
	readonly IEnumerable<Country> countries;

	public CountriesRepository()
	{
		countries = (from culture in CultureInfo.GetCultures(CultureTypes.SpecificCultures)
			  select new Country (new RegionInfo(culture.LCID)))
			  .Distinct<Country>()
			  .OrderBy(n => n.Name);
	}

	public IEnumerable<Country> GetCountriesStartingWith(string startsWith)
	{
		var result = from country in this.countries
			  where country.Name.StartsWith(startsWith, StringComparison.InvariantCultureIgnoreCase)
			  select country;
		return result;
	}
}

Now you can set the first property as follows:
JsonDataSourceUrl=”~/CountriesHandler.ashx”

If you run your application you still get an exception because the ValueField property is required too:

Required property: ValueField for: AutoCompleteTextBox1
A value must be provided for the specified property.

By setting such property you tell the control wich property of the object returned will be used to fill the autosuggest list.
Set the property as below:

ValueField=”Name”

Now the control is configured correctly and the page will load but you will get an alert, warning you that you forgot to add a reference to the JQuery library:

Now you have to made a choice: you can tell the WebControl to provide by itself a reference to the required javascript libraries (Jquery and JQueryUI) or to rely on the page in which it’s contained to include references to the right javascript libraries.

If you want to use the control in a page in which you already use JQuery for other purposes you will have your reference right in place in the head of the page:

<head runat="server">
    <title></title>
    <script type="text/javascript" src="/Scripts/jQuery-1.4.1.js"></script>
    <script type="text/javascript" src="/Scripts/jquery-ui.js"></script>
</head>

If this is not the case you can simply set another property of AutoCompleteTextBox:

RegisterJQueryAndJQueryUI=”true”

You’re ready to use your Page.
Just type ‘in’ in the textbox and you will get a list of country names starting with ‘in’.
If you type few random letters, say: ‘ee’ you won’t see any result.
If you prefer to be prompted with a message you can set the following property:

NoResultsMessage = “No results”

Still you miss a pretty aesthetic functionality: you can have a loading image spinning inside the textbox while waiting that the information is retrieved.
The WebControl already looks for such image. You only need to provide it in a path in which the control can find it.
In the folder in which you unzipped the release package you can find the file:

ui-anim_basic_16x16.gif

In your Visual Studio Solution add a folder named: Images to the web application root folder and place the gif file inside it. That’s it!
Reload the page, type ‘un’ and you will see the spinner for a while before the results are presented.

If you want to place the spinner image elsewhere, for instance if you already have an images folder but with a different name, you can modify the default stylesheet as explained in the paragraph: RegisterDefaultStyleSheet.

You must download the source of the project, open the stylesheet jquery-ui.css, go to row: 305:

.ui-autocomplete-loading 
{ 
   background: white url('images/ui-anim_basic_16x16.gif') right center no-repeat; 
}

and replace the relative path in the url with the path you want.

If you want to customize the stylesheet without recompiling the control, just set the
RegisterDefaultStyleSheet property to “false” and place the jquery-ui.css file you find in the release package wherever you want in the website directory structure, e.g.: {root}\Style.
Then add to the head of the page the following snippet:

<link href="/Style/jquery-ui.css"
	  rel="stylesheet" 
	  type="text/css" />

You can then modify the stylesheet as before.

By default the WebControl adds a reference to the default autocomplete stylesheet jquery-ui.css we saw above.
The stylesheet has been built with the Jquery UI ThemeRoller.
If a theme has already been added to the page, the WebControl’s default theme is not necessary and could override the style defined in the page.
In this case you should disable the default stylesheet by setting the following property as below:

RegisterDefaultStyleSheet=”false”

After the user selects the chosen item in the list of suggestions, you can do whatever you want with all the data available about the selected item.
In this case you have ‘Code’ and ‘Name’ of the selected Country.
Say you want to save the ‘Code’ in a hiddenfield in order to send it to the server during the next submit/postback.
You can write your own javascript function and the AutoCompleteTextBox will provide the function with the information about the selected country.
Just set the following property:

OnClientSelection=”SaveCodeForLaterUse”

add the following hidden field inside the form tag:

<asp:HiddenField ID="SelectedCountryHiddenField" runat="server" />

and add the following block of javascript immediately after the opening tag of the form element of the page:

<script type="text/javascript">
//<![CDATA[

// set hidden field with the value corresponding to the selected item.
function SaveCodeForLaterUse(selectedItem) {
    var codeHiddenField = '<%=(FindControl("SelectedCountryHiddenField").ClientID)%>';
    $('#' + codeHiddenField).val(selectedItem.Code);
    alert("Code value is: " + $('#' + codeHiddenField).val());
}

//]]>
</script>

The argument passed to the javascript function (selectedItem) represents an instance of a Country object and exposes the same properties as its server side counterpart: Name and Code.

The full declaration now is:

<IM:AutoCompleteTextBox ID="CountriesAutoCompleteTextBox" runat="server" 
			JsonDataSourceUrl="~/CountriesHandler.ashx"
			ValueField="Name" 
			RegisterJQueryAndJQueryUI="true" 
			NoResultsMessage = "No results"
			OnClientSelection="SaveCodeForLaterUse" />

Note:
If you place the above script in the head section, the control (and the page as well) won’t be able to manipulate the head anymore because the page header is readonly when there are codeblocks inside it.
The control needs to manipulate the header to add the default stylesheet.
If you don’t mind about it or if you are willing to add the stylesheet by yourself you can safely place your script in the page head section.
If you won’t use code blocks in your javascript function you can place the script in the page header as well.

→ top of paragraph
→ top of post

4. Asp.Net MVC Documentation

4.1. Extension Methods

WORK IN PROGRESS

→ top of paragraph
→ top of post

4.2. Tutorial

Let’s see how to create an example application to test the Asp.Net Mvc AutoComplete Extensions.

First of all create a new Visual Studio Solution and add a new Asp.Net Mvc Web Application project.

Download the latest version of AutoComplete.Net and unzip the release package wherever you want.
Browse to the folder in which you unzipped the release package and locate the AutoComplete.dll assembly. Copy and paste it in the folder in which you want your Visual Studio Solution to find it.
You can then place it in a folder common to all projects on the machine (it can be even the same: C:\Program Files\AutoComplete.Net) or in a folder specific to the current solution.
I usually create a Libs folder in the root of the solution and show its contents in Visual Studio by adding a Solution Folder with the same name.

Add a reference to the assembly in your Asp.net Mvc Web Application project.

First of all make some room in our new project: delete the controllers and model classes created by the project template:

AccountController.cs and HomeController.cs under the folder: Controllers
AccountModels.cs under the folder: Models
folders: Account and Home under the folder: Views
Remove the content of the Shared folder under the folder: Views

Create a folder named: Countries under the folder: Views, right click it and choose: Add… –> View.
Name it: Search and uncheck: ‘Select master page’.

A new page: Search.aspx will open.
Now you can add the markup for the AutoComplete control inside the main div of the page (together with a label):

<label for="country">Country:</label>

<%= Html.AutoCompleteTextBox("country", 
			     new Uri("/Countries/SearchByFirstLetters", UriKind.RelativeOrAbsolute), 
			     "Name") %>

Visual Studio will warn you that it cannot find the AutoCompleteTextBox extension method.
You need to instruct it about the namespace.
You can do it once for all in the web.config of the application:
Just open it and add:

<add namespace="AutoComplete"/>

to the namespaces in the tag:

<system.web>
    <pages>
        <namespaces>

or you can do it page by page using the import directive at the top of the page:

<%@ Import Namespace="AutoComplete" %>

In each case just rebuild the project and the Visual Studio error message will disappear.

The first argument we passed to the AutoCompleteTextBox extension method (“country”) will be the id of the html input field.
The second argument is the uri of the resource that will be invoked and the third argument is the name of the property to be used, of the objects returned by the uri resource, to populate the suggestions list.

The uri: “/Countries/SearchByFirstLetters” invoked in an Asp.Net MVC Web Application with the default routes in place will cause a controller named: CountriesController to be searched for.
Let’s add such a controller in the folder Controllers.
Let’s add to the controller the method that will be invoked when our view is loaded.
The method, by convention, will be called: Search and we will replaced it to the method: Index created by the controller template.
Here is the first method of our newly created controller:

//
// GET: /Countries/Search/

public ActionResult Search()
{
	return View();
}

if you now type the url: Countries/Search you will get the following javascript alert:

In fact we still didn’t add the required javascript references in the head of the page.
We need a reference to JQuery, a reference to JQueryUI and a reference to the IM.AutoComplete.js javascript library.
Go to the folder in which you unzipped the release package and locate the following files:
jquery-ui.js
IM.AutoComplete.js

Copy and paste the 2 files in the Scripts folder of your project and add the following references to the head of the Search.aspx view:

<script type="text/javascript" src="/Scripts/jQuery-1.4.1.js"></script>
<script type="text/javascript" src="/Scripts/jquery-ui.js"></script>
<script type="text/javascript" src="/Scripts/IM.AutoComplete.js"></script>

Still the autocomplete functionality won’t work unless we add to the controller a SearchByFirstLetters method returning a JsonResult, representing the required resource.
Below you will see a simple way to provide such a resource just to test the Extension method.
You need to add a couple of simple classes to your Asp.Net Mvc Web Application.
First add a method named SearchByFirstLetters to your controller:

public ActionResult SearchByFirstLetters(string startsWith)
{
	if (!Request.IsAjaxRequest())
	{
		return Content(string.Empty);
	}

	CountriesRepository repository = new CountriesRepository();
	IEnumerable<Country> countries = repository.GetCountriesStartingWith(startsWith);
	return Json(countries.ToList(), JsonRequestBehavior.AllowGet);
}

Note:
we’re allowing the SearchByFirstLetters method to be invoked by e GET request because
internet explorer randomly causes HTTP errors when sending too many post requests to a server.

Now add the following two classes to the: Models folder.

public class Country : IEquatable<Country>
{
	/// <summary>
	/// Needed by Asp.Net Mvc framework.
	/// </summary>
	public Country()
	{

	}
	
	public Country(RegionInfo region)
	{
		Name = region.EnglishName;
		Code = region.TwoLetterISORegionName;
	}

	public string Name { get; set; }

	public string Code { get; set; }

	#region IEquatable<Country> Members

	public bool Equals(Country other)
	{
		if (ReferenceEquals(other, null)) return false;
		return Code.Equals(other.Code) && Name.Equals(other.Name);
	}

	#endregion

	public override int GetHashCode()
	{
		return Name.GetHashCode() ^ Code.GetHashCode();
	}
}

The IEquatable implementation and the GetHashCode override are needed to avoid duplicate countries in the lists.
Then add another class: CountriesRepository defined as below:

public class CountriesRepository
{
	readonly IEnumerable<Country> countries;

	public CountriesRepository()
	{
		countries = (from culture in CultureInfo.GetCultures(CultureTypes.SpecificCultures)
			    select new Country (new RegionInfo(culture.LCID)))
			    .Distinct<Country>()
			    .OrderBy(n => n.Name);
	}

	public IEnumerable<Country> GetCountriesStartingWith(string startsWith)
	{
		var result = from country in this.countries
			    where country.Name.StartsWith(startsWith, StringComparison.InvariantCultureIgnoreCase)
			    select country;
		return result;
	}
}

Now you can run the web site and type the url: Countries/Search.
You will get the page and can type the first 2 letters of a country to get suggestions.

Still the suggestions list is not very stylish. We forgot to add our default style sheet that was generated with the Jquery UI ThemeRoller (if you read the Asp.Net tutorial you know that the AutoCompleteTextBox WebControl added the reference by itself).
Go to the folder in which you unzipped the release package and locate the file:
jquery-ui.css

Copy and paste it in the Content folder of your project and add the following reference to the head of the Search.aspx view:

<link href="/Content/jquery-ui.css"
	  rel="stylesheet" 
	  type="text/css" />

If a theme has already been added to the page, this default theme is not necessary and could accidentally override the style defined in the page.

You can also have a loading image spinning inside the textbox while waiting for the information to be retrieved.
In the release package you can find the file:

ui-anim_basic_16x16.gif

In your Visual Studio Solution add a folder named: Images under the Content folder and place the gif inside it.
That’s it!
Reload the page, type ‘un’ and you will see the spinner for a while before the results are presented.

If you want to place the spinner image elsewhere, for instance if you already have an images folder but with a different name, you can modify the default stylesheet as explained in the ASP.NET WebControl section at the paragraph: RegisterDefaultStyleSheet.

You must modify the stylesheet file found in the release package: jquery-ui.css. Open the file and go to row: 305:

.ui-autocomplete-loading 
{ 
   background: white url('images/ui-anim_basic_16x16.gif') right center no-repeat; 
}

then replace the relative path in the url with the path you want.

There’s plenty of overloads to the AutoCompleteTextBox extension method we used but there’s another and more notable series of extension methods: the strongly typed ones, named: AutoCompleteTextBoxFor.

Let’s add another View under the Countries folder and call it: StronglyTypedSearch,
check the ‘Create a strongly-typed view’ checkbox and select:
AspNetMvcAutoComplete.Models.Country as ‘View data class’,
select the ‘Edit’ ‘View content’ and
uncheck the ‘Select master page’ checkbox.

Remove the fields related to the Code property and the Actionlink at the bottom of the page.
Replace:

<%= Html.TextBoxFor(model => model.Name) %>

with:

<%= Html.AutoCompleteTextBoxFor(model => model.Name, 
				new Uri("/Countries/SearchByFirstLetters", UriKind.RelativeOrAbsolute)) %>

and place the label in the same div as the textbox.
Add to the head of the page the same references as in the Search.aspx view:

<script type="text/javascript" src="/Scripts/jQuery-1.4.1.js"></script>
<script type="text/javascript" src="/Scripts/jquery-ui.js"></script>
<script type="text/javascript" src="/Scripts/IM.AutoComplete.js"></script>
<link href="/Content/jquery-ui.css"
	  rel="stylesheet" 
	  type="text/css" />

The page will now look like the following:

<%@ Page Language="C#" Inherits="System.Web.Mvc.ViewPage<AspNetMvcAutoComplete.Models.Country>" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>StronglyTypedSearch</title>
    <script type="text/javascript" src="/Scripts/jQuery-1.4.1.js"></script>
    <script type="text/javascript" src="/Scripts/jquery-ui.js"></script>
    <script type="text/javascript" src="/Scripts/IM.AutoComplete.js"></script>
    <link href="/Content/jquery-ui.css"
          rel="stylesheet" 
          type="text/css" />
</head>
<body>
<% using (Html.BeginForm()) {%>
	<%= Html.ValidationSummary(true) %>
	
	<fieldset>
		<legend>Fields</legend>
		
		<div>
			<%= Html.LabelFor(model => model.Name) %>            
			<%= Html.AutoCompleteTextBoxFor(model => model.Name, 
							new Uri("/Countries/SearchByFirstLetters", UriKind.RelativeOrAbsolute)) %>                
			<%= Html.ValidationMessageFor(model => model.Name) %>
		</div>
		
		<p>
			<input type="submit" value="Save" />
		</p>
	</fieldset>

<% } %>
</body>
</html>

Add the DisplayNameAttribute to the Name property of the Country class if you want a meaningful label, e.g.:

[DisplayNameAttribute("Country:")] 
public string Name { get; set; }

Add a method named StronglyTypedSearch to the controller (CountriesController):

public ActionResult StronglyTypedSearch()
{
	return View();
}

so that it will be invoked when typing the url: ‘Countries/StronglyTypedSearch’.

If you add the following method to the controller, to manage the submit of the page, you will be able to debug and see the selected value sent back to the server:

[AcceptVerbs(HttpVerbs.Post)]
public ActionResult StronglyTypedSearch(Country country)
{
	return View(country);
}

Now just run the website and type the above url.
Type few letters in the textbox and select a country.
Place a breakpoint in the method above and hit the save button.
You can now watch the argument passed to the method and notice that the Name property is correctly set based on your selection.

You can download the full sample code: AutoCompleteNetExamples Source Code at the project home page.

→ top of paragraph
→ top of post

Suggested Books

1. Introduction
2. Description
2.1. Implementation
2.2. Strongly Typed Extension Methods
3. Full Code
3.1. PanelExtensions
3.2. MvcPanel
3.3. TestView
3.4. StronglyTypedView
3.5. ViewModel
3.6. Controller

1. Introduction

In this article I will describe, step by step, my implementation of a simple Panel widget to be used in ASP.NET MVC web applications.

The goal is to be able to wrap some markup in a content area with a describing title at the top.

The usual way to wrap logically related content when writing Html is to encapsulate it in a <div> tag, so my Panel will be little more than this.

I will try to underline the few main concepts I used in my implementation so that anyone could implement a similar helper method.

→ top of post

2. Description

• 2.1. Implementation
• 2.2. Strongly Typed Extensions Methods

2.1. Implementation

I liked very much the smart use the ASP.NET MVC team made of IDisposable to support the using syntax in the BeginForm() helper method.

So I downloaded and browsed the source code trying to understand how the whole thing works.

I found the following two classes:

mvc3\src\SystemWebMvc\Mvc\Html\FormExtensions.cs

mvc3\src\SystemWebMvc\Mvc\Html\McvForm.cs

The FormExtensions class provides two extension methods:

Html.BeginForm() (with a bunch of overloads) and

Html.EndForm()

Both the methods write directly to the HttpResponse output instead of returning an MvcHtmlString.

In fact all the BeginForm() overloads return an instance of MvcForm (more about it below) and the EndForm() method is void.

We can invoke the two methods at the right moment, at the beginning and at the end of the form, to render an opening <form> tag and a closing </form> tag.

<% Html.BeginForm() %>
   ...form contents
<% Html.EndForm() %>

But what I like most is the possibility to invoke the BeginForm method in an inline code block like the following:

<% using (Html.BeginForm()) { %>
...form contents
<% } %>

This syntax is supported thanks to the fact that the BeginForm() methods return an instance of MvcForm.

This class implements IDisposable in a very particular way:

The body of the MvcForm.Dispose(bool disposing) method writes to the HttpResponse output a closing <form> tag as the FormExtensions.EndForm() does.

We can invoke the BeginForm() method inside a using block relying on the .Net Framework to invoke the Dispose() method on the instance of MvcForm returned by BeginForm() and so be sure that the form will be closed.

Based on what you read this far, we will create a PanelExtensions class in which we will add our
extension methods and a MvcPanel class that will be the analogous of the MvcForm class seen above.

The core functionality of the extension methods will make use of the TagBuilder utility class to output Html.

That class allows us to build an html tag with an object oriented syntax.

Our method won’t return an MvcHtmlString but will write directly to the HttpResponse and it will return an instance of the MvcPanel class.

The MvcPanel class will implement IDisposable.

The following code is an example of what the body of an extension method could be (with hardcoded values at the moment), based on the assumption that it will render a <div> for the title of the panel and a <div> for the content:

// title panel
TagBuilder titleTagBuilder = new TagBuilder("div");
titleTagBuilder.MergeAttributes(new RouteValueDictionary(new {title="title tooltip text"}));
titleTagBuilder.AddCssClass("titleClass");
titleTagBuilder.SetInnerText("This is the title");

// content panel
TagBuilder tagBuilder = new TagBuilder("div");
tagBuilder.MergeAttributes(new RouteValueDictionary(new {title="content tooltip text"}));
tagBuilder.AddCssClass("contentClass");

HttpResponseBase httpResponse = helper.ViewContext.HttpContext.Response;
httpResponse.Write(titleTagBuilder.ToString(TagRenderMode.Normal));
httpResponse.Write(tagBuilder.ToString(TagRenderMode.StartTag));

return new MvcPanel(httpResponse);

As we can see the TagBuilder class exposes a constructor accepting a string with the name of the tag to write.

We then make use of the MergeAttributes() method. Such method accepts an IDictionary<string, object> that is supposed to contain pairs of key/values representing html attributes applicable to the tag specified in the constructor.

To invoke the MergeAttributes() method we create an instance of an anonymous type and then we pass it to a RouteValueDictionary class.

In this way we rely on it to parse correctly the anonymous type instance and to use it to initialize its own contents.

We then use the RouteValueDictionary instance as the IDictionary to pass as parameter to the MergeAttributes() method.

The AddCssClass() method accepts the name of a css rule to apply to the rendered tag and, eventually, the SetInnerText() method accepts some text that will be contained between the open and close tag.

When it’s time to write in the HttpResponse we use the ToString() method of the TagBuilder class.

Such method accepts a parameter of type: TagRenderMode.

TagRenderMode is an enumeration used to specify any of the four ways in which we can write a tag:

• Normal: an open tag, some content and a close tag: <div>some content</div>
• StartTag: only the open tag: <div>
• EndTag: only the closing tag: </div>
• SelfClosing: a tag without content: <br />

We write to the HttpResponse the complete title div but only the opening tag of the content div.

Here you can see how the preceding code will be rendered:

<div class="titleClass" title="title tooltip text">
This is the title
</div>
<div class="contentClass" title="content tooltip text">

The very last row in the code snippet returns to the caller an instance of the MvcPanel class, passing to the MvcPanel constructor an instance of the current HttpResponse.

MvcPanel accepts an HttpResponse in the constructor in order to be able, later, to write the closing tag to the response at the right moment.

MvcPanel, in fact, implements the IDisposable interface.

Its Dispose() method invokes a call to the HttpResponse.Write() method writing a div’s closing tag:

protected virtual void Dispose(bool disposing)
{
	if (!this.disposed)
	{
		this.disposed = true;
		this.httpResponse.Write("</div>");
	}
}

If invoking the extension method with the using statement, the .Net framework runtime, upon exiting the using block, will call Dispose() on the MvcPanel instance returned by the extension method. We will then obtain the end of the panel (i.e.: a closing div tag).

In the PanelExtensions class we provide many overloaded extension methods accepting different sets of arguments and all of them, in the end, will call the overload really doing the job.

Such overload is the one with the greatest number of arguments.

The body of this extension method will be analogous to the code snippet above but with the arguments passed to the TagBuilder class arriving as method parameters passed from callers of the method:

public static MvcPanel BeginPanel(this HtmlHelper helper,
								  string title,
								  string titleCssClass,
								  string panelCssClass,
								  IDictionary<string, object> titleHtmlAttributes,
								  IDictionary<string, object> panelHtmlAttributes)
{
	// title panel
	TagBuilder titleTagBuilder = new TagBuilder("div");
	titleTagBuilder.MergeAttributes(titleHtmlAttributes);
	titleTagBuilder.AddCssClass(titleCssClass);
	titleTagBuilder.SetInnerText(title);

	// content panel
	TagBuilder tagBuilder = new TagBuilder("div");
	tagBuilder.MergeAttributes(panelHtmlAttributes);
	tagBuilder.AddCssClass(panelCssClass);

	HttpResponseBase httpResponse = helper.ViewContext.HttpContext.Response;
	httpResponse.Write(titleTagBuilder.ToString(TagRenderMode.Normal));
	httpResponse.Write(tagBuilder.ToString(TagRenderMode.StartTag));
	return new MvcPanel(httpResponse);
}

The arguments represent:

• the title displaied in the title panel
• the css class rule to apply to the title panel
• the css class rule to apply to the content panel
• a dictionary containing additional html attributes for the title div
• a dictionary containing additional html attributes for the content div

For each method accepting one or more IDictionary as parameters, an overload is provided accepting an instance of type object.

This is just a convenience to facilitate invoking the desired overload taking advantage of anonymous types.

In fact we gain the ability to pass the list of html attributes as an anonymous type like the following:

new { title = "panel's tooltip" } 

In the last paragraph you can find the full Code for PanelExtensions and MvcPanel.

As you can see in the code, the first and simplest extension method accepts only a parameter: the title to be displaied in the title panel.

All the overloads not explicitly accepting css class rules as parameters, rely on the view using them to define a couple of default css class rules (whose names you can find in constants inside the PanelExtensions class).

The default css class rules names are:

• panelTitle
• panel

An example of usage is:

<% using (Html.BeginPanel("About")) 
{ %>
    <span>Put content here.</span>
<% } %>

You must remember to import your namespace in the view that will use your extension methods:

<%@ Import Namespace="MvcPanelExample.Models.Html" %>

Alternatively you can import the namespace for the whole web application adding it to the web.config:

<pages>
      <namespaces>
        <add namespace="MvcPanelExample.Models.Html"/>
      </namespaces>
</pages>

At the paragraph 3.3. TestView you can find the code for a view rendering three panels obtained by invoking three different overloaded extension methods contained in the PanelExtensions class.

The view contains also the definition of two css class rules with the default names plus a pair of custom named css class rules:

• customPanelTitle
• customPanel

here is the result displaied by the browser:

→ top of paragraph

→ top of post

2.2. Strongly Typed Extension Methods

Eventually I added the strongly typed version of my extension methods.

I didn’t find much help on how to do it on the web, apart from this topic:

Is it possible to create a custom ASP.NET MVC strongly typed HTML Helper?.

Then I downloaded the ASP.NET MVC 3 beta version source code and had a look at how the strongly typed methods: TextBoxFor and LabelFor were implemented.

I had a look at the ModelMetadata class as well.

Starting from there I wrote my own strongly typed html helper method.

The content of the simplest overload is the following (as you can see at paragraph 3.1. PanelExtensions):

ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
return BeginPanel(html, metadata.Model as string);

The Asp.Net Mvc framework ModelMetaData class provides the utility method: FromLambdaExpression that parses the lambda expression passed as argument and returns an instance of ModelMetadata containing information about the model property returned by the lambda expression.

The Model property of ModelMetaData contains the value contained in such property, cast as object.

As we can see, the strongly typed overload delegates the actual rendering to the non strongly typed overload: BeginPanel.

We can than feel safe about XSS attacks because the values contained in the model are sanitized.
In fact the model property will be output in the html via the TagBuilder’s method: SetInnerText() and such method encodes the argument passed.

From my views I can then call any of the strongly typed versions of the Panel extension methods:

<% using (Html.BeginPanelFor(m => m.Title, "bluePanel"))
{ %>
	<div>
		Content of my strongly typed panel.
	</div>
<% } %>

At the paragraph 3.4. StronglyTypedView you can find the code for a view rendering two panels obtained by invoking two different strongly typed extension methods contained in the PanelExtensions class.

here is the result displaied by the browser:

Obviously both the views in this article are accessible as long as I have the appropriate Controller action methods returning them as result.

For the strongly typed view I expect to have an action method like the following:

public ActionResult StronglyTypedView()
{
	PanelModel model = new PanelModel();
	model.Title = "Fake Title";
	model.SomeOtherText = "SomeOtherText Property Content";
	return View(model);
}

you can find the full code for the controller at the paragraph 3.6. Controller.

→ top of paragraph

→ top of post

3. Full Code

• 3.1. PanelExtensions
• 3.2. MvcPanel
• 3.3. TestView
• 3.4. StronglyTypedView
• 3.5. ViewModel
• 3.6. Controller

You can download the full source code here or copy the code in the following paragraphs.

3.1. PanelExtensions

namespace MvcPanelExample.Models.Html
{
    using System.Web;
    using System.Web.Mvc;
    using System.Collections.Generic;
    using System.Web.Routing;
    using System.Diagnostics.CodeAnalysis;
    using System.Linq.Expressions;
    using System;


    public static class PanelExtensions
    {
        #region Constants

        const string TitleCssClass = "panelTitle";
        const string PanelCssClass = "panel";

        #endregion

        #region Methods

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title)
        {
            return BeginPanel(helper, title, new RouteValueDictionary(), new RouteValueDictionary());
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          object htmlAttributes)
        {

            return BeginPanel(helper, title, new RouteValueDictionary(), new RouteValueDictionary(htmlAttributes));
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          IDictionary<string, object> htmlAttributes)
        {

            return BeginPanel(helper, title, new RouteValueDictionary(), htmlAttributes);
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          object titleHtmlAttributes,
                                          object htmlAttributes)
        {

            return BeginPanel(helper, title, TitleCssClass, PanelCssClass, new RouteValueDictionary(titleHtmlAttributes), new RouteValueDictionary(htmlAttributes));
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          IDictionary<string, object> titleHtmlAttributes,
                                          IDictionary<string, object> htmlAttributes)
        {

            return BeginPanel(helper, title, TitleCssClass, PanelCssClass, titleHtmlAttributes, htmlAttributes);
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          string panelCssClass)
        {

            return BeginPanel(helper, title, TitleCssClass, panelCssClass);
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          string titleCssClass,
                                          string panelCssClass)
        {

            return BeginPanel(helper, title, titleCssClass, panelCssClass, new RouteValueDictionary(), new RouteValueDictionary());
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          string titleCssClass,
                                          string panelCssClass,
                                          object titleHtmlAttributes,
                                          object panelHtmlAttributes)
        {
            return BeginPanel(helper, title, titleCssClass, panelCssClass, new RouteValueDictionary(titleHtmlAttributes), new RouteValueDictionary(panelHtmlAttributes));
        }

        public static MvcPanel BeginPanel(this HtmlHelper helper,
                                          string title,
                                          string titleCssClass,
                                          string panelCssClass,
                                          IDictionary<string, object> titleHtmlAttributes,
                                          IDictionary<string, object> panelHtmlAttributes)
        {
            // title panel
            TagBuilder titleTagBuilder = new TagBuilder("div");
            titleTagBuilder.MergeAttributes(titleHtmlAttributes);
            titleTagBuilder.AddCssClass(titleCssClass);
            titleTagBuilder.SetInnerText(title);

            // content panel
            TagBuilder tagBuilder = new TagBuilder("div");
            tagBuilder.MergeAttributes(panelHtmlAttributes);
            tagBuilder.AddCssClass(panelCssClass);

            HttpResponseBase httpResponse = helper.ViewContext.HttpContext.Response;
            httpResponse.Write(titleTagBuilder.ToString(TagRenderMode.Normal));
            httpResponse.Write(tagBuilder.ToString(TagRenderMode.StartTag));
            return new MvcPanel(httpResponse);
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html, Expression<Func<TModel, TValue>> expression)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string);
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             object htmlAttributes)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, new RouteValueDictionary(), new RouteValueDictionary(htmlAttributes));
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             IDictionary<string, object> htmlAttributes)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, new RouteValueDictionary(), htmlAttributes);
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             object titleHtmlAttributes,
                                                             object htmlAttributes)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, TitleCssClass, PanelCssClass, new RouteValueDictionary(titleHtmlAttributes), new RouteValueDictionary(htmlAttributes));
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             IDictionary<string, object> titleHtmlAttributes,
                                                             IDictionary<string, object> htmlAttributes)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, TitleCssClass, PanelCssClass, titleHtmlAttributes, htmlAttributes);
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             string panelCssClass)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, TitleCssClass, panelCssClass);
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             string titleCssClass,
                                                             string panelCssClass)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, titleCssClass, panelCssClass, new RouteValueDictionary(), new RouteValueDictionary());
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             string titleCssClass,
                                                             string panelCssClass,
                                                             object titleHtmlAttributes,
                                                             object panelHtmlAttributes)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, titleCssClass, panelCssClass, new RouteValueDictionary(titleHtmlAttributes), new RouteValueDictionary(panelHtmlAttributes));
        }

        [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures", Justification = "This is an appropriate nesting of generic types")]
        public static MvcPanel BeginPanelFor<TModel, TValue>(this HtmlHelper<TModel> html,
                                                             Expression<Func<TModel, TValue>> expression,
                                                             string titleCssClass,
                                                             string panelCssClass,
                                                             IDictionary<string, object> titleHtmlAttributes,
                                                             IDictionary<string, object> panelHtmlAttributes)
        {
            ModelMetadata metadata = ModelMetadata.FromLambdaExpression(expression, html.ViewData);
            return BeginPanel(html, metadata.Model as string, titleCssClass, panelCssClass, titleHtmlAttributes, panelHtmlAttributes);
        }

        public static void EndPanel(this HtmlHelper helper)
        {
            HttpResponseBase httpResponse = helper.ViewContext.HttpContext.Response;
            httpResponse.Write("</div>");
        }

        #endregion
    }
}

→ top of paragraph
→ top of post

3.2. MvcPanel

namespace MvcPanelExample.Models.Html
{
    using System;
    using System.Diagnostics.CodeAnalysis;
    using System.Web;

    public class MvcPanel : IDisposable
    {
        #region Fields

        private bool disposed;
        private readonly HttpResponseBase httpResponse;

        #endregion

        #region CTOR

        public MvcPanel(HttpResponseBase httpResponse)
        {
            if (httpResponse == null)
            {
                throw new ArgumentNullException("httpResponse");
            }
            this.httpResponse = httpResponse;
        }

        #endregion

        #region Methods

        [SuppressMessage("Microsoft.Security", "CA2123:OverrideLinkDemandsShouldBeIdenticalToBase")]
        public void Dispose()
        {
            Dispose(true /* disposing */);
            GC.SuppressFinalize(this);
        }

        protected virtual void Dispose(bool disposing)
        {
            if (!this.disposed)
            {
                this.disposed = true;
                this.httpResponse.Write("</div>");
            }
        }

        public void EndPanel()
        {
            Dispose(true);
        }

        #endregion
    }
}

→ top of paragraph
→ top of post

3.3. TestView

<%@ Page Language="C#" Inherits="System.Web.Mvc.ViewPage" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Example View</title>
    <style type="text/css">
    /* Top bar containing the title of the panel */
    .panelTitle
    {
	    height:30px;
	    background-color:#333366;
	    color:white;
	    border-top:solid 1px #666699;
	    border-right:solid 1px #666699;
	    border-left:solid 1px #666699;
	    padding:5px 0px 0px 20px;
	    font-weight:bold;
	    font-size:large;
	    overflow:auto;
    }

    /* Section of the screen containing omogeneous information */
    .panel
    {
	    border:solid 1px #666699;
	    background-color:white;
	    padding:10px;
	    overflow:auto;
    }
    
    .customPanelTitle
    {
	    height:30px;
	    background-color:#333366;
	    color:white;
	    border-top:solid 1px #666699;
	    border-right:solid 1px #666699;
	    border-left:solid 1px #666699;
	    padding:5px 0px 0px 20px;
	    font-weight:bold;
	    font-size:large;
	    overflow:auto;
	    width:300px;
    }
    
    .customPanel
    {
	    border:solid 1px #666699;
	    background-color:Blue;
	    color:White;
	    border:solid 1px Blue;
	    padding:10px;
	    overflow:auto;
	    width:300px;
    }
    </style>
</head>
<body>
<div>
    <% using (Html.BeginPanel("This is my first Panel"))
       { %>
        <div>
            Content of my first panel.
        </div>
    <% } %>
    <p>
    </p>
    <% using (Html.BeginPanel("Panel with non default style class",
                              "customPanelTitle",
                              "customPanel"))
       { %>
        <div>
            Content of my second panel.
        </div>
    <% } %>
    <p>
    </p>
    <% using (Html.BeginPanel("Panel obtained with all parameters",
                              "customPanelTitle",
                              "customPanel",
                              new { title = "panel's tooltip" },
                              null))
       { %>
        <div>
            Content of my panel obtained specifying all parameters.
        </div>
    <% } %>
</div>
</body>
</html>

→ top of paragraph
→ top of post

3.4. StronglyTypedView

<%@ Page Language="C#" Inherits="System.Web.Mvc.ViewPage<MvcPanelExample.Models.PanelModel>" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>StronglyTypedView</title>
     <style type="text/css">
    /* Top bar containing the title of the panel */
    .panelTitle
    {
	    height:30px;
	    background-color:#333366;
	    color:white;
	    border-top:solid 1px #666699;
	    border-right:solid 1px #666699;
	    border-left:solid 1px #666699;
	    padding:5px 0px 0px 20px;
	    font-weight:bold;
	    font-size:large;
	    overflow:auto;
	    width:300px;
    }

    /* Section of the screen containing omogeneous information */
    .panel
    {
	    border:solid 1px #666699;
	    background-color:white;
	    padding:10px;
	    overflow:auto;
	    width:300px;
    }
    
    .bluePanel
    {
	    border:solid 1px #666699;
	    background-color:Blue;
	    color:White;
	    border:solid 1px Blue;
	    padding:10px;
	    overflow:auto;
	    width:300px;
    }
    </style>
</head>
<body>
    <% using (Html.BeginPanelFor(m => m.Title))
    { %>
        <div>
            Content of my first panel.
        </div>
    <% } %>
    <p></p>
    <% using (Html.BeginPanelFor(m => m.SomeOtherText, "bluePanel"))
    { %>
        <div>
            Content of my second panel.
        </div>
    <% } %>
</body>
</html>

→ top of paragraph
→ top of post

3.5. ViewModel

This is the view model used by the view in the previous paragraph:

namespace MvcPanelExample.Models
{
    public class PanelModel
    {
        public string Title { get; set; }

        public string SomeOtherText { get; set; }
    }
}

→ top of paragraph
→ top of post

3.6. Controller

namespace MvcPanelExample.Controllers
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Web;
    using System.Web.Mvc;
    using MvcPanelExample.Models;

    [HandleError]
    public class HomeController : Controller
    {
        public ActionResult TestView()
        {
            return View();
        }

        public ActionResult StronglyTypedView()
        {
            PanelModel model = new PanelModel();
            model.Title = "Title From the Model";
            model.SomeOtherText = "Some other text from the model";
            return View(model);
        }
    }
}

→ top of paragraph
→ top of post

This article is the second one of a series dedicated to CruiseControl.Net.
In the first part (which you can find here) we installed it and had an overview of how to configure it.
Then we started to configure a project file: we instructed the Source Control Block to use Subversion, the Trigger Block to check it periodically and the Labeller Block to use: svnRevisionLabeller
In this second article we will see the Tasks Block and I will point out some issues that might arise and provide solutions as well.

Thanks to Frank Geerlings for making me aware of a casing problem with the xml samples.
By talking with WordPress support it came out that there was a little bug and they suggested me
how to fix the problem.

9. Tasks Block

The tasks block represents how the build of the project actually takes place.
In our example we will use an MsBuild Task to accomplish the main purpose of our project, which is to compile the versioned Visual Studio solution.
After that we will use an Executable Task to run our unit tests, if the build succeeds.
Let’s see the whole Tasks Block, at first:

<tasks>
<!-- compiles working copy -- >
  <msbuild>
    <executable>C:\WINDOWS\Microsoft.NET\Framework\
      v2.0.50727\MSBuild.exe
    </executable>
    <workingDirectory>C:\develop\CCnet\project1WorkingDir
    </workingDirectory>
<projectFile>DummySolution.sln</projectFile >
    <buildArgs>/noconsolelogger /v:quiet
      /p:Configuration=Debug
      /p:ReferencePath="C:\Program Files\NUnit 2.4.7\bin"
    </buildArgs>
    <targets>ReBuild</targets >
    <timeout>600</timeout >
    <logger>c:\Program Files\CruiseControl.NET\server\
      Rodemeyer.MsBuildToCCNet.dll</logger >
  </msbuild>
<!-- launches nunit tests on working copy -- >
  <exec>
    <executable>C:\Program Files\NUnit 2.4.7\
      bin\nunit-console.exe
    </executable >
    <buildArgs>/xml:..\project1CCnetArtifacts\nunit-results.xml
      /nologo Dummy.sln.nunit
      /exclude:LongRunning,AnotherCategoryName
    </buildArgs>
  </exec>
</tasks>

Let’s focus on the MsBuild Task first and see how we can configure and customize it:

→ top of post
→ top of paragraph

10. MsBuild Task

Let’s have a look at the meaning of the xml nodes children of the <msbuild> node:

<executable>: contains the path to the msbuild executable file. You don’t really need to set it because the default value is the standard installation path: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\MSBuild.exe.
I decided to set it explicitly just to be sure about it .
<workingDirectory>: is the directory in which MsBuild will be run, so it must be the directory containing our project’s checked out working copy. You can provide a path relative to the current project’s workinDirectory but I preferred to provide the full path. Actually, the path to the CCNET checked out working copy is the same as the <workingDirectory> field of the Source Control Block.
<projectFile>: is the name of the project to build. MsBuild accepts a Visual Studio solution file as the project file to build. Obviously the MsBuild Task accepts it as well.
<buildArgs> This row provides additional command line arguments to MsBuild. We tell it not to log events to the console (/noconsolelogger), to build the Debug configuration (/p:Configuration=Debug) and to provide a reduced output (/v:quiet).
As far as the /p:ReferencePath buildArg is concerned it is worth to talk extensively about a problem that could arise with Nunit, so have a look at paragraph 10.1.

10.1 MSBuild and ReferencePath – CruiseControl.NET not resolving reference to Nunit

It could happen that CCNET is not able to locate Nunit (or some other dependency assembly) depending on how your project file has been created by Visual Studio.
Open your project file (DummyProject.csproj) with a text editor (e.g.: Notepad++). If you find an entry as follows in it:

<Itemgroup>
  <Reference Include="nunit.framework, Version=2.4.7.0,
    Culture=neutral, PublicKeyToken=96d09a1eb7f44a77,
    processorArchitecture=MSIL" />
      ....
</Itemgroup>

with no <HintPath> associated to the Nunit <Reference> it could be that CCNET will not be able to resolve that reference if you don’t register nunit.framework.dll in the server’s GAC.

You can make sure that CCNET is able to resolve the dependency by providing an alternative search path in which to look for.
Each assembly referenced in the Visual Studio project file needs to be located by MSBUild at compile time.
The location of the referenced assemblies is resolved by MSBuild by looking in several locations in a particular search order (as explained here).
We could modify the .csproj file by providing a value as a child node of the node, e.g.:

<Reference Include="DummyLibrary, Version=1.0.0.0,
    Culture=neutral, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>..\..\CommonReferencedDLLs\DummyLibrary.dll
  </HintPath>
</Reference>

This approach has two drawbacks:

1. the hintpath is a relative path, thus making the build success depend on the location of the project relative to the referenced assembly (this could be a problem if we reference an external assembly);
2. we need to modify each Visual Studio project file by hand and we don’t want to do it!

Fortunately there’s an easy way out:
We can override all the project specific settings for path resolving by passing a ReferencePath property from the MSBuild command line.
Such property accepts as value a list of paths (MSBuild DummySolution.sln /p:”ReferencePath=<Path1;Path2;Path3>”) and it is checked by the build process before checking other locations (HintPath for example).
So the way to provide an alternative search path from the command line is to pass as argument a ReferencePath property.
This is the reason why the command line provided in the <buildArgs> field contains the ReferencePath property pointing to the Nunit install path:
/p:ReferencePath=”C:\Program Files\NUnit 2.4.7\bin”.

→ top of post
→ top of paragraph

end of paragraph 10.1
continues paragraph 10. MsBuild Task

Let’s go on with the analysis of the xml nodes children of the <msbuild> node:
<targets> specifies which targets to build in this msbuild project file. It represents the MSbuild’s /target command line argument. We set it to Rebuild (clean and build).
<timeout> is the number of seconds before assuming that the process has hung. If timeout is exceeded the process will be killed.
<logger> specifies the path to the assembly containing the logger to use to format the log output of MSbuild .
If you don’t want to use the alternative logger that I used in the configuration shown above, you can rely on the default logger as explained here and skip the following
paragraph 10.2.
To use the default logger:

• leave out the <logger> field,
• download the assembly containing the default xml logger here (find info here),
• copy the downloaded assembly (ThoughtWorks.CruiseControl.MSBuild.dll) to the folder: C:\%ProgramFiles%\CruiseControl.NET\server.

I suggest to use the alternative logger (by Christian Rodemeyer) as explained in the following paragraph. The RodeMeyer’s logger provide lighter msbuild output and his modified stylesheets provide much more readable display of such information.

10.2. An Alternative MSBuild Logger – Christian Rodemeyer’s MsBuildToCCNet

I chose to use a logger alternative to the default one: Christian Rodemeyer’s MsBuildToCCNet.
You can find it at: Improved MSBuild Integration. From there either you can download separately the assembly and all related stuff needed to correctly display the results from Rodemeyer’s logger or you can download a zip file with the whole project and source code.

In the page cited above you can find detailed instructions on how the logger works and how it should be configured.
In the current paragraph I’ll illustrate the installation process and add some useful tips for making it work.
I suggest to download the full project that comes in a zip file named: MsBuildToCCNet.zip (download here).
Unzipping the package you will have a directory named: MsBuildToCCNet. Inside this directory you will find, among the rest, a directory named Release, containing the assembly: Rodemeyer.MsBuildToCCnet.dll.
Just copy the assembly to the \CruiseControl.NET\server folder (e.g.: c:\Program Files\CruiseControl.NET\server\).
There’s another subdirectory of the MsBuildToCCNet folder, named ccnet where you can find the resources needed to correctly display the logs produced by Rodemeyer’s logger. Those resources are:
cruisecontrol.css and
msbuild2ccnet.xsl.

You need to use those two files and to configure the Webdshboard:

1. Move into your CruiseControl.NET Webdashboard folder, under the path: C:\%ProgramFiles%\CruiseControl.NET\webdashboard (e.g.: c:\Program Files\CruiseControl.NET\webdashboard\) and back up the file: cruisecontrol.css.
   Then replace it with the cruisecontrol.css file you found in the Rodemeyer’s MsBuildToCCNet folder (e.g.: copy MsBuildToCCNet\ccnet\cruisecontrol.css to c:\Program Files\CruiseControl.NET\webdashboard\cruisecontrol.css);
2. There’s a subdirectory of the CruiseControl.NET Webdashboard folder, named: xsl.
   You need to copy the other resource (msbuild2ccnet.xsl) you found in the MsBuildToCCNet\ccnet folder in that directory: C:\%ProgramFiles%\CruiseControl.NET\webdashboard\xsl\;
3. You need to modify the dashboard.config file in the CruiseControl.NET Webdashboard folder in order to correctly show the output of the logger.
   Being that we’re talking about the Webdashboard configuration I will show you all the changes you will need to do to let it work with the following three components (even if we’ll see two of them only in the following paragraphs):
   • MsBuildToCCNet
   • Nunit integration
   • FxCop integration

   First of all choose a 32 x 32 jpg image representing a smiling icon and place it in the CruiseControl.NET Webdashboard folder: C:\%ProgramFiles%\CruiseControl.NET\webdashboard.
   Rename the image file: your_happy_image.jpg and, when a new build succeeds, you’ll obtain a smiling icon in the Webdashboard report! (you can find a sample image here).
   Then open CruiseControl.NET\webdashboard\xsl\msbuild2ccnet.xsl and go to line 24:

   <xsl :if test="@error_count = 0 and @warning_count = 0">
   <tr>
   <td><img src="/ccnet/your_happy_image.jpg"
              alt="Happy Image :-)" /> Juchuu !!!</td>
   </tr>
   </xsl>
   

   replace the img src attribute: /ccnet/your_happy_image.jpg with /your_happy_image.jpg if you configured iis with a new website for the webdashboard instead of a virtual directory. If you’re usign the default virtual directory named ccnet, don’t modify that row.
   Next you need to locate the field: <buildPlugins> in C:\%ProgramFiles%\CruiseControl.NET\webdashboard\dashboard.config and arrange or delete its children nodes in order to obtain the following configuration (remember to back up the file first):

   <buildplugins>
     <buildreportbuildplugin>
       <xslfilenames>
         <xslfile>xsl\header.xsl</xslfile>
         <xslfile>xsl\modifications.xsl</xslfile>
         <xslfile>xsl\msbuild2ccnet.xsl</xslfile>
         <xslfile>xsl\unittests.xsl</xslfile>
         <xslfile>xsl\compile.xsl</xslfile>
         <xslfile>xsl\fxcop-summary.xsl</xslfile>
       </xslfilenames>
     </buildreportbuildplugin>
     <buildlogbuildplugin />
     <xslreportbuildplugin description="NUnit Details"
          actionName="NUnitDetailsBuildReport"
          xslFileName="xsl\tests.xsl" />
     <xslreportbuildplugin description="NUnit Timings"
          actionName="NUnitTimingsBuildReport"
          xslFileName="xsl\timing.xsl" />
      <xslreportbuildplugin description="FxCop Report"
          actionName="FxCopBuildReport"
          xslFileName="xsl\FxCopReport.xsl" />
   </buildplugins>
   

   As you can see, such configuration includes also stylesheet files for nunit and fxcop integration. We will soon configure the server to integrate those components.

→ top of post
→ top of paragraph

end of paragraph 10.2
continues paragraph 10. MsBuild Task

While adding the smiling image in the previous paragraph we had to change the path in the xsl file.
The same problem could arise with other stylesheet files if you configured the webdashboard to be a website instead that a virtual directory named ccnet.
Have a look at the next paragraph for details:

10.3. CruiseControl.NET Webdashboard Fails in Finding Images if Not Installed in Virtual Directory

If you unchecked ‘Create virtual directory in IIS for Web dashboard’ as shown in part 1 of this tutorial at 3.1. Install CruiseControl.NET and installed the Webdashboard as a new website as shown in the paragraph: 3.2. Create a CCNet Website in IIS, the webdashboard could have problems in resolving image paths.
You will realize it as soon as you will configure the server to integrate nunit or fxcop (will see it in following paragraphs).
To make sure not to have this problems you must modify the following files:
xsl\tests.xsl
xsl\fxcop-summary.xsl
under: C:\%ProgramFiles%\CruiseControl.NET\webdashboard\

you have to replace all the paths relative to the root of the website with relative paths, e.g:

in the file: xsl\tests.xsl you should replace all entries like:

eImg.src = "<xsl :value-of select="$applicationPath"/>/images/arrow_minus_small.gif";

with:

eImg.src = "<xsl :value-of select="$applicationPath"/>images/arrow_minus_small.gif";

and entries like:

<img src="{$applicationPath}/images/fxcop-error.gif"/>

with:

<img src="{$applicationPath}images/fxcop-error.gif"/>

that is, you simply need to delete the leading ‘forward slash’ at the beginning of the path (just before the ‘images’ folder name).

you need to accomplish the same task with the file xsl\fxcop-summary.xsl, e.g.:

you should replace entries like:

<xsl :attribute name="src"><xsl :value-of select="$applicationPath" />/images/fxcop-critical-error.gif</xsl>

with:

<xsl :attribute name="src"><xsl :value-of select="$applicationPath" />images/fxcop-critical-error.gif</xsl>

Actually, you should find all paths to images in those two files and delete the leading forward slash.

→ top of post
→ top of paragraph

end of paragraph 10.3
continues paragraph 10. MsBuild Task

Back to the MSBuildToCCNET alternative Logger for MsBuild, I will explain now why I decided to recompile the source code instead of using the assembly provided: MsBuildToCCNet\Release\Rodemeyer.MsBuildToCCnet.dll

10.4. MSBuildToCCNET Reports Wrong Number of Compiled Projects

I found that MsBuildToCCNet reported the wrong number of projects in the webdashboard in the page reporting the details of the last build.
There’s a row that sounds like the following, displaied in that page:

’15 Projects built with 2 warnings’

Looking at the source code (in the file: Logger.cs) I realized that the list of Project type instances includes the solution file (DummySolution.sln) and a Project object named “MSBuild“, somehow representing the MsBuild process.
Appearently this is the reason why the reported number of projects is wrong.
I still haven’t tried to contact the author so I don’t know very well how the Logger is supposed to work as far as this count is concerned.
As a workaround I modified the following row:

w.WriteAttributeString("project_count",
                     XmlConvert.ToString(projects.Count));

turning it into:

w.WriteAttributeString("project_count",
                     XmlConvert.ToString(projects.Count - 2));

in the ‘WriteLog(XmlWriter w)’ method (file: Logger.cs at row 104).

This seems having fixed the problem with no side effects.

→ top of post
→ top of paragraph

end of paragraph 10.4
continues paragraph 10. MsBuild Task

You could have problems running msbuild task if your server machine (the one in which you installed CruiseControl.NET) is not updated with all the software installed in a developer workstation. Let’s see which problems could arise:

10.5. CruiseControl.NET, MsBuild Task and Resources – Assembly Linker

If you want to provide localization for any of your projects or somehow use resources files (.resx) you will get an error during the build on the CruiseControl.NET server if MsBuild is not able to locate the Assembly Linker.
The error should look something like:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Microsoft.Common.targets(1950,9): error MSB3011: “C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\AL.exe” was not found. Either 1) Install the .NET Framework SDK, which will install AL.exe. Or 2) Pass the correct location of AL.exe into the “ToolPath” parameter of the AL task.

AL.exe is used to produce the satellite assemblies and the executable file is placed in the .NET framework directory.
But Al.exe is a .Net Framework SDK tool. It is not included in .Net Framework 2.0 runtime installation.
You need to install the .NET framework SDK on the server machine if you don’t want to encounter this problem.
If you want to solve this particular issue in a tricky way without installing the whole SDK, you can copy al.exe.config e al.exe from a developer workstation and place them in the C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 directory on the server machine.
This is how I solved the problem but I suggest you to install the .NET framework SDK on the server machine.

→ top of post
→ top of paragraph

10.6. CruiseControl.NET, MsBuild Task and Web Application projects

A particular note is due for Web projects.
Updating Visual Studio 2005 you get the SP1. Together with the Service Pack 1 for Visual Studio you get the WebApplication project template.
Such template lets us add a new kind of project to our solution: a web site project structured exactly like any other Visual Studio project.
So you can quit creating new websites (File –> New –> Web Site…) and start creating new WebApplication projects (File –> New –> Project… and then choose ‘ASP.NET Web Application‘).

In order to use WebApplication projects you need to have Visual Studio installed on your machine and the WebApplication project plugin (that comes with the Visual Studio 2005 SP1).
If the server in which CruiseControl.NET server is running is not a develpment workstation you will get an error when trying to build a WebApplication project, beacuse you miss those two prerequisites.

You can easily fix this problem: you simply need to copy the file: Microsoft.WebApplication.targets that you can find under:
“C:\Program Files\MSBuild\Microsoft\VisualStudio\v8.0\WebApplications\”
from a development workstation and paste it to the corresponding path on the server machine (creating the directories in the path if needed).

Additionally, if you’re using an ASP.NET AJAX Enabled WebApplication as the web project template you need to install the aspnet-ajax extensions as well.
You can find the installer (ASPAJAXExtSetup.msi) for .NET framework 2.0 here

→ top of post
→ top of paragraph

11. Nunit Task

The second Task Block that you find in the xml fragment above is an Executable Task used to instruct CruiseControl.NET to run unit tests with Nunit.

At first I tried to use a Nunit Task Block but I soon realized that it was not good for me because it was not possible to provide arguments to the task that should be used as arguments of the Nunit command-line executable.

This is a problem because there’s no way to let the Nunit task be aware of Nunit categories.
For those who don’t know, Nunit lets you specify a ‘Category‘ attribute in test methods, with the following syntax:

[Test]
[Category("LongRunning")]
public void VeryLongTest()
{ /* ... */ }

This attribute allows you to instruct Nunit to treat all the methods belonging to the same category in the same way.
Usually what we want to do is to exclude a cluster of tests from running.
Typically we exclude tests that take too much to run, using the following syntax with the nunit command-line tool:

nunit-console.exe /exclude:LongRunning,AnotherCategoryName

You can configure excluded categories in nunit GUI as well, by clicking the ‘Categories‘ tab in the top left corner.
A list of available categories will be shown. Just select the categories of interest and click the Add button.
Then check the Exclude these categories checkbox at the bottom of the page and run the nunit project.

It is very useful to be able to exclude some categories of tests from the continuous integration environment, still being able to run them on developer machines.

This is the reason why I recently submitted a patch to CruiseControl.Net adding support for Nunit categories.
It’s not included in the official release yet, because I submitted it too late for this purpose.
However you can find it in the current build which is publicly available at: ccnetlive. The patch is included starting from build: 3591.
So now you have two chances to use categories:

1. If you really want to use the last officially released version, read the paragraph 11.2 about how to use an Executable Task (the method described can be useful also if you want to use any other unsupported Nunit command line argument);
2. Instead if you can download the latest build from ccnetlive you will be able to specify categories inside the Nunit Task block, as explained in paragraph 11.1

11.1. Nunit Task

If you downloaded the most recent build and followed the installation instructions (see: 3. Installation) you can go on reading this paragraph.
If you installed the official release or a build older than 1.4.0.3591, you can still modify your installation with the following instructions:

download the zipped package (here) or source code. Unzip it in a temporary directory and locate the assembly: ThoughtWorks.CruiseControl.Core.dll (which, for the zip package, is in the directory: ‘server’).
Copy and replace it to the original one in your CCNET installation directory (back up the original one first) that should be: Program Files\CruiseControl.NET\server.

That’s it! Now you can use the CruiseControl.NET’s Nunit Task Block also for specifying Nunit categories (see: Nunit categories for reference).

It is possible to specify a list of the categories of tests that we want to be excluded.
It is possible, as well, to specify a list of the only categories that we want to be included as allowed by the Nunit Command-line or GUI interface.
The configuration syntax for the Nunit task becomes:

<nunit>
<path>C:\Program Files\NUnit 2.4.7\bin\nunit-console.exe
</path>
    <assemblies>
        <assembly>Dummy.sln.nunit</assembly>
    </assemblies>
    <excludedCategories>
        <excludedCategory>LongRunning</excludedCategory>
	<excludedCategory>Category 2</excludedCategory>
    </excludedCategories>
</nunit>

for excluded categories, or:

<nunit>
<path>C:\Program Files\NUnit 2.4.7\bin\nunit-console.exe
</path>
    <assemblies>
        <assembly>Dummy.sln.nunit</assembly>
    </assemblies>
    <includedCategories>
        <includedCategory>LongRunning</includedCategory>
	<includedCategory>Category 2</includedCategory>
    </includedCategories>
</nunit>

for included categories. You can find the official reference at this page on the official website.

The Nunit task output log file is automatically integrated in the CCNET build results.
So you don’t need to specify the Merge task (needed if you use the procedure explaine in paragraph 11.2 instead of this one) in the Publishers block as explained in paragraph 12:

<merge>
  <files>
    <file>..\project1CCnetArtifacts\nunit-results.xml</file>
  </files>
</merge>

Instead you still need to delete the previous Nunit log file before each build process as explained in the paragraph 13 – PreBuild Block.

→ top of post
→ top of paragraph

11.2. Executable Task

If you’re working with the official release of CruiseControl.Net (release 1.4) Nunit Task Block syntax only allows you to specify the target solution and little more. In our example it would be:

<nunit>
<path>C:\Program Files\NUnit 2.4.7\bin\nunit-console.exe
</path>
	<assemblies>
		<assembly>Dummy.sln.nunit</assembly>
	</assemblies>
</nunit>

where Dummy.sln.nunit is the Nunit project file for our solution.

The solution I strongly suggest is to replace the Nunit Task with an Executable Task like the one shown below:

<exec>
  <executable>
    C:\Program Files\NUnit 2.4.7\bin\nunit-console.exe
  </executable>
  <buildArgs>/xml:..\project1CCnetArtifacts\nunit-results.xml
    /nologo Dummy.sln.nunit
    /exclude:LongRunning,AnotherCategoryName
  </buildArgs>
</exec>

You only need to specify the full path to the Nunit command-line executable file in the <executable> field and the command-line arguments in the <buildArgs> field.

In the <buildArgs> field you specify arguments as if provided directly to nunit-console.exe:

1. specify the path to the file in which nunit will write its output: /xml:..\project1CCnetArtifacts\nunit-results.xml.
   The file should be produced in the artifactDirectory of the current CCNET project.
   By default the executable run by an executable task is run in the Project Working Directory, so the path to the output file is relative to such directory.
2. You can pass many things as Nunit targets (assemblies, Visual Studio projects or Nunit project files). I suggest to create an Nunit project and pass it as argument to nunit-console.exe as shown in the sample above (where the nunit project file is called: Dummy.sln.nunit).
3. you can then add: /exclude:LongRunning,AnotherCategoryName thus excluding unwanted tests.

Specifying the name of the output file is not enough.
In order to make the output written by nunit in the file nunit-results.xml (arbitrary name specified in the buildArgs tag), available to CruiseControl.NET we need to use a File Merge Task.
If we used Nunit task the output file would have been automatically merged with other output for CruiseControl.NET.
Using the Executable Task we need to explicitly configure CruiseControl.NET to merge the Nunit output file in the log file parsed by CruiseControl.NET.
We will tell CruiseControl.NET to do it at the end of the build process, namely in the Publishers section.

→ top of post
→ top of paragraph

12. Publishers Block

We will add a File Merge Task at the beginning of the Publishers section. You can see below the publishers section as it is defined in our project configuration file:

<publishers>
  <merge>
    <files>
      <file>..\project1CCnetArtifacts\nunit-results.xml
      </file>
    </files>
  </merge>
  <xmllogger />
  <statistics />
  <modificationHistory onlyLogWhenChangesFound="true" />
  <artifactcleanup cleanUpMethod="KeepLastXBuilds"
    cleanUpValue="20" />
      ...
</publishers>

The File Merge Task specifies the paths to the files that we want to be merged by the Xml Log Publisher Task with the rest of its own output (you don’t need to specify nunit output file if you used the Nunit Task as in paragraph 11.1. Nunit Task).
All of this output is placed by default in the buildlogs directory under the Project’s Artifact Directory.
So the File Merge Task should appear before the Xml Log Publisher Task in the publishers section.
The Xml Log Publisher Task (‘xmllogger‘) is needed for making the web dashboard work correctly.
The ‘statistics‘ field collects and updates statistics for each build. You can see them clicking: View Statistics on the left side of the Web Dashboard.
The ‘modificationHistory‘ field logs all the modifications for each build. With onlyLogWhenChangesFound you can choose to log info only for builds happened when changes take place (not for forced builds). You can see the modification history by clicking: View Modification History on the left side of the Web Dashboard.

I then added an ‘artifactcleanup‘ field in order to keep memory of the last 20 builds only.
This task allows us to choose between two clean up modes of the past build logs:
- deleting logs older than a specified number of days
- keeping only a specified number of logs: the more recent ones (cleanUpMethod=”KeepLastXBuilds”)

In the sample above we typed the second choice specifying 20 as cleanUpValue thus telling CruiseControl.NET to keep the log files for the last 20 builds only.

→ top of post
→ top of paragraph

13. PreBuild Block

There’s another issue to solve when integrating Nunit using either an Exec Task or the Nunit Task: the Nunit log file is not deleted after the build succeeds or fails.
So upon the next build we’ll still have the old Nunit log file until the Task running Nunit is executed.
To understand what I’m going to explain now, keep in mind that if a task in the Tasks Block fails all the subsequent tasks in the block will be skipped while the tasks in the Publishers Block will be executed.

If, during the next build, the MSBuild Task fails, the Exec Task (Nunit Task) launching Nunit isn’t executed at all so the File Merge Task will merge the previous Nunit log file with the current Xml Log Publisher output, thus leading to an incorrect report: still displaying the Nunit results relative to the previous build.
We would obtain the current MSBuild report but the old Nunit report.
This behavior can lead to misunderstanding of the results so it is a good practice to delete the old Nunit log file before every new build takes place.

The place to accomplish this task is the PreBuild Block.
I used a Nant build file to drive the steps needed to obtain the desired result (simply delete a file if it exists).

13.1. Install Nant

You need to install the Nant Build tool on the server machine.
Just download the zip package: nant-0.85-bin.zip from here and unzip it into the folder: C:\Program Files\Nant.

13.2. Nant Fundamentals

Nant is a build tool driven by xml configuration files (Nant build files).
When you call nant.exe from the command line and you don’t specify a build file (you can specify one passing as argument: -buildfile:pathToDir\FileName.build) NAnt looks for a file ending with .build (e.g.: NAnt.build) in the current directory. If it finds such file, it uses it as the reference for the tasks to execute.

The file structure is shown in the following sample xml file:

< ?xml version="1.0"?>
<project name="dummy" default="target1" basedir=".">
	<description>dummy project</description>
	<target name="target1" description="target1 description">
	    ... (a list of Nant tasks will be placed here)
	</target>
	<target name="target2" description="target2 description">
		<delete file="pathToFile\FileName"
                failonerror="false" />
		... (a list of other Nant tasks will be placed here)
	</target>
</project>

A build file contains one <project> field with one or more children <target> fields each containing different Nant tasks (e.g.: the <delete> task).
When invoking nant.exe you can specify the name of the target to be executed and Nant will execute all the tasks contained in that target. If you don’t provide a target, the default one will be executed (i.e. the one specified in the ‘default‘ attribute of the <project> field).

end of paragraph 13.2
continues paragraph 13. PreBuild Block

Once you’ve got Nant installed on the server machine you have to create a file named nant.build and place it, for convenience, in the directory in which you placed all the CruiseControl.NET related stuff (in this example: C:\develop\CCnet).

At the moment we need just one target to delete Nunit log files. Later we will add another target.
The actual file content is the following:

< ?xml version="1.0"?>
<project name="Dummy" default="cleanNunit" basedir=".">
  <description>CCNET Tasks</description>
  <target name="cleanNunit"
         description="removes nunit log file">
    <delete file="${CCNetArtifactDirectory}\nunit-results.xml"
          failonerror="false" />
  </target>
</project>

When we tell Nant to execute the ‘cleanNunit‘ target, the delete task will be executed and the nunit-results.xml file will be deleted.
We use one of the environment variables provided by CCNET to retrieve the path to the artifact directory: ${CCNetArtifactDirectory} so this Nant build file will only work when run from CruiseControl.NET.

In the Prebuild Block we will instruct CruiseControl.NET to run a Nant task by adding a CruiseControl.NET Nant Task Block.
Such block lets us instruct CruiseControl.NET to execute Nant and lets us specify a Nant build file and the list of Nant targets to execute.
Remember that we named the build file: nant.build and we placed it in the directory: C:\develop\CCnet.
Now we provide this information to the CruiseControl.NET Nant Task Block as shown in the following example:

<prebuild>
<!-- clean nunit output to avoid CCNET reporting
       about previous build tests if current build fails -->
  <nant>
    <executable>C:\Program Filse\Nant\bin\nant.exe
    </executable>
    <baseDirectory>C:\develop\CCnet</baseDirectory>
    <nologo>false</nologo>
    <buildFile>nant.build</buildFile>
    <targetList>
      <target>cleanNunit</target>
    </targetList>
  </nant>
</prebuild>

the <executable> field specifies the path to the version of nant.exe you want to run,
the <baseDirectory> specifies the directory to run the NAnt process in,
<nologo> passes the -nologo argument to the Nant command line,
<buildFile> specifies the path to the build file to use (relative to the <baseDirectory>),
<targetList> is used to specify a list of targets, each one in a <target> field.

Now we can be sure that each build has the Nunit log file deleted before being executed.

→ top of post
→ top of paragraph

<< CruiseControl.Net Tutorial – Part 1

As soon as possible I will post the third and last part of this tutorial

My AutoComplete Project on CodePlex

1. Introduction
2. Resources
3. Installation
3.1. Install CruiseControl.NET
3.2. Create a CCNet Website in IIS
3.3. Install Nunit
4. CruiseControl.NET Server Configuration – General
5. Structure of a ‘Project’ Configuration File
6. Source Control Block
7. Trigger Block
8. Labeller Block
9. Tasks Block (part 2)
10. MsBuild Task (part 2)
10.1. MSBuild and ReferencePath – CruiseControl.NET not resolving reference to Nunit (part 2)
10.2. An Alternative MSBuild Logger – Christian Rodemeyer’s MsBuildToCCNet (part 2)
10.3. CruiseControl.NET Webdashboard fails in finding images if not installed in virtual directory (part 2)
10.4. MSBuildToCCNET reports wrong number of compiled projects (part 2)
10.5. CruiseControl.NET, MsBuild Task and Resources – Assembly Linker (part 2)
10.6. CruiseControl.NET, MsBuild Task and Web Application projects (part 2)
11. Nunit Task (part 2)
11.1. Nunit Task (part 2)
11.2. Executable Task (part 2)
12. Publishers Block (part 2)
13. PreBuild Block (part 2)
13.1. Install Nant (part 2)
13.2. Nant Fundamentals (part 2)

1. Introduction

In this article series I will review the various steps needed to setup and configure a working CruiseControl.Net server.
The goal is to set up a Continuous Integration process for a sample project as close as possible to a real-life project.
I will point out several issues that might arise and I will provide solutions as well.
I will try to underline all the details that you need to be aware of.

Thanks to Frank Geerlings for making me aware of a casing problem with the xml samples.
By talking with the guys at WordPress support it came out that there was a little bug and they suggested me how to fix the problem.

→ top of post

2. Resources

During the article I will guide you through the installation process of the following software:

Subversion
CruiseControl.NET
Nunit

Nant
FxCop
NantContrib

The following are optional:

TortoiseSVN
AnkhSVN

You can find information about how to install: Subversion, TortoiseSVN and AnkhSVN in the article: Guide to Versioning a Visual Studio Solution with Subversion, TortoiseSVN and AnkhSVN.
There you can also find a quick guide about how to create a Subversion repository and how to add a Visual Studio solution to source control.

This tutorial assumes that you have Subversion 1.4.6 installed and that you have configured a Subversion repository at the url: svn://localhost/trunk as shown in the article: Guide to Versioning a Visual Studio Solution with Subversion, TortoiseSVN and AnkhSVN.

If you already have a working environment with a repository and versioned files, you can go on reading and replace the paths and names in the examples with the paths and names in your environment.

→ top of post
→ top of paragraph

3. Installation

• 3.1. Install CruiseControl.NET
• 3.2. Create a CCNet Website in IIS
• 3.3. Install Nunit

This tutorial will assume that you install CruiseControl.NET on the same machine on which you had installed the Subversion repository. So, first of all, let’s go through the steps needed to install CruiseControl.NET on your server machine.

3.1. Install CruiseControl.NET

Download the latest CruiseControl.NET release from: SourceForge or the latest build from CCNetLive.
You can find release notes here. For this article I used the installer for version 1.4 (CruiseControl.NET-1.4-Setup.exe), downloaded from the CCNetLive website.

Run the setup executable file and, when prompted, you must specify your choices for a couple of actions:
‘Install CC.Net server as windows service’ must be checked so that the setup will install CruiseControl as a Windows service.
In the Services management console the CruiseControl service will be displayed with the name: CruiseControl.NET.
‘Create virtual directory in IIS for Web dashboard’ will create a virtual directory named ccnet in the machine’s IIS web server. If you have an IIS server installation supporting multiple web sites (this is not the case for Windows XP Professional) and prefer to have a separate web site for the CCNet web dashboard you should uncheck this option. This is my choice. In the next paragraph I will show you how to create an IIS web site for the CruiseControl.NET web dashboard.

When the install process is finished all the content will be installed in the folder:
C:\%ProgramFiles%\CruiseControl.NET (e.g. C:\Program Files\CruiseControl.NET).
Under this path you will find a directory called server, containing all the CCNet binary files and executables, and a directory called webdashboard, containing the CruiseControl.NET web interface.

→ top of post
→ top of paragraph

3.2. Create a CCNet Website in IIS

Here I will add and configure a Website in IIS for the CruiseControl.NET Webdashboard: the administrative interface of CruiseControl.NET.
Open IIS Manager in Administrative Tools, right-click on the Web Sites node and select New Web Site.
The Web site creation wizard will start.
Click Next and you will be prompted for a Web Site Description.
Type CCNet and click Next, leave Unassigned the IPAddress, choose a port number (say: 222) and leave empty the ‘Host Header for this site’ field, then click Next.
Choose C:\%ProgramFiles%\CruiseControl.NET\webdashboard as the path for the Website and click Next.
Allow ‘Read’ and ‘Run scripts’, the default, and click Next. The wizard is finished and the new Website created.

→ top of post
→ top of paragraph

3.3. Install Nunit

For the sake of our example we will need Nunit so, if you haven’t already done, install it on the same machine on which you have installed CruiseControl.NET.

You can find the latest Nunit release here at SourceForge.
This article is based on the release 2.4.6, currently the latest. You can install it by downloading: NUnit-2.4.6-net-2.0.msi.

After the installation you will have a new directory under %ProgramFiles% : C:\%ProgramFiles%\NUnit 2.4.6.

→ top of post
→ top of paragraph

4. CruiseControl.NET Server Configuration – General

All the configuration files we’re going to talk about are placed or are to be placed in:
C:\%ProgramFiles%\CruiseControl.NET\server.

CruiseControl.NET comes with two server executables: ccservice.exe which is the windows service installed by the installation setup and ccnet.exe which is a console application included for testing purposes.
It is much easier to debug a console application that a service so I strongly suggest to make your initial tests with ccnet.exe and carefully read the console output to get familiar with CCNet behavior.

Each of the two executables comes with a default configuration file (i.e.: ccservice.exe.config and ccnet.exe.config) that you don’t need to change at the moment.
Moreover both the server processes (windows service or console application) look for a file named ccnet.config in which you will place all the actual information needed by CCNet to learn what it is supposed to do and how it is supposed to do it.

ccnet.config is an xml file with a root element named <cruisecontrol> and a child element, named <project>, for each set of activities that we want CruiseControl.NET to execute, as shown in the following example:

<cruisecontrol>
<project name="project1">
    ...
  </project>
<project name="project2">
    ...
  </project>
</cruisecontrol>

In this tutorial we will setup our CruiseControl.NET configuration with two logical sets of activities.
For the sake of clarity we will benefit of the usage of xml entities.
We’ll define each ‘project’ configuration in a separate file and import all the files in ‘ccnet.config’ by means of entity definitions and entity declarations:

< !DOCTYPE cruisecontrol [
	< !ENTITY project1 SYSTEM "file:project1.xml.config">
	< !ENTITY project2 SYSTEM "file:project2.xml.config">
]>
<cruisecontrol>
  &project1;
  &project2;
</cruisecontrol>

Let’s focus, at first, only on the first project, so delete the second entity reference (i.e.: &project2; ) thus obtaining:

< !DOCTYPE cruisecontrol [
	< !ENTITY project1 SYSTEM "file:project1.xml.config">
	< !ENTITY project2 SYSTEM "file:project2.xml.config">
]>
<cruisecontrol>
  &project1;
</cruisecontrol>

→ top of post
→ top of paragraph

5. Structure of a ‘Project’ Configuration File

What we need to do now is creating a file named: project1.xml.config in C:\%ProgramFiles%\CruiseControl.NET\server
and use it to setup CruiseControl.NET main activities.
This file will contain what is called the ‘Project Configuration Block’ for the first CCNet activity that we want to configure.
First of all we need to assign a unique name to the root of the Project Configuration Block: the <project> tag. We then write:

<project name="1 - testProject">
  <webURL>http://192.168.15.2:222</weburl>
  <workingDirectory>C:\develop\CCnet\project1WorkingDir
  </workingDirectory>
  <artifactDirectory>C:\develop\CCnet\project1CCnetArtifacts
  </artifactDirectory>
  ...
</project>

Let’s talk about the first three children nodes:

represents the URL at which the current project is available through the web interface. We will see later why it is useful.
For now just make sure to set it to the IP of the server machine (in which you installed CCNet) and to the port that you chose for the WebDashboard website when you configured the web site in IIS (see: 3.2. Create a CCNet Website in IIS).

is the path to the main directory of this project and is meant to contain the checked out version of the project under integration.
This path will be accessible as an environment variable: %CCNetWorkingDirectory%, available to external scripts (we will see it later).
I use to place all the projects managed with CCNET in folders under a common directory named: C:\develop\CCnet.
For this test project I chose: C:\develop\CCnet\project1WorkingDir.

It is convenient to choose a directory in which to place all the stuff that will be used by CCNet (script files or executable files that you may want CruiseControl.NET to execute) as well as the workingDirectory in which CCNET will checkout the versioned files and the artifactDirectory in which it will output log files.
In the example above I chose the directory: C:\develop\CCnet as the container of all CCNet related stuff.

is the path to the directory where all the build logs for this project will be placed.

Apart from the three tags described above, the main blocks that we’re going to add to the project configuration file are:

• Source Control Block
• Trigger Block
• Labeller Block
• 9. Tasks Block
• 13. PreBuild Block
• 12. Publishers Block

→ top of post
→ top of paragraph

6. Source Control Block

Source Control configuration block tells CruiseControl.NET that the project named ’1 – testProject’ is bound to a Subversion repository.
This means that the task performed when executing this project depends on the status of that particular Subversion repository.
As soon as CruiseControl.NET detects a new revision in the repository it updates its working copy and executes the tasks related to the current project.
Here is the xml excerpt:

<sourcecontrol type="svn">
<trunkUrl>svn://localhost/trunk</trunkUrl>
  <workingDirectory>C:\develop\CCnet\project1WorkingDir
  </workingDirectory>
  <username>ccnet </username>
<password> ccnet </password>
</sourcecontrol>

contains the url of the repository that we want to check for modifications (e.g., svn://svnserver/pathToRepo).
As we saw in the post Guide to Versioning a Visual Studio Solution with Subversion, TortoiseSVN and AnkhSVN, Subversion could host several repositories under a common folder, say: C:\develop\TestRepo.
But in that article, as well as in the current example, we set up only one repository and run svnserve with the command line: svnserve -d -r “C:\develop\test\repo”.
So, specifying the server name (localhost) and the path to the particular repository we’re interested in, turns out to be simply: svn://localhost/trunk (instead of: svn://localhost/SpecificRepositoryFolder/trunk);
is the directory that will contain the working copy checked out by CCNET;
sets the timeout for the source control operation. It defaults to 10 minutes and you can set it to a different amount of time in milliseconds (default) or specifying units (“millis”, “seconds”, “minutes”, “hours”); I left it out thus accepting the default.
If you want to set it to a different value remember to not choose a too short timeout value because if the timeout is exceeded the build will fail without providing information about the reason.
In that case the only way you can retrieve the actual reason of the build failing is by analyzing CCNET log file in the CruiseControl.NET\server folder (if you set log4net to the debug log level)
and must be set to a valid svn account that CCNET can use to access Subversion repository.

→ top of post
→ top of paragraph

7. Trigger Block

A trigger block is needed to specify when CruiseControl.NET will start a new integration cycle.
We want to check for the repository status continuously so we need an ‘Interval Trigger’ to tell CruiseControl.NET to perform integration periodically after a specified amount of time:

<triggers>
  <intervalTrigger name="Subversion" seconds="10" />
</triggers>

CruiseControl.NET, as far as project ’1 – TestProject’ is concerned, polls the repository every 10 seconds to see if any changes has been committed.
The name attribute is used by CruiseControl.NET GUI to identify the trigger that requested the build;
The seconds attribute is the amount of time before triggering the next integration cycle.

Each time the time interval elapses, CCNET checks for modifications and, by default, runs integration only if changes are detected.

→ top of post
→ top of paragraph

8. Labeller Block

A label is created, at each integration cycle, to identify the specific build occurred.
Different labellers can be used to generate the label that CCNet will use to track the builds.

Other than the Labeller Blocks that come with the CruiseControl.NET distribution, many people provided plugin Labeller Blocks to target the generation of labels with specific formats.

A very good one, IMHO, is SvnRevisionLabeller by David Keaveny (much important to me because I recently contributed to the project).
This plugin allows labelling CruiseControl.NET builds with Subversion’s repository revision numbers and I think this is a really useful feature.
So this example will use SvnRevisionLabeller as the Labeller Block.
For detailed information about this plugin see my post: CruiseControl.NET and Subversion – SvnRevisionLabeller.

To use the SvnRevisionLabeller plugin in your installation of CruiseControl.NET you need to unzip the downloaded package and copy the assembly: ccnet.SvnRevisionLabeller.plugin.dll in the server folder directory under the CruiseControl.NET install path (e.g.: ‘C:\Program Files\CruiseControl.NET\server’).

Next you need to configure the Labeller Block in your project:

<labeller type="svnRevisionLabeller">
	<major>7</major>
	<minor>11</minor>
	<url>svn://localhost/trunk</url>
</labeller>

SvnRevisionLabeller will produce build labels in the format:

major.minor.svnRevision.build

where major and minor are the two values you set in the configuration block while svnRevision is the current version in the Subversion’s repository related to this project.
The build number is automatically incremented each time a new build is forced if no further modification has been committed to the repository.

<url> is the path to the repository used to retrieve the revision number (e.g. svn://svnserver/pathToRepo/trunk). Actually it should be filled with the same path used in the <trunkUrl> field of the Subversion Source Control Block.
In our example it is:

<url>svn://localhost/trunk</url>

Following is a configuration for SvnRevisionLabeller with the complete set of fields:

<labeller type="svnRevisionLabeller">
<prefix>Test-</prefix>
  <major>7</major>
  <minor>11</minor>
  <url>svn://localhost/trunk</url>
  <username>ccnet</username>
<password>ccnet</password>
</labeller>

Such a configuration will produce a label with the following format: Test-major.minor.svnRevision.build.
<username> and <password> are the username and password of a valid Subversion account for the repository specified in the <url> field.

You can use in an external script the build label produced, which is stored in an environment variable.
It can be useful to flag release version of output dlls.
You can access the build number from a script with the syntax: %CCNetLabel% or from a C# application with the following row:

Environment.GetEnvironmentVariable("ccnetlabel");

If you used the SolutionInfo approach in your Visual Studio solution (see my post: SolutionInfo and Partitioned Single Solution) you can use the build label produced by SvnRevisionLabeller to update the AssemblyFileVersion attribute in the SolutionInfo.cs file.
In this way you can provide consistent versioning of the released assemblies together with easy trackability of the corresponding source code’s revision.

Be careful not to use the <prefix> tag in this case because you need to set AssemblyFileVersion to a string in the format:
major.minor.svnRevision.build
with all of the 4 fields being numerical values.

→ top of post
→ top of paragraph

CruiseControl.Net Tutorial – Part 2 >>

A while ago I spent a lot of time for finding information about which character was the line continuation character in a Windows batch script.
The line continuation character allows us to split a line of code in multiple lines while letting the command interpreter know that the current command is not ending upon newline but is going on in the next line.
This is particularly useful if you want to format your scripts to make them more readable.
Here is a list of newline line continuation characters in few scripting languages:

1. Batch (.bat): ^ (caret)
2. Nmake (Makefile): \ (backslash)
3. VBScript (.vbs): _ (underscore)

1. Introduction

In this article I will describe the process of setting up a working Subversion server, creating a repository and add to versioning a Visual Studio solution to work with.

2. Resources

During this article I will guide you through the installation process of the following software:

Subversion
TortoiseSVN
AnkhSVN

→ top of post
→ top of paragraph

3. Prerequisites – Install Software

• Install Subversion
• Install TortoiseSVN
• Install AnkhSVN

Install Subversion

Download the latest Subversion release from the download page and launch the installer. At the moment I’m writing the last available version is: svn-1.4.6-setup.exe.
Subversion will be installed under: C:\Program Files\Subversion.

Make sure that C:\Program Files\Subversion\bin is included in the %PATH% environment variable, otherwise add it following these steps:
right-click MyComputer and choose Properties –> Advanced, then click the button: Environment Variables.
Look for the name: Path between variable names (left column) in the bottom list.
Once found double click it, add a semi-colon to the ‘variable value‘ field and paste the path to Subversion bin directory (C:\Program Files\Subversion\bin).
Click ok three times to accept the changes.

Now open a command prompt and digit svn help. You should be able to see svn syntax information.
The installation succeeded. Now go on to the next step: Install TortoiseSVN

→ top of post
→ top of paragraph

Install TortoiseSVN

Download the latest TortoiseSVN release from the download page: TortoiseSVN-1.4.8.12137-win32-svn-1.4.6.msi and launch the installer.

→ top of post
→ top of paragraph

Install AnkhSVN

Download the latest AnkhSVN release: AnkhSetup-1.0.2.2778-Final.msi from the download page and launch the installer.

Now that you have installed it, forget it for a while and step through the next paragraphs.

→ top of post
→ top of paragraph

4. Setup a Subversion Repository with the Help of TortoiseSVN

• 4.1. Create a Repository
• 4.2. Setup a Security Policy
• 4.3. Run Subversion Server Process

Now you have a very cool GUI for Subversion provided by TortoiseSVN.
In the following paragraphs we will setup a Subversion repository on the local machine and we will start working with it.

4.1. Create a Repository

Create a new directory, e.g.: C:\develop\test\repo, right click it and choose: TortoiseSVN –> Create repository here… (see: Figure 1).
Accept the preselected option: Native filesystem (FSFS) at the prompt and click ok (see: Figure 2).
The new repository will be created and an informational message will tell you that ‘The Repository was successfully created‘.

Now let’s add some content. First of all prepare the standard layout: create a temporary directory next to the repo directory and call it temp: C:\develop\test\temp. Add three subdirectories inside it, named: trunk, tags, branches.
The trunk directory will become the main directory of our project and it will contain all the versioned data.
Right click on C:\develop\test\temp and choose: TortoiseSVN –> Import… and the Import window will open. Click the button on the right of the combobox: ‘URL of repository‘ (as shown in Figure 3).

A browse pop up window will open. Browse to the repository directory: C:\develop\test\repo and click OK.
The combobox will be filled with: file:///C:/develop/Test/repo.
Write the comment ‘Initial Repository Layout‘ in the ‘Import Message‘ text area at the bottom of the Import window and click OK (see: Figure 4).
Everything should be alright and the informational window shown in Figure 5 should appear. You can click OK and the repository layout is ready.

Now you can delete the temporary directory: C:\develop\test\temp.

4.2. Setup a Security Policy

Before starting to use your freshly created repository you must set a security policy, that is, you must create user accounts for the repository.
First of all open the file: C:\develop\test\repo\conf\svnserve.conf.
Have a read to the file and notice that all lines are commented (the pound character: # is the comment character).
Uncomment rows 12 and 13, remove any leading spaces at the beginning of the rows and change them to fit your security policy.
You can, for instance, decide to deny access to the repository to anonymous users and to unauthorized ones while giving full access to authorized users.
To obtain this result set those two lines as follows:

anon-access = none
auth-access = write

Then uncomment row 18 to tell Subversion where the user accounts information will be stored:

password-db = passwd

where ‘passwd‘ is the name of a file in the same directory as ‘svnserve.conf‘ (C:\develop\test\repo\conf\passwd).
Open the ‘passwd‘ file and you will find two example rows, at rows 7 and 8, showing the syntax to define users:

# harry = harryssecret
# sally = sallyssecret

The two lines are commented but they clearly show that the syntax is:

user = password

Add information about the account that you will use to access the repository (e.g.: test = test).

4.3. Run Subversion Server Process

You can simply start svn server process from the command line.
Open a command prompt and digit:

svnserve -d -r “C:\develop\test\repo”

and you’re done!
If you prefer to run Subversion in order to let it manage different repositories placed under a common directory, you can run the Subversion server process in that directory, e.g.:

svnserve -d -r “C:\develop”.

The row above will let Subversion be able to expose repositories placed in the paths:

C:\develop\TestRepo1
C:\develop\TestRepo2
…

If you prefer to run Subversion as a Windows service, have a look at the paragraph: Install Subversion as a Service.

5. Checkout a Working Copy

Now you can prepare your workin copy or, in Subversion language, checkout your working copy.
Create a new directory named ‘wk’: C:\develop\test\wk.
Right-click the directory: C:\develop\test\repo and choose: SVN Checkout…. The Checkout panel will open.
Notice that the box: ‘URL of repository‘ is already filled with the path: file:///C:/develop/test/repo (see: Figure 6).

You need to modify that path to match the exact path to the repository and you can do it in one of two ways:

• Just add ‘trunk‘ to the path, because we want that only the content under that directory is copied in our working copy.
  The ‘URL of repository‘ will then be: file:///C:/develop/test/repo/trunk.
  This choice doesn’t need to have svnserve running and it’s good for a local test environment.
• If you want to use Subversion through your network (i.e. in a real environment) and if you want to take advantage of the Subversion security policy that we have set up in the previous paragraph, you’d better use this alternative option:
  Let’s assume that you have run svnserve with the following row: svnserve -d -r “C:\develop\test\repo” as explained in paragraph 4.3.
  Delete the content of the ‘URL of repository‘ box and replace it with: ‘svn://localhost/trunk‘.
  The example is provided assuming Subversion server installed on the local machine but you can replace localhost with the server machine name or IP address.
  We need to specify the path of the repository relative to the working directory of Subversion (svnserve), which is: C:\develop\test\repo, so the path that we specify is simply: trunk.

In the rest of the article we will assume the second choice.
After having set the ‘URL of repository‘ we must fill the ‘Checkout directory‘ box and we can do it browsing to C:\develop\wk by means of the adjacent button (see: Figure 7).
Make sure that ‘HEAD revision‘ is checked and click OK.

If you have set the ‘URL of repository‘ to svn://localhost/trunk you will be prompted for username and password (see Figure 8).

Fill both fields with: ‘test‘ or whatever account information you configured in the paragraph: 4.2. Set a Security Policy and flag the ‘Save authentication‘ checkbox, then click OK.
An informational window will appear stating that the checkout was succesfully created (see: Figure 9).

Close that window and look inside the C:\develop\wk directory.
The wk directory has been filled with the content from the repository’s trunk directory, that is the directory is empty.
Actually it’s not quite empty: there’s a directory named .svn inside it.
Such directory contains all the information needed by Subversion to keep track of the history of all the files that will be added to versioning inside this directory.
Now let’s go to the following step and start adding content.

6. Add content and Commit

• 6.1. Add a Text File to Versioning
• 6.2. Add a Visual Studio Solution to Versioning (TortoiseSVN)
  
• 6.3. Add a Visual Studio Solution to Versioning (AnkhSVN)

6.1. Add a Text File to Versioning

Let’s add a simple text file to versioning: create a file named ‘test.txt‘ inside C:\develop\wk.
Right-click it and choose: TortoiseSVN –> Add… (see: Figure 10), then click OK at the following two prompts and you will see an overlay blue plus icon above your file meaning that the file has been scheduled for inclusion in the repository upon the next commit.

If you can’t see the overlay icon, just press F5 to refresh the screen.
Now execute your first commit thus sending the new file to the repository. From now on, its changes will be tracked by the Subversion versioning system.
If you want to commit the content of the directory all at once (only one file at the moment) just go up one level, right click on the directory: C:\develop\wk and choose: SVN –> Commit… (see: Figure 11).
If you checked the ‘Save authentication‘ checkbox when checking out the working copy (as shown in 5. Checkout a Working Copy) you won’t be prompted, now, for username and password.

The Log Message window will open (see: Figure 12), waiting for you to provide a meaningful message. Write: “Added empty test file” and click OK.

Make sure that everything worked fine when the informational window titled: ‘wk – TortoiseSVN Commit… Finished!‘ will appear.
It should state something like: ‘Completed At revision: 1‘.
If everything is alright then click OK.

Now you can start adding content to the file and commit the changes to the repository.

→ top of post
→ top of paragraph

6.2. Add a Visual Studio Solution to Versioning (TortoiseSVN)

Let’s talk about versioning a Visual Studio solution (I won’t talk here about how to create Visual Studio solutions and projects).
Open Visual Studio (I’m working with Visual Studio 2005) and create a new blank solution inside C:\develop\wk.
Name the solution: DummySolution.sln and add two projects to the solution:
DummyProject.csproj and DummyProject.Tests.csproj.
The first is a Class Library project and the second is a Nunit Tests project referencing DummyProject.
If you’re using Nunit and RhinoMocks you can take advantage of the project Template I provide with the TDDTemplates.vsi (see article: Visual Studio Nunit & Rhino Mocks Templates) installer to easily create the unit tests project.
Now you can add the solution to versioning in one of two ways:

1. adding the solution file and the projects directories with TortoiseSVN;
2. installing AnkhSVN and versioning the solution directly from Visual Studio;

In this paragraph we’ll see the first option while in the next paragraph we will repeat the same actions with AnkhSVN.

At first select the solution file: DummySolution.sln and the two project directories: DummyProject and DummyProject.Tests.
Be careful not to select the file: DummySolution.suo, which contains solution-wide configuration data specific to every developer’s machine.
Then right-click one of the selected items and choose: TortoiseSVN –> Add…..
In the Add window (see: Figure 13) uncheck the directories: bin and obj of each project and the files: DummyProject.csproj.user and DummyProject.Tests.csproj.user if you find any of them in the list of checked items.
Click OK and a report window, titled: TortoiseSVN Add… Finished!, should appear if everything worked well. Click OK again as you did for the ‘test.txt’ file.
Now all the content needed is scheduled to be added to versioning upon the next commit action.

Now you can commit the freshly added content to the repository: right click on the directory C:\develop\wk and choose: SVN –> Commit… as you did when you added the test.txt file.

6.3. Add a Visual Studio Solution to Versioning (AnkhSVN)

As an alternative to previous paragraph, we can add the Visual Studio solution to versioning directly from the Visual Studio GUI with the help of AnkhSVN.

Before reading the current paragraph you need to install AnkhSVN as in Install AnkhSVN.

Open the solution file: DummySolution.sln with Visual Studio 2005.
A little prompt window (see: Figure 14) will ask if you want to enable AnkhSVN for the current solution:

Click No and go to solution explorer. Right-click the solution item and choose:
Ankh –> Add solution to Subversion repository… as shown in Figure 15:

The appropriate window will pop up (see: Figure 16) asking you the repository url. Fill the URL textbox with: svn://localhost/trunk , leave ‘Create subdirectory‘ unchecked and click OK.

You will be prompted for username and password (they are managed separately by TortoiseSVN and by AnkhSVN) as shown in Figure 17.
Fill both the fields and check ‘Save credentials‘.

Upon clicking the OK button one more window will popup showing you the files that AnkhSVN is going to add to the repository and waiting for you to add a meaningful log message for the commit (see: Figure 18).
AnkhSVN already left out the directories: bin, obj and their content as well as files: DummyProject.csproj .user and DummyProject.Tests.csproj.user that you had to manually uncheck when using TorotoiseSVN.
Write something like: ‘Added Visual Studio solution‘ and click the Commit button.

A Committing progress bar will appear and, upon success, the solution explorer will be updated with green icons before the names of versioned items (see: Figure 19).

Now that AnkhSVN is enabled for this solution, each time you add a new item to a project it will be marked with a question mark icon to let you know that the file is not added to versioning (see: Figure 20).
Let’s see it in action by adding a new item in solution explorer:
right-click on DummyProject and choose: Add –> New Item…, select the Class item template, leave the default name (should be Class2.cs) and click the Add button.

If you right-click on the solution in solution explorer and choose: Ankh –> Add… a new window will open, whose title is: Select items to add (see: Figure 21).
It contains the list of non versioned files in the current solution, each prefixed by a checkbox.
They are all checked by default, meaning that they will be scheduled to be added to versioning if you will click OK.

After choosing OK the Class2.cs file in solution explorer will have a yellow plus icon beside (see: Figure 22), meaning that it is scheduled to be added at the next commit (the same is true for the project and solution items).

Right-click the solution item and choose: Commit…. The Commit dialog will open.
At the same time the icons beside the project and solution items become red squares (see: Figure 23), meaning that there are local modifications that need to be committed to the repository.
Provide a meaningful message and click the Commit button (see: Figure 24).

Whenever you want to quit using AnkhSVN you can disable it for the solution you are using.
Just right click the solution item and choose: Ankh –> Disable Ankh for this solution.
You can then work using TortoiseSVN or the Subversion command-line.
If you want to enable Ankh again just choose: Ankh –> Enable Ankh for this solution.

7. Install Subversion as a Service

If you want to Install Subversion as a Windows service you can use the utility: sc.exe, where sc stands for “Service Control”.
Below you find a sample batch script to automate the install process.
You can copy into a text file and save it, for example, as InstallSvnService.bat.
Open a command prompt in the directory in which you placed the .bat file and run it by digiting
InstallSvnService and pressing return.
The service will be installed and configured to start automatically.


sc create svnserve ^
binpath= "\"C:\Program Files\Subversion\bin\svnserve.exe\" -r ^ \"C:\develop\test\repo\" --service" ^
displayname= "Subversion" ^
depend= Tcpip ^
start= auto


Note that the caret symbol (^) in the script code is the line continuation character for batch scripts. It allows us to split the long command in multiple lines in order to make it more readable.
The line continuation character tells to the command interpreter that the current command is not ending at the first newline but is going on in the next line.

It’s possible that you need to change the path:
“C:\Program Files\Subversion\bin\svnserve.exe” depending on where is your copy of Subversion installed.
The path: “C:\develop\test\repo\” in the example is the path to the location in which svnserve will find the repositories to host.
Once the batch file has run open the administrative panel for services to make sure that the Subversion service exists and is running:
go to: Start –> Administrative Tools –> Services
scroll down looking for a service named Subversion and if it is not running click on the Start link.

→ top of post
→ top of paragraph

1. Download

I recently contributed to a project that I find very useful:

SvnRevisionLabeller (direct download link) plugin for CruiseControl.NET by David Keaveny.
You can also find it having a look at the Contributions Page in the CruiseControl.Net official website (it’s the third item under the title: Labeller Blocks).

→ top of paragraph
→ top of post

2. Description

David Keaveny’s SvnRevisionLabeller lets CruiseControl.NET generate build labels based upon Subversion’s repository revision number.

I contributed to the project with a bug fix and by adding support for secure access to a Subversion repository (connecting with a repository’s particular account: username and password).

A file named Readme.txt comes zipped with the distribution.
Inside that file you can find instructions about how to install and configure SvnRevisionLabeller as the Labeller Block of choice in your CCnet configuration file.

In this article I will try to briefly guide you through these steps.

→ top of paragraph
→ top of post

3. Usage

Let’s have a look at how to setup CruiseControl.NET server to work with the SvnRevisionLabeller plugin.

3.1. Build Labels

SvnRevisionLabeller produces build labels in the format:

major.minor.svnRevision.build

major and minor numbers are set in the configuration of the Labeller Block,
svnRevision number is retrieved from the Subversion repository,
build is automatically incremented if a new build is forced when no further modification to the repository happened.

The label produced by whichever Labeller Block is made available to the Task Blocks by means of the environment variable: CCNetLabel.
That environment variable can then be accessed by NAnt or MSBuild (as ${CCNetLabel} or $(CCNetLabel)) or by an External script with the usual syntax for environment variables on Windows Operating Systems: %CCNetLabel%.

3.2. Installation

Installing the SvnRevisionLabeller plugin is just a matter of unzipping the package (ccnet.SvnRevisionLabeller.plugin.zip) into a temporary directory and of copying the assembly:
src\ccnet.SvnRevisionLabeller.plugin\bin\Release\ccnet.SvnRevisionLabeller.plugin.dll

that you find inside the temporary directory into the directory in which CruiseControl.NET has been installed (e.g.: C:\Program Files\CruiseControl.NET\server).

Next you need to configure the Labeller Block in your projects in order to let them use SvnRevisionLabeller.
Let’s see how.

3.3. Configuration

Following is the basic configuration for SvnRevisionLabeller. Only the required fields are set:

<labeller type="svnRevisionLabeller">
  <major>7</major>
  <minor>11</minor>
  <url>svn://localhost/repository/trunk</url>
</labeller>

<sourcecontrol type="svn">
  <trunkurl>svn://localhost/repository/trunk</trunkurl>
  ...
</sourcecontrol>

<labeller type="svnRevisionLabeller">
  <prefix>Test-</prefix>
  <major>7</major>
  <minor>11</minor>
  <url>svn://localhost/repository/trunk</url>
  <username>ccnetuser</username>
  <password>ccnetpassword</password>
</labeller>

→ top of paragraph
→ top of post

1. Introduction – Path to Common Assemblies

When you need to place some common references in your solutions and you don’t want to register the referenced assemblies into the GAC (because they change frequently or for whatever other reason), you can decide to act as suggested in the article Team Development with Visual Studio .NET and Visual SourceSafe on msdn at the paragraph: Use a Virtual Drive Letter for Greater Flexibility.

The article presents an easy way to have a common environment on different machines.
Often there’s the need, for a team, to agree a directory path to be reproduced on each developer machine.
For example your team could agree in placing all third parties’ assemblies in a directory named: C:\develop\common.
It will be care of each developer to create such directory on his machine and to keep it up to date with the new releases of the assemblies.

This approach requires that developers set up analogous directory structures in their working environment. They are at least required to have a directory named C:\develop\common.
What you can do is to reduce this constraint, at a certain level, by using virtual drive letter mapping.

Instead of agreeing a path that each develper is supposed to have on his own machine your team must simply agree on a drive letter name. Each developer will be free to choose the path he prefers and he will only have to map it to a virtual drive letter with the agreed name by using the subst command.

→ top of paragraph
→ top of post

2. Subst Command

The subst command serves the purpose of mapping a physical path on disk to a virtual drive letter.
Just digit subst /? at a command prompt or visit Microsoft technet command-line reference page to learn more.

The syntax is: subst [drive1: [drive2:]Path]

where drive1 is the name of the virtual drive to which you want to map a path and drive2:Path represents the path itself.

e.g.: subst G: C:\develop\common

By mapping different paths on different machines to a common drive letter you can, from this moment on, let your project files reference common assemblies using paths relative to the virtual drive: G: (see again Use a Virtual Drive Letter for Greater Flexibility).

→ top of paragraph
→ top of post

In this article I will talk about possible issues when creating a SolutionInfo.cs file
while using the Partitioned single solution development model.

1. Prerequisites

While writing this article I was using the following software:

Visual Studio 2005
Subversion (Download the latest version)

2. Introduction – SolutionInfo.cs

Having multiple projects in a solution means having multiple assemblies, and having multiple assemblies could mean that you want to deploy them as separate assemblies.
Each project generated by Visual Studio 2005 contains, by default, an AssemblyInfo.cs file in which you can write assembly attributes.
If you open AssemblyInfo.cs you will find a set of assembly attributes with default values.
The values for some of these attributes could vary from project to project but others (such as AssemblyVersion) should be application wide.
For this purpose a common choice is the SolutionInfo.cs pattern as illustrated by Juval Lowy (you can find his book: Programming .NET Components, 2nd Edition at Amazon).
It consists in grouping all the attributes common to all projects (solution wide attributes) in a separate file named SolutionInfo.cs that will be included as a solution item.
Each project will contain, under the Properties directory, an AssemblyInfo.cs file and a link to the shared SolutionInfo.cs file (see note: Add file as link).
Adding that file as a link allows you to modify always the same file, no matter which link you open so having all the projects’ properties updated at once.
This approach is very useful for incrementing Version Number.

→ top of paragraph
→ top of post

3. Introduction – Partitioned single solution

References:

Structuring Solutions and Projects (MSDN Article)
or you can find an updated version of the preceding article in the book:
‘Team development with visual studio team foundation server‘
that you can freely download at: http://www.codeplex.com/TFSGuide

Partitioned Single Solution:

As shown in the articles above, when you have a big application and want to allow developers to work on smaller portions of the appliction, you can consider using the ‘partitioned single solution‘ development model.
It consists in creating a top solution containing all the projects in the application and then introducing separate solution files for subsets of related projects.
Each solution file will contain all the projects a develper needs to work on and all the referenced projects.
In this way it is possible to checkout only the projects actually needed on each developer’s workstation, thus obtaining a lighter build process during the development stage.

This approach requires additional work and time to keep all the solution files aligned but it provides a safer way to share work on the same application between different developers.

→ top of paragraph
→ top of post

4. Partitioned single solution and SolutionInfo.cs – The problem

This article aims to point out that there are a couple of drawbacks in combining the SolutionInfo pattern with the Partitioned single solution model.

Case Scenario 1:

First of all the SolutionInfo approach makes it impossible for a developer to copy the project as is to another location and import it into another solution file.
At compile time he would get the following message:

‘Error 1 Source file ‘pathToSolution\SolutionInfo.cs’ could not be opened …’

He will have to create a SolutionInfo.cs file in the same directory in which the copy of the project is placed in order to make the build succeed.

To understand why this fixes the problem let’s have a look at what happens behind the scenes:

Say that we created projects leaving the Visual Studio default behavior unchanged, that is, they are located in subdirectories of the directory containing the solution file.
When we add a file as link to a project (see note), the following lines will be added to the project file (projectName.csproj) under the ‘ItemGroup‘ tag:

<compile Include="..\SolutionInfo.cs">
    <link>Properties\SolutionInfo.cs</link>
</compile>

We could decide to create a directory structure as shown in the following picture:

Case Scenario 3:

What if we want to add a solution file for each project and we want to place it in the project’s directory?

A developer could checkout from the repository only a project’s directory and he would get the solution file too.
But when he will try to build the solution he will get the file missing error!
If he provides a copy of SolutionInfo.cs in the solution’s directory (which is the project’s directory too) it won’t work because MSbuild (as we said before) looks for the file up one level (..\SolutionInfo.cs).
The developer should create a SolutionInfo.cs file outside of its working copy to make the build succeed.If we have a more complicated directory structure with different levels of directories, with project directories in some of this levels, and with solution files in some of these levels too, the situation is even worse.
In fact the SolutionInfo.cs file is located more than one level up with respect to some of this project and solution files as you can see in the following image:

Each time a developer checks out a solution directory that is not the root one he will miss the SolutionInfo.cs file and he’ll need to open a project file in a text editor to know were it is supposed to be.

→ top of paragraph
→ top of post

5. Partitioned single solution and SolutionInfo.cs – The Solution

In order to avoid uncertainty about where each project expects the SolutionInfo.cs to be placed, we need to reference it with a path relative to the solution location instead of the project’s directory. So we can open projectName.csproj in a text editor and modify the entry as follows:

SolutionDir variable

<compile Include="$(SolutionDir)\SolutionInfo.cs">
    <link>Properties\SolutionInfo.cs</link>
</compile>

the ‘Compile‘ tag in the projectName.csproj file supports another useful attribute: ‘Condition‘.
The condition specified by such attribute will be evaluated by MSBuild during the build process and the file will be compiled only if the condition is satisfied.
We could add it to the row related to SolutionInfo.cs thus obtaining:

<compile Include="$(SolutionDir)\SolutionInfo.cs"
        Condition="Exists('$(SolutionDir)\SolutionInfo.cs')">
    <link>Properties\SolutionInfo.cs</link>
</compile>

6. Subversion Issue 695 and Release 1.5

If you use Subversions as Version Control System you must be aware of a problem in which you may run into when working with a partitioned single solution model.
If you organize your repository, say, like in the case scenario 2, and you want to checkout a solution (not the global one) and only the projects (and projects’ directories) referenced by that solution you should do it in two separate steps:

first of all keep in mind that with Subversion you can only checkout directories, so you cannot have only the solution file you need but you’re forced to get in your working copy all the solution files defined in the root directory:

- checkout non-recursively the root directory (the one with the solution files),

next you can add to your working copy only the projects’ directories you want:

- call svn update separately specifying the subdirectories you need.

This will seem to work at first but it is not true.
There’s an old implementation issue in Subversion (see: issue 695), related to checking out a directory non-recursively :

the issue consists in the fact that such a directory in the working-copy is not aware of being a partial checkout. So as long as anyone works on identical working copies everything works fine otherwise you will obtain a weird behavior.
If someone commits changes to, say, a directory that you didn’t check out from the repository, the first time you will make a global update of your working copy you’ll get the following error message:

>> Error: Directory ‘pathToWorkingCopy\project3Dir’ is missing
>> Error: Please execute the “Cleanup” command.

If you execute the cleanup and try to update again, the whole root directory will be checked out in your working copy!

The bug has been fixed and sparse directory checkout should be allowed with the upcoming 1.5 version of Subversion.
At the moment if you want to be safe with your working copy you have to checkout the whole root directory.

→ top of paragraph
→ top of post

7. Notes

7.1. Add file as link
7.2. Set Build Action to None

7.1. Add file as link

When you want to add a file as link to a project simply right click on the project and choose Add –> Existing item.
In the choose file dialog box locate and select the file you want (say e.g. SolutionInfo.cs). Don’t click the Add button, you should click the little down arrow on the right edge of the Add button instead. A drop down menu will appear as shown in the picture. Choose Add as link and you’re done (then you can move the link anywhere else in the project directory structure simply dragging it in Solution Explorer).

→ top of paragraph
→ top of post

7.2. Set Build Action to None

To set the Build Action to None for a project item simply select the item in Solution Explorer (e.g.: SolutionInfo.cs) and look at the Properties Panel.
A bunch of properties will be shown for the selected item through which you will see: ‘Build Action‘ with the value ‘Compile‘. Just click on the value and a drop down list will appear as shown in the picture. Select ‘None‘ and you’re done.

→ top of paragraph
→ top of post

1. Sourcecode tag in WordPress

Many of you already know that there’s this cool tag in wordpress allowing us to post code without worrying about formatting:

In fact it takes care of syntax highligthing as well as preserving good indentation, like in the following example of a CSS rule:

.Test
{
    background-image:url('/images/Bckgrnd.jpg');
    background-color:#FFFFFF;
    border:solid 1px #7E7E81;
    cursor:pointer;
}

• actionscript3
• bash
• coldfusion
• cpp
• csharp
• css
• delphi
• erlang
• fsharp
• diff
• groovy
• javascript
• java
• javafx
• matlab (keywords only)
• objc
• perl
• php
• python
• powershell
• r
• ruby
• scala
• sql
• vb
• xml

You can find info at the following link:

How do I post source code?

2. Not for all Themes

What you may not know is that this feature does not work with all the themes available, for example it doesn’t work with the default wordpress theme: Kubrick.

Hope this is a useful info for people trying to make it work right now.

→ go to top