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

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

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 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 >>

1. Download
2. Description
3. Usage
3.1. Build Labels
3.2. Installation
3.3. Configuration

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>

where:<major> and <minor> are the first two numbers in the build label:
7.11.svnRevision.build
and <url> represents the path to the repository monitored by the current CruiseControl.net project. Actually the <url> field must be filled with the same path used in the <trunkurl> field of the Subversion Source Control Block:

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

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

<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>

where:<prefix> is a prefix added to the build label in the 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’d better create a specific account used only by CruiseControl.NET.That’s it! In this way CruiseControl.NET will flag its builds with the revision number from Subversion and you can retrieve such value if you want to use it to modify the AssemblyInfo.cs files in your Visual Studio projects or if you want to flag your administrative backup names.

→ top of paragraph
→ top of post

1. Prerequisites
2. Introduction – SolutionInfo.cs
3. Introduction – Partitioned single solution
4. Partitioned single solution and SolutionInfo.cs – The problem
5. Partitioned single solution and SolutionInfo.cs – The Solution
6. Subversion Issue 695 and Release 1.5
7. Notes
7.1. Add a file as link
7.2. Set Build Action to None

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>

The ‘Include‘ attribute stores the path to the original file that we’re linking to.
The ‘Link‘ tag stores the path in which the link will be shown in Solution Explorer (including possible solution directory e.g.: ‘Properties‘).
As you can see, the ‘Include‘ attribute stores the relative path to SolutionInfo.cs with respect to the projectName.csproj file location. This will end up in Visual Studio (and MSbuild) looking for a file named SolutionInfo.cs one level above with respect to the projectName.csproj file.So this is the reason for the error message shown above if copying a project directory anywhere else.Let’s go further and introduce the SolutionInfo method in a Partitioned Single Solution.The default Visual Studio behaviour of introducing relative paths (instead of using paths relative to the solution path) makes linking a file (e.g.: SolutionInfo.cs) in a Partitioned Single Solution structure an error prone procedure.
In fact it can easily lead to the build error reported above, if we use nested directory structures.
Let’s have a look at the possible situations:

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>

In this way we let the projects be independent of their location in the directory structure.Let’s go one step further.
If a developer doesn’t want to provide a SolutionInfo.cs file to its custom solution his solution won’t compile unless he sets SolutionInfo.cs ‘Build Action‘ to ‘None‘ (see note: Set Build Action to None).
The problem here is that the ‘Build Action‘ of a file is stored in the versioned projectName.csproj file. Changing this setting will impact on the working copies of all developers using that same project and even on the release build script.
Luckily we can apply a work around to this problem:

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>

MSBuild will evaluate the condition and if it will not find the linked file in the specified path it won’t even try to compile it.
This will allow developers to always have their projects successfully built even if a SolutionInfo.cs file is not present on disk.
Solution Explorer will let the project build succeed but will show a broken link in the GUI to let the user know that something is missing.The assembly resulting from such a working copy build process will lack the solution wide assembly information but the continuous integration tools, as well as developers using solutions including a SolutionInfo.cs file, will have their projects build with the complete assembly information.

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. Introduction
2. System Requirements
3. Download and Install
4. Package Contents
4.1. Test Class Library Project Template
4.2. Test Class ItemTemplate
4.3. Code Snippets
5. Uninstall
6. Suggested Books

1. Introduction

If you’ve been using ‘NUnit’ you found yourself involved in doing repetitive actions like creating test projects and adding test classes and test methods.
If you ever had a try with the ‘Rhino Mocks’ mocking framework you had an extra bit of repetitive code to write, in all of your TestFixture classes.

I was tired of always creating a new test project for each project in my solution and manually add references.
I was tired of always prepare test classes with Setup and Teardown methods as well as other standard elements.

Then I created a standard Project Template creating a test class library, an Item Template creating a Rhino Mocks enabled TestFixture class, and a couple of useful code snippets.

All this stuff is targeted to Visual C# projects.

2. System Requirements

You’ll need the following software:

Visual Studio 2005
NUnit (NUnit-2.4.7-net-2.0.msi)
Rhino Mocks (Rhino.Mocks-3.4.zip)

Important: Project references are based on Nunit default installation path and on Rhino.Mocks.dll being installed into the location %ProgramFiles%\RhinoMocks. To install Rhino in such a path just donwload the .zip file and unzip it there.

Note: If your installation paths are different from the ones specified, you will need to modify project references once created a new test project with my template.

3. Download and Install

First of all download the file: TDDTemplates.vsi that you can find here.
All you have to do is download, double click, and proceed with the installation.
If you want more detailed description of what you are downloading, read further.

The file TDDTemplates.vsi is a Visual Studio installer file, containing:

1. A Project Template named Test Class Library;
2. An ItemTemplate named Test Class;
3. Two Code snippets useful for test driven develpment (TDD Snippet component).

Double-clicking on the installer file you will get a dialog window prompting you to choose wich of the listed items you want to install.
Clicking on the next button you will get a message warning that the installer file is not signed.
If you don’t want to install unsigned content you will need to create this installer by yourself and I will provide you with a brief tutorial in a future post.

If you will click the yes button, checked items will be installed:

• the Project Template (Test Class Library.zip) will be installed into the location:

%USERPROFILE%\MyDocuments\VisualStudio2005\Templates\ProjectTemplates\VisualC# (where %USERPROFILE% is C:\DocumentsandSettings\username in Windows Xp);

• the Item Template (Test Class.zip) will be installed into the location:

%USERPROFILE%\MyDocuments\VisualStudio2005\Templates\ItemTemplates\VisualC#;

• a dialog will allow you to choose were to install Code snippets (TDD.snippet):

if you choose My Code Snippets the snippet file will be installed into the location:
%USERPROFILE%\MyDocuments\VisualStudio2005\CodeSnippets\VisualC#\MyCodeSnippets,

while if you choose Visual C# it will be installed under the Visual Studio installation directory, into the location:
%ProgramFiles%\MicrosoftVisualStudio8\VC#\Snippets\1033\VisualC#.

→ go to top

4. Package Contents

4.1. Test Class Library Project Template
4.2. Test Class ItemTemplate
4.3. Code Snippets

In this paragraph you will find a detailed description of the contents installed by the Visual Studio installer we’re talking about: TDDTemplates.vsi.

4.1. Test Class Library Project Template

When creating a new project, the initial dialog will list a new project template under the Visual C# category: Test Class Library, as shown in the following image.

If you rename the project: ProjectName and click ok, a new class library project will be created with the structure shown in the following screenshot of the Solution Explorer window:

The file named Class1Tests.cs, created inside the project, contains the code defining the skeleton of a TestFixture class definition:

using System;
using System.Collections.Generic;
using System.Text;
using NUnit.Framework;
using NUnit.Framework.SyntaxHelpers;
using Rhino.Mocks;

namespace ProjectName
{
    [TestFixture]
    public class Class1Tests
    {
        MockRepository mocks;

        ///
        /// Prepares mock repository
        ///
        [SetUp]
        public void Initialize()
        {
            mocks = new MockRepository();
        }

        ///
        /// template behavior and state testing method
        ///
        [Test]
        public void TestMethod1()
        {
            IDependency dependency = mocks.CreateMock();

            // Record expectations
            using (mocks.Record())
            {
                Expect
                       .Call(dependency.Method1("parameter"))
                       .Return("result");
                dependency.Method2();
            }

            // Replay and validate interaction
            Subject subjectUnderTest;
            using (mocks.Playback())
            {
                subjectUnderTest = new Subject(dependency);
                subjectUnderTest.DoWork();
            }

            // Post-interaction assertion
            Assert.That(subjectUnderTest.WorkDone, Is.True);
        }
    }
}

As you can see the class definition already contains a default implementation of a Test method.
Such method includes the definition of RhinoMocks expectations for a hypothetical object under test.
I chose to use Rhino Mocks new Record-playback Syntax which takes care of calling mocks.ReplayAll() and mocks.VerifyAll() under the hood.
I feel this syntax is very neat and clean providing a clear separation between the moment in which we record expectations and the moment in which we use the object under test.

4.2. Test Class Item Template

When adding a new item to the project, the Add New Item dialog will list a new project template: Test Class.
It is possible that you have to scroll down a little to see the My Templates category, as shown in the following image:

Selecting the Test Class template, a new class definition file will be created, containing the same class definition you obtained when creating the Test Class Library Project (see previous paragraph).

→ top of paragraph
→ top of post

4.3. Code Snippets

From now on, when writing code, you will have two more intellisense entries in your IDE: TDDtestmethod and TDDusing.

TDDtestmethod will insert a test method definition as shown in the following sequence of images:

Selecting the keyword as in the preceding image will produce the following code:

The snippet allows the user to choose the method’s Attribute (defaults to: Nunit.Framework.TestAttribute) and the methods name (defaults to: TestMethod).

TDDusing will insert the two using blocks needed for the Rhino Mocks Record-playback Syntax, as shown in the following sequence of images:

Selecting the keyword as in the preceding image will produce the following code:

The snippet allows the user to choose the instance of Rhino.Mocks.MockRepository
to use for mocking objects.

→ top of paragraph
→ top of post

5. Uninstall

If you want to uninstall the installed content you can simply go to the paths specified in the Download and Install paragraph and delete the correct files:

delete the file: Test Class Library.zip under:
%USERPROFILE%\MyDocuments\VisualStudio2005\Templates\ProjectTemplates\VisualC#

delete the file: Test Class.zip under:
%USERPROFILE%\MyDocuments\VisualStudio2005\Templates\ItemTemplates\VisualC#;

depending on where you chose to install the snippets, find the file TDD.snippet file under:
%USERPROFILE%\MyDocuments\VisualStudio2005\CodeSnippets\VisualC#\MyCodeSnippets,
or under:
%ProgramFiles%\MicrosoftVisualStudio8\VC#\Snippets\1033\VisualC#
and delete it.

That’s all.
Feel free to post a comment if you want to report a bug or to propose enhancement of the templates and snippets.

→ top of paragraph
→ top of post

6. Suggested Books

Some useful reading about Test Driven Development and Nunit can be found in the following books:

Test Driven Development: By Example (The Addison-Wesley Signature Series)	Pragmatic Unit Testing in C# with NUnit, 2nd Edition

→ top of post

1. Introduction
2. The problem
3. Other solutions
4. The goal
5. Example
6. Conclusion
7. Advantages of this solution
8. Full source code

1. Introduction

Use of enumerations greatly enhance readability of code and let client code be type safe and easier to write.
We don’t need to write sets of constant values and related validation code, we only need to properly define enumeration items.

2. The problem

Sometimes we want to use clear and simple names for enumeration values but we want to show more meaningful string representations in some GUI.
This is were simply defining our custom enumeration is not enough.
In fact default string representation of enum items relies on the EnumConverter class. But EnumConverter simply uses the enum item’s name as its string representation.

3. Other solutions

When I first needed to solve this issue, I browsed the web and found few good articles about repurposing enumerations, such as: Repurposing Enumerations by Mathew Nolton and Localizing .NET Enums by Grant Frisken, and few more.
All of them rely on implementing a custom EnumConverter to be applied declaratively to the enumeration:

[TypeConverter(typeof(CustomConverter))]
public enum MyEnum
{
   ...
}

I found very instructive and interesting such approach but I still was not satisfied.
What I dislike is the need to change client code from a simple:

MyObject.Property = MyEnum.Item;
string humanReadable = MyObject.Property;

to:

MyObject.Property = MyEnum.Item;
string humanReadable = (string)TypeDescriptor.
GetConverter(typeof(MyEnum)).
ConvertTo(MyObject.Property, typeof(string));

→ go to top

4. The goal

What I wanted was a pattern whose goal is to minimize the changes to client code while being as simple as possible to implement.
All the articles that I read implied the need of a helper class (the custom EnumConverter), so I found it acceptable to implement a simple helper class too.
I wanted a pattern providing a sort of separation of concerns: keeping Enumeration behavior unchanged while providing a means to control its string representation.
The solution I’m going to illustrate is based on the use of conversion operators and I hope you will find it simple and straightforward.

→ go to top

5. Example

A typical situation could be a Clock application that we want to be able to display date and/or time in different formats.
We will name the format choices using simple enumeration items (e.g.: DateTimeFormat.Date, DateTimeFormat.Time) but we’ll need to convert them in actual formats.
The actual formats (e.g.: ‘dd/MM/yyyy’, ‘HH:mm:ss’) are needed to instruct the Clock object about how to render itself and its embedded DateTime in the form of a text string in a specific format.
Take a look at the following code:

remark: note that comments on method calls in the client code state only the expected behavior.
We will obtain it only at the end of the example.

/***************
* Client code: *
****************/

Clock clock = new Clock();
// clock.DisplayedFormat accepts enumeration values
// (e.g.: 'DateTimeFormat.Date')
clock.DisplayedFormat = DateTimeFormat.Date;
// Enum value will be converted internally in the
// actual format and used by the Clock so that we can
// simply tell it to represent as string.
Console.WriteLine(clock);

// clock.DisplayedFormat returns the actual format
// string (e.g.: 'dd/MM/yyyy')
string format = clock.DisplayedFormat;
Console.WriteLine(format);

// ouptus:
// 10/01/2008
// dd/MM/yyyy

Let’s implement the Types we need:

/*************
* Enum code: *
**************/

public enum DateTimeFormat
{
    Date,
    Time
}

Let’s Try and implement Clock’s basic functionality:

/*************
* Clock code:*
**************/

public class Clock
{

  #region fields

  private DateTime m_CurrentDateTime = DateTime.Now;
  // defaults to Time format
  private DateTimeFormat m_Format = DateTimeFormat.Time; 

  #endregion
  #region properties

  /// <summary>
  /// format used to display current datetime
  /// </summary>
  public DateTimeFormat DisplayedFormat
  {
      get
      {
          return m_Format;
      }
      set
      {
          m_Format = value;
      }
  }

  #endregion
  #region methods

   /// <summary>
   /// provides string representation of current DateTime
   /// depending on the format set.
   /// </summary>
   /// <returns>returns current date or time</returns>
   public override string ToString()
   {
       return m_CurrentDateTime.
              ToString(DisplayedFormat.ToString());
   }

   #endregion
}

The three preceding slices of code don’t even compile because in the client code we need to provide explicit conversion from the Enum value to a string.
So we need to replace the line:

string format = clock.DisplayedFormat;

with:

string format = clock.DisplayedFormat.ToString();

Now that the code compiles we still have some wierd results.
In fact we provided a not meaningful format (the string representation of the enum value: ‘date’) to the m_CurrentDateTime.ToString( ) method.
To let this code work we could implement a custom EnumConverter in order to represent the enum values as we like. But this choice would force us to modify client code as shown in paragraph: ‘Other solutions’.

string format = clock.DisplayedFormat;

To obtain the expected result we will implement a nested helper class named: Format.

public class Format
{
   #region const

   const string
      Date = "dd/MM/yyyy",
      Time = "HH:mm:ss";

   #endregion
   #region fields

   DateTimeFormat m_CalendarFormat;

   #endregion
   #region .CTOR

   /// <summary>
   /// each Format instance represents a different value
   /// of DateTimeFormat enumeration
   /// </summary>
   /// <param name="calendarFormat">DateTimeFormat value
   /// </param>
   public Format(DateTimeFormat calendarFormat)
   {
       m_CalendarFormat = calendarFormat;
   }

   #endregion
   #region methods

   /// <summary>
   /// converts current Format instance into its string
   /// representation, i.e. the actual format string
   /// </summary>
   /// <returns>actual format string represented by the
   /// current Format instance (e.g.: "dd/MM/yyy")</returns>
   public override string ToString()
   {
       return Convert();
   }

    /// <summary>
    /// converts enum values in actual datetime formats
    /// </summary>
    /// <returns>returns valid datetime format</returns>
    private string Convert()
    {
        string format = null;
        switch (m_CalendarFormat)
        {
            case DateTimeFormat.Date:
                format = Date;
                break;
            case DateTimeFormat.Time:
                format = Time;
                break;
            default:
                throw new Exception(
                              "Format is not initialized!!");
         }
         return format;
     }

     #endregion
}

Every instance of Format is initialized with a DateTimeFormat value and represents that
value and the string representation we want for it.
Now that we have the helper class we can replace Clock.DisplayedFormat returned type with: Format.

private Format m_Format;
public Format DisplayedFormat
{
	get
	{
		return m_Format;
	}
	set
	{
		m_Format = value;
	}
}

This would force us to change our client code like the following:

Clock clock = new Clock();
// FOLLOWING ROW IS CHANGED
clock.DisplayedFormat= new Clock.Format(DateTimeFormat.Date);
Console.WriteLine(clock);

// clock.DisplayedFormat returns the actual
// format string (i.e.: 'dd/MM/yyyy')
string format = clock.DisplayedFormat.ToString();
Console.WriteLine(format);

Now in client and Clock code the following row:

string format = clock.DisplayedFormat.ToString();

returns the correct string representation of the chosen format (i.e.: ‘dd/MM/yyyy’).
At this point we’re still forced to make too many modifications to client code.
This is where conversion operators come in place!!

/// <summary>
/// converts a DateTimeFormat value into a Format instance
/// </summary>
public static implicit operator Format(DateTimeFormat arg)
{
	return new Format(arg);
}

/// <summary>
/// converts a Format instance into a string
/// </summary>
public static implicit operator string(Format arg)
{
	return arg.Convert();
}

The first one provides implicit conversion of DateTimeFormat values in Format instances.
This allows us to set clock.DisplayedFormat by simply providing the enumeration value:

clock.DisplayedFormat = DateTimeFormat.Date;

The second one provides implicit conversion of a Format instance into its string representation, the actual format string (i.e.: “dd/MM/yyy”).
This allows us to retrieve the desired actual format string by simply getting clock.DisplayedFormat:

string format = clock.DisplayedFormat;

→ top of paragraph
→ top of post

6. Conclusion

Eventually, to achieve the desired result, we only need two things.
We only need to implement the helper class and to replace the clock.Property returned type and it will work like a charm!

→ go to top

7. Advantages of this solution

Following are advantages of this solution:

• Simple to implement (it is more difficult to explain than to code)
• No changes to client code needed
• Separation of concerns (relying on Format class to convert enum values and not on the enumeration itself by means of a custom converter)
• Works with existing enumerations too

→ go to top

8. Full source code

• Clock code
• Client code

Clock Code:

/*************
* Clock code:*
**************/

using System;

namespace FormatProvider
{
  public enum DateTimeFormat
  {
    Date,
    Time
  }

  /// <summary>
  /// displays date or time
  /// </summary>
  public class Clock
  {
    #region nested class

    /// <summary>
    /// encapsulate a DateTimeFormat and its
    /// string representation
    /// </summary>
    public class Format
    {
      #region const
      const string
              Date = "dd/MM/yyyy",
              Time = "HH:mm:ss";
      #endregion
      #region fields

      DateTimeFormat m_CalendarFormat;

      #endregion
      #region .CTOR
      /// <summary>
      /// each Format instance represents a different value
      /// of DateTimeFormat enumeration
      /// </summary>
      /// <param name="calendarFormat">DateTimeFormat value
      /// </param>
      public Format(DateTimeFormat calendarFormat)
      {
          m_CalendarFormat = calendarFormat;
      } 

      #endregion
      #region methods

      /// <summary>
      /// provides implicit conversion of DateTimeFormat
      /// values in Format instances
      /// </summary>
      /// <param name="arg">DateTimeFormat value</param>
      /// <returns>Format instance corresponding to the
      /// DateTimeFormat value provided</returns>
      public static implicit operator Format(
                                   DateTimeFormat arg)
      {
          return new Format(arg);
      }

      /// <summary>
      /// provides implicit conversion of a Format instance
      /// in its string representation, i.e. the actual
      /// format string</summary>
      /// <param name="arg">a Format instance to convert in
      /// string representation</param>
      /// <returns>returns the actual format string
      /// represented by the current Format instance
      /// (i.e.: "dd/MM/yyy")</returns>
      public static implicit operator string(Format arg)
      {
          return arg.Convert();
      }

      /// <summary>
      /// converts current Format instance
      /// in its string representation, i.e. the actual
      /// format string</summary>
      /// <returns>actual format string represented by the
      /// current Format instance (i.e.: "dd/MM/yyy")
      /// </returns>
      public override string ToString()
      {
          return Convert();
      }

      /// <summary>
      /// converts enum values in actual datetime formats
      /// </summary>
      /// <returns>returns valid datetime format</returns>
      private string Convert()
      {
          string format = null;
          switch (m_CalendarFormat)
          {
              case DateTimeFormat.Date:
                  format = Date;
                  break;
              case DateTimeFormat.Time:
                  format = Time;
                  break;
              default:
                  throw new Exception(
                               "Format not initialized!!");
          }
          return format;
      } 

      #endregion
    } 

    #endregion
    #region fields

    private DateTime m_CurrentDateTime = DateTime.Now;
    // defaults to time
    private Format m_Format = DateTimeFormat.Time;

    #endregion
    #region properties

    /// <summary>
    /// format used to display current datetime
    /// </summary>
    public Format DisplayedFormat
    {
        get
        {
            return m_Format;
        }
        set
        {
            m_Format = value;
        }
    } 

    #endregion
    #region methods

    /// <summary>
    /// provide string representation of current datetime
    /// depending on the format set.
    /// </summary>
    /// <returns>returns current date or time</returns>
    public override string ToString()
    {
        return m_CurrentDateTime.ToString(DisplayedFormat);
    } 

    #endregion
  }
}

→ top of paragraph
→ top of post

Client Code:

/***************
* Client code: *
****************/

using System;
using FormatProvider;

namespace ClientCode
{
    class Program
    {
        static void Main(string[] args)
        {
            Clock clock = new Clock();
            // clock.DisplayedFormat accepts enumeration
            // values (i.e.: 'DateTimeFormat.Date')
            clock.DisplayedFormat = DateTimeFormat.Date;
            Console.WriteLine(clock);

            // clock.DisplayedFormat returns the actual
            // format string (i.e.: 'dd/MM/yyyy')
            string format = clock.DisplayedFormat;
            Console.WriteLine(format);

            // output:
            // 08/01/2008
            // dd/MM/yyyy
        }
    }
}

→ top of paragraph
→ top of post