<!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"> <!-- Documenting T:NAnt.Core.Tasks.TryCatchTask--> <head> <meta http-equiv="Content-Language" content="en-ca" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="../style.css" /> <title><trycatch> Task</title> </head> <body> <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar"> <tr> <td class="NavBar-Cell"> <a href="http://nant.sourceforge.net"> <b>NAnt</b> </a> <img alt="->" src="../images/arrow.gif" /> <a href="../index.html">Help</a> <img alt="->" src="../images/arrow.gif" /> <a href="../tasks/index.html">Task Reference</a> <img alt="->" src="../images/arrow.gif" /> <trycatch></td> <td class="NavBar-Cell" align="right"> v0.92</td> </tr> </table> <h1><trycatch></h1> <p> Executes a set of tasks, and optionally catches a build exception to allow recovery or rollback steps to be taken, or to define some steps to be taken regardless if the tasks succeed or fail, or both. </p> <p> The tasks defined in the <code><<code>try</code>></code> block will be executed in turn, as they normally would in a target. </p> <p> If a <code><<code>catch</code>></code> block is defined, the tasks in that block will be executed in turn only if one of the tasks in the <code><<code>try</code>></code> block fails. This failure will then be suppressed by the <code><<code>catch</code>></code> block. </p> <p> The message associated with the failure can also be caught in a property for use within the <code><<code>catch</code>></code> block. The original contents of the property will be restored upon exiting the <code><<code>catch</code>></code> block. </p> <p> If a <code><<code>finally</code>></code> block is defined, the tasks in that block will be executed after the tasks in both the <code><<code>try</code>></code> and <code><<code>catch</code>></code> blocks have been executed, regardless of whether any task fails in either block. </p> <h3>Parameters</h3> <div class="table"> <table> <tr> <th>Attribute</th> <th style="text-align: center;">Type</th> <th>Description</th> <th style="text-align: center;">Required</th> </tr> <tr> <td valign="top">failonerror</td> <td style="text-align: center;">bool</td> <td> Determines if task failure stops the build, or is just reported. The default is <b>true</b>. </td> <td style="text-align: center;">False</td> </tr> <tr> <td valign="top">if</td> <td style="text-align: center;">bool</td> <td> If <b>true</b> then the task will be executed; otherwise, skipped. The default is <b>true</b>. </td> <td style="text-align: center;">False</td> </tr> <tr> <td valign="top">unless</td> <td style="text-align: center;">bool</td> <td> Opposite of <code>if</code>. If <b>false</b> then the task will be executed; otherwise, skipped. The default is <b>false</b>. </td> <td style="text-align: center;">False</td> </tr> <tr> <td valign="top">verbose</td> <td style="text-align: center;">bool</td> <td> Determines whether the task should report detailed build log messages. The default is <b>false</b>. </td> <td style="text-align: center;">False</td> </tr> </table> </div> <h3>Nested Elements:</h3> <!--Element--> <h4> <a id="try"> </a> <try> </h4> <div class="nested-element"> The tasks in this block will be executed as a normal part of the build script. <p> Executes embedded tasks/elements in the order in which they are defined. </p><p /></div> <h4> <a id="try"> </a> </try> </h4> <!--Element--> <h4> <a id="catch"> </a> <catch> </h4> <div class="nested-element"> The tasks in this block will be executed if any task in the try block fails. <p></p><h3>Parameters</h3><div class="table"><table><tr><th>Attribute</th><th style="text-align: center;">Type</th><th>Description</th><th style="text-align: center;">Required</th></tr><tr><td valign="top">property</td><td style="text-align: center;">string</td><td> Defines the name of the property to save the message describing the failure that has been caught. </td><td style="text-align: center;">False</td></tr></table></div><p /></div> <h4> <a id="catch"> </a> </catch> </h4> <!--Element--> <h4> <a id="finally"> </a> <finally> </h4> <div class="nested-element"> The tasks in this block will always be executed, regardless of what happens in the try and catch blocks. <p> Executes embedded tasks/elements in the order in which they are defined. </p><p /></div> <h4> <a id="finally"> </a> </finally> </h4> <h3>Examples</h3> <ul class="examples"> <li> <pre class="code"> <trycatch> <try> <echo message="In try" /> <fail message="Failing!" /> </try> <catch> <echo message="In catch" /> </catch> <finally> <echo message="Finally done" /> </finally> </trycatch> </pre> <p> The output of this example will be: </p> <pre class="code">In try In catch Finally done </pre> <p> The failure in the <code><<code>try</code>></code> block will not cause the build to fail. </p> </li> <li> <pre class="code"> <trycatch> <try> <echo message="In try" /> <fail message="Just because..." /> </try> <catch property="failure"> <echo message="Caught failure: ${failure}" /> <fail message="Bad catch" /> </catch> <finally> <echo message="Finally done" /> </finally> </trycatch> </pre> <p> The output of this example will be: </p> <pre class="code">In try Caught failure: Just because... Finally done Build failed: Bad catch </pre> <p> Like the above, the failure in the <code><<code>try</code>></code> block does not cause the build to fail. The failure in the <code><<code>catch</code>></code> block does, however. Note that the <code><<code>finally</code>></code> block is executed even though the <code><<code>catch</code>></code> block failed. </p> </li> <li> <pre class="code"> <trycatch> <try> <echo message="In try" /> <fail message="yet again" /> </try> <catch property="failure"> <echo message="Caught failure ${failure}" /> <fail message="Bad catch" /> </catch> <finally> <echo message="Finally done ${failure}" /> </finally> </trycatch> </pre> <p> The output of this example will be: </p> <pre class="code">In try Caught failure yet again Build failed: Property 'failure' has not been set. </pre> <p> The <a href="../tasks/echo.html"><echo></a> task in the <code><<code>finally</code>></code> block failed because the "failure" property was not defined after exiting the <code><<code>catch</code>></code> block. Note that the failure in the <code><<code>finally</code>></code> block has eclipsed the failure in the <code><<code>catch</code>></code> block. </p> </li> <li> <pre class="code"> <trycatch> <try> <property name="temp.file" value="${path::get-temp-file-name()}" /> <do-stuff to="${temp.file}" /> <fail message="Oops..." /> </try> <finally> <echo message="Cleaning up..." /> <if test="${property::exists('temp.file')}"> <delete file="${temp.file}" /> </if> </finally> </trycatch> </pre> <p> A more concrete example, that will always clean up the generated temporary file after it has been created. </p> </li> </ul> <h3>Requirements</h3> <div style="margin-left: 20px;"> <b>Assembly:</b> NAnt.Core (0.92.4543.0) </div> </body> </html>