Configure Draco.NET for Use

Draco.NET is a config-file-driven Windows service that monitors source-code repositories for changes, automatically gets the latest code, compiles it, and sends e-mails reporting the results. It supports several source-control products, including Visual SourceSafe, CVS, and PVCS, as well as several ways of compiling your project code: Visual Studio.NET, MSBuild, and NAnt. It is open source and completely free to use for both personal and commercial projects.

Draco.NET is a Windows service programmed in .NET, so all of its configuration is handled through the file named Draco.exe.config in the bin directory of the installation path. There are several main elements in this config file: the configSections and startup elements (standard elements controlling which class will be invoked to read the Draco-specific element, and which version of the Runtime is required), the system.diagnostics element used to configure trace output to the file named draco.log at the root of the installation path, the system.runtime.remoting element used to configure remoting for use with the client tools (see the section below), and the draco element itself, which contains information about each build. The first two elements contain specific information necessary for the operation of Draco.NET, and you should not alter these.

As Draco.NET operates, it outputs trace messages relating to polling the source control, retrieving files, invoking builds, and e-mailing results. These trace messages are logged to a file in the root installation path called draco.log. The trace switch controlling this behavior is a standard TraceSwitch class, so the values correspond to the TraceLevel enumeration. By default, TraceLevelSwitch value is set to 4, meaning Verbose:

<system.diagnostics>
<switches>
<add name=”TraceLevelSwitch” value=”4” />
</switches>
<trace autoflush=”true” indentsize=”4”>
<listeners>
<add name=”Draco” 
type=
“Chive.Draco.Util.FileTraceListener, Draco”  />
<remove name=”Default”/> 
</listeners>
</trace>
</system.diagnostics>

This value is appropriate when you're getting used to how Draco.NET works. But you'll want to change this value to 1 once you take your app to production, so that only errors get logged to the file, and it doesn't grow too large.

The draco element contains all the information about each build, as well as some parameters to control how the service itself functions:

<draco xmlns=”http://www.chive.com/draco”>
<pollperiod>60</pollperiod>
<quietperiod>20</quietperiod>
<mailserver>localhost</mailserver>
<fromaddress>buildmanager@example.com
</fromaddress>

When Draco.NET is looking for code changes, it checks the source control at a regular interval, controlled by the pollperiod element. The default value of 60 means that it checks projects for changes once every minute. Once it detects a change, Draco.NET waits for the source control to be idle for a certain number of seconds (defined by the quietperiod element) before initiating a build. This is to make sure that a build doesn't start in the middle of a large check in. Finally, Draco.NET reports results through e-mail, so it uses the mailserver element to indicate the outgoing SMTP mail server, while the fromaddress indicates the e-mail address you want to send notifications from.

The builds element contains a list of all the projects that are watched and built by the service. Each build sub-element represents a project. Each build element has a unique name, can override the global settings related to the poll and quiet periods, and contains information about where notifications should be sent, which tool should be used to build the project, and where the project can be found under source control.

This partial listing of the build element illustrates how to override global parameters and configure notification:

<builds>
<build>
<name>DotProduct</name>
<pollperiod>30</pollperiod>
<notification>
<email>
<recipient>
rpierry+msdn@gmail.com</recipient>
</email>
<file>
<dir>C:\Builds\Output</dir>
</file>
</notification>

You can send notifications to an arbitrary list of e-mail addresses, as well as write them to a file in a configurable location.

Each build element contains one sub-element that defines how to build the project, and one sub-element to indicate which source control to use. Currently, Draco.NET supports the nant element for using NAnt, and the devenv element for compiling using Visual Studio.NET. The devenv element contains information about which solution file contains your project and which build configuration (Debug, Release, and so on) to use:

<devenv>
<solutionfile>DracoTest.sln</solutionfile>
<solutionconfig>Debug</solutionconfig>
</devenv>

Supplying the projectnameorfile element means that you can build a single project instead of the entire solution. These elements all correspond to command-line arguments to devenv.exe itself, the main executable for the Visual Studio.NET IDE. You can run “devenv.exe /?” from a Visual Studio.NET Command Prompt for further details on their usage.

Use the vss element to set up your project to use Visual SourceSafe for source control:

<vss>
<project>$/DracoTest/DracoTest</project>
<username>rpierry</username>
<password></password>
</vss>

This element contains all the expected information such as the path to your project in source control and a username and password to use to sign in to SourceSafe. If your SourceSafe database is on a different server (or in a non-standard location), you must provide an ssdir element that contains the path to srcsafe.ini. This tells Draco.NET know where to find the database.

Project artifacts such as specifications or documentation are sometimes stored under source control, so Draco.NET allows you to ignore changes made by a specific user, or that contain a specific comment. This means updating the documentation won't trigger a build:

<ignorechanges>
<ignore user=”documenter” />
<ignore comment=”documentation” />
</ignorechanges>

This code illustrates how to use a sample ignorechanges element to ignore changes either made by the user “documenter” or with the comment “documentation.”