NAnt SDK Documentation - v0.92

TryCatchTask Class

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.

For a list of all members of this type, see TryCatchTask Members.

System.Object
   NAnt.Core.Element
      NAnt.Core.Task
         NAnt.Core.Tasks.TryCatchTask

[Visual Basic]
<TaskName(Name:="trycatch")>
Public Class TryCatchTask
    Inherits Task
[C#]
[TaskName(Name="trycatch")]
public class TryCatchTask : Task

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Remarks

The tasks defined in the <TryBlock> block will be executed in turn, as they normally would in a target.

If a <CatchBlock> block is defined, the tasks in that block will be executed in turn only if one of the tasks in the <TryBlock> block fails. This failure will then be suppressed by the <CatchBlock> block.

The message associated with the failure can also be caught in a property for use within the <CatchBlock> block. The original contents of the property will be restored upon exiting the <CatchBlock> block.

If a <FinallyBlock> block is defined, the tasks in that block will be executed after the tasks in both the <TryBlock> and <CatchBlock> blocks have been executed, regardless of whether any task fails in either block.

Example

    
<trycatch>
    <try>
        <echo message="In try" />
        <fail message="Failing!" />
    </try>
    <catch>
        <echo message="In catch" />
    </catch>
    <finally>
        <echo message="Finally done" />
    </finally>
</trycatch>
    
  

The output of this example will be:

In try
In catch
Finally done
  

The failure in the <TryBlock> block will not cause the build to fail.

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

The output of this example will be:

In try
Caught failure: Just because...
Finally done
Build failed: Bad catch
  

Like the above, the failure in the <TryBlock> block does not cause the build to fail. The failure in the <CatchBlock> block does, however. Note that the <FinallyBlock> block is executed even though the <CatchBlock> block failed.

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

The output of this example will be:

In try
Caught failure yet again
Build failed: Property 'failure' has not been set.
  

The EchoTask in the <FinallyBlock> block failed because the "failure" property was not defined after exiting the <CatchBlock> block. Note that the failure in the <FinallyBlock> block has eclipsed the failure in the <CatchBlock> block.

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

A more concrete example, that will always clean up the generated temporary file after it has been created.

Requirements

Namespace: NAnt.Core.Tasks

Assembly: NAnt.Core (in NAnt.Core.dll)

See Also

TryCatchTask Members | NAnt.Core.Tasks Namespace