<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>NAnt - Loggers & Listeners</title>
<meta http-equiv="Content-Language" content="en-ca" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="Loggers & Listeners" />
<link rel="stylesheet" type="text/css" href="../style.css" />
<style type="text/css">
.xmlelement {
color: #660000;
}
.xmlattribute {
color: red;
}
.xmltext {
color: blue;
}
.xmlcomment {
color: green;
}
.xmlcdata {
color: #FF00CC;
}
</style>
</head>
<body>
<table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
<tr>
<td class="NavBar-Cell">
<a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="->" width="13" height="9" />
<a href="../index.html">Help</a> <img alt="->" src="../images/arrow.gif"/> <a href="index.html">
Fundamentals</a> <img height="9" alt="->" src="../images/arrow.gif" width="13" />
Loggers & Listeners
</td>
<td class="NavBar-Cell" align="right">
v0.92
</td>
</tr>
</table>
<h1>Loggers & Listeners</h1>
<h2>Overview</h2>
<p>
NAnt has two related features to allow the build process to be monitored:
listeners and loggers.
</p>
<h3>Listeners</h3>
<p>
A listener is alerted of the following events:
</p>
<ul>
<li>
build started
</li>
<li>
build finished
</li>
<li>
target started
</li>
<li>
target finished
</li>
<li>
task started
</li>
<li>
task finished
</li>
<li>
message logged</li>
</ul>
<h3>Loggers</h3>
<p>
Loggers extend the capabilities of listeners and add the following features:
</p>
<ul>
<li>
Receives a handle to the standard output and error print streams and therefore
can log information to the console or the <code>-logfile</code>
specified file.
</li>
<li>
Logging level (<code>-quiet</code>, <code>-verbose</code>, <code>-debug</code>)
aware.
</li>
<li>
Emacs-mode aware. This still needs to be implemented.
</li>
</ul>
<h2>Built-in Listeners/Loggers</h2>
<div class="table">
<table>
<colgroup>
<col />
<col />
<col style="TEXT-ALIGN: center" />
</colgroup>
<tbody>
<tr>
<th>
Class</th>
<th>
Description</th>
<th>
Type</th>
</tr>
<tr>
<td><a href="#DefaultLogger">NAnt.Core.DefaultLogger</a></td>
<td>
The logger used implicitly unless overridden with the <code>-logger</code> command-line
switch.
</td>
<td>IBuildLogger</td>
</tr>
<tr>
<td><a href="#MailLogger">NAnt.Core.MailLogger</a></td>
<td>
Extends <a href="#DefaultLogger">DefaultLogger</a> such that output is still
generated the same, and when the build is finished an e-mail can be sent.
</td>
<td>IBuildLogger</td>
</tr>
<tr>
<td><a href="#XmlLogger">NAnt.Core.XmlLogger</a></td>
<td>
Generates output in XML format.
</td>
<td>IBuildLogger</td>
</tr>
</tbody>
</table>
</div>
<h3><a id="DefaultLogger" />DefaultLogger</h3>
<p>Simply run NAnt normally, or:</p>
<blockquote>
<p><code>NAnt.exe -logger:NAnt.Core.DefaultLogger</code></p>
</blockquote>
<h3><a id="MailLogger" />MailLogger</h3>
<p>
The MailLogger captures all output logged through DefaultLogger (standard NAnt
output) and will send success and failure messages to unique e-mail lists, with
control for turning off success or failure messages individually.
</p>
<p>Properties controlling the operation of MailLogger are:</p>
<div class="table">
<table>
<colgroup>
<col />
<col />
<col />
</colgroup>
<tbody>
<tr>
<th>
Property</th>
<th>
Description</th>
<th>
Required</th>
</tr>
<tr>
<td>MailLogger.mailhost</td>
<td>The SMTP server to use.</td>
<td>No, default is "localhost"</td>
</tr>
<tr>
<td>MailLogger.from</td>
<td>The address of the e-mail sender.</td>
<td>Yes, if mail needs to be sent.</td>
</tr>
<tr>
<td>MailLogger.failure.notify</td>
<td>Send build failure e-mails ?</td>
<td>No, default is "true".</td>
</tr>
<tr>
<td>MailLogger.success.notify</td>
<td>Send build success e-mails ?</td>
<td>No, default is "true".</td>
</tr>
<tr>
<td>MailLogger.failure.to</td>
<td>The address to send build failure messages to.</td>
<td>Yes, if failure mail is to be sent.</td>
</tr>
<tr>
<td>MailLogger.success.to</td>
<td>The address to send build success messages to.</td>
<td>Yes, if success mail is to be sent.</td>
</tr>
<tr>
<td>MailLogger.failure.subject</td>
<td>The subject of build failure messages.</td>
<td>No, default is "Build Failure".</td>
</tr>
<tr>
<td>MailLogger.success.subject</td>
<td>The subject of build success messages.</td>
<td>No, default is "Build Success".</td>
</tr>
<tr>
<td>MailLogger.failure.attachments</td>
<td>The ID of a fileset representing a set of files to attach when the build fails.</td>
<td>No.</td>
</tr>
<tr>
<td>MailLogger.success.attachments</td>
<td>The ID of a fileset representing a set of files to attach when the build is successful.</td>
<td>No.</td>
</tr>
<tr>
<td>MailLogger.body.encoding</td>
<td>The encoding type of the body of the e-mail message.</td>
<td>No, default is system's ANSI code page.</td>
</tr>
<tr>
<td>MailLogger.smtp.username<sup>1</sup></td>
<td>The name of the user to login to the SMTP server.</td>
<td>No.</td>
</tr>
<tr>
<td>MailLogger.smtp.password<sup>1</sup></td>
<td>The password of the specified user.</td>
<td>No.</td>
</tr>
<tr>
<td>MailLogger.smtp.enablessl<sup>1</sup></td>
<td>Specifies whether to use SSL to encrypt the connection.</td>
<td>No, default is "false".</td>
</tr>
<tr>
<td>MailLogger.smtp.port<sup>1</sup></td>
<td>The SMTP server port to connect to.</td>
<td>No, default is "25".</td>
</tr>
</tbody>
</table>
<p><sup>1</sup> Only available when NAnt is built targeting .NET Framework 1.1 (or equivalent) or higher.</p>
</div>
<p>Usage:</p>
<blockquote>
<p><code>NAnt.exe -logger:NAnt.Core.MailLogger</code></p>
</blockquote>
<p>Example:</p>
<pre class="code">
<span class="xmltext"><</span><span class="xmlelement">project</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger Test"</span> <span class="xmlattribute">default</span><span class="xmltext">="build"></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.mailhost"</span> <span class="xmlattribute">value</span><span class="xmltext">="smtp.wherever.be" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.from"</span> <span class="xmlattribute">value</span><span class="xmltext">="me@telenet.be" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.notify"</span> <span class="xmlattribute">value</span><span class="xmltext">="true" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.notify"</span> <span class="xmlattribute">value</span><span class="xmltext">="true" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.to"</span> <span class="xmlattribute">value</span><span class="xmltext">="support@home.be" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.to"</span> <span class="xmlattribute">value</span><span class="xmltext">="support@home.be" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.subject"</span> <span class="xmlattribute">value</span><span class="xmltext">="Nightly build failure !" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.subject"</span> <span class="xmlattribute">value</span><span class="xmltext">="Nightly build successful" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.attachments"</span> <span class="xmlattribute">value</span><span class="xmltext">="MailLogger.failure.files" /></span>
<span class="xmltext"><</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.attachments"</span> <span class="xmlattribute">value</span><span class="xmltext">="MailLogger.success.files" /></span>
<span class="xmlcomment"><!-- set of files to attach when build fails --></span>
<span class="xmltext"><</span><span class="xmlelement">fileset</span> <span class="xmlattribute">id</span><span class="xmltext">="MailLogger.failure.files"></span>
<span class="xmltext"><</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="dump.log" /></span>
<span class="xmltext"><</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="trace.txt" /></span>
<span class="xmltext"></</span><span class="xmlelement">fileset</span><span class="xmltext">></span>
<span class="xmlcomment"><!-- set of files to attach when build is successful --></span>
<span class="xmltext"><</span><span class="xmlelement">fileset</span> <span class="xmlattribute">id</span><span class="xmltext">="MailLogger.success.files"></span>
<span class="xmltext"><</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="trace.txt" /></span>
<span class="xmltext"></</span><span class="xmlelement">fileset</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">target</span> <span class="xmlattribute">name</span><span class="xmltext">="build"></span>
<span class="xmltext"><</span><span class="xmlelement">echo</span> <span class="xmlattribute">message</span><span class="xmltext">="Starting build" /></span>
....
<span class="xmltext"><</span><span class="xmlelement">echo</span> <span class="xmlattribute">message</span><span class="xmltext">="Finished build" /></span>
<span class="xmltext"></</span><span class="xmlelement">target</span><span class="xmltext">></span>
<span class="xmltext"></</span><span class="xmlelement">project</span><span class="xmltext">></span>
</pre>
<h3><a id="XmlLogger" />XmlLogger</h3>
<p>
Writes all build information out to an XML file named <code>log.xml</code>, or
the value of the <code>XmlLogger.file</code> property if present, when used as
a listener. When used as a logger, it writes all output to either the console
or to the value of <code>-logfile</code>.
</p>
<p>
Whether used as a listener or logger, the output is not generated until the
build is complete.
</p>
<p>Usage:</p>
<blockquote>
<p>
<code>NAnt.exe -listener:NAnt.Core.XmlLogger</code><br />
<code>NAnt.exe -logger:NAnt.Core.XmlLogger -logfile:buildlog.xml</code>
</p>
</blockquote>
<p>Example:</p>
<pre class="code">
<span class="xmltext"><</span><span class="xmlelement">buildresults</span> <span class="xmlattribute">project</span><span class="xmltext">="test"></span>
<span class="xmltext"><</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"><![</span><span class="xmlcdata">CDATA[Buildfile: file:///D:/nant-test/xmlpeek/default.build]]</span><span class="xmltext">></</span><span class="xmlelement">message</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"><![</span><span class="xmlcdata">CDATA[Target framework: Microsoft .NET Framework 1.1]]</span><span class="xmltext">></</span><span class="xmlelement">message</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"><![</span><span class="xmlcdata">CDATA[Target<span class="xmltext">(</span>s<span class="xmltext">)</span> specified: build]]</span><span class="xmltext">></</span><span class="xmlelement">message</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">target</span> <span class="xmlattribute">name</span><span class="xmltext">="build"></span>
<span class="xmltext"><</span><span class="xmlelement">task</span> <span class="xmlattribute">name</span><span class="xmltext">="xmlpeek"></span>
<span class="xmltext"><</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"><![</span><span class="xmlcdata">CDATA[Peeking at <span class="xmltext">'D:\nant-test\xmlpeek\input.xml'</span> with XPath expression <span class="xmltext">'x:parameters/x:param'</span>.]]</span><span class="xmltext">></</span><span class="xmlelement">message</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"><![</span><span class="xmlcdata">CDATA[Found <span class="xmltext">'1'</span> nodes with the XPath expression <span class="xmltext">'x:parameters/x:param'</span>.]]</span><span class="xmltext">></</span><span class="xmlelement">message</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">duration</span><span class="xmltext">></span><span style="color: black;">15.625</span><span class="xmltext"></</span><span class="xmlelement">duration</span><span class="xmltext">></span>
<span class="xmltext"></</span><span class="xmlelement">task</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">duration</span><span class="xmltext">></span><span style="color: black;">15.625</span><span class="xmltext"></</span><span class="xmlelement">duration</span><span class="xmltext">></span>
<span class="xmltext"></</span><span class="xmlelement">target</span><span class="xmltext">></span>
<span class="xmltext"><</span><span class="xmlelement">duration</span><span class="xmltext">></span><span style="color: black;">31.25</span><span class="xmltext"></</span><span class="xmlelement">duration</span><span class="xmltext">></span>
<span class="xmltext"></</span><span class="xmlelement">buildresults</span><span class="xmltext">></span>
</pre>
</body>
</html>
