NAntContrib Help Task Reference <trycatch> | v0.85-rc2 |
[This is preliminary documentation and subject to change.]
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.
The tasks defined in the <
block will be executed in turn, as they normally would in a target. try
>
If a <
block is defined, the tasks in that block will be executed in turn only if one of the tasks in the catch
><
block fails. This failure will then be suppressed by the try
><
block. catch
>
The message associated with the failure can also be caught in a property for use within the <
block. The original contents of the property will be restored upon exiting the catch
><
block. catch
>
If a <
block is defined, the tasks in that block will be executed after the tasks in both the finally
><
and try
><
blocks have been executed, regardless of whether any task fails in either block. catch
>
Attribute | Type | Description | Required |
---|---|---|---|
failonerror | bool | Determines if task failure stops the build, or is just reported. The default is true. | False |
if | bool | If true then the task will be executed; otherwise, skipped. The default is true. | False |
unless | bool | Opposite of if . If false then the task will be executed; otherwise, skipped. The default is false. |
False |
verbose | bool | Determines whether the task should report detailed build log messages. The default is false. | False |
Executes embedded tasks in the order in which they are defined.
Attribute | Type | Description | Required |
---|---|---|---|
failonerror | bool | Determines if task failure stops the build, or is just reported. The default is true. | False |
if | bool | If true then the task will be executed; otherwise, skipped. The default is true. | False |
unless | bool | Opposite of if . If false then the task will be executed; otherwise, skipped. The default is false. | False |
verbose | bool | Determines whether the task should report detailed build log messages. The default is false. | False |
Attribute | Type | Description | Required |
---|---|---|---|
property | string | Defines the name of the property to save the message describing the failure that has been caught. | False |
failonerror | bool | Determines if task failure stops the build, or is just reported. The default is true. | False |
if | bool | If true then the task will be executed; otherwise, skipped. The default is true. | False |
unless | bool | Opposite of if . If false then the task will be executed; otherwise, skipped. The default is false. | False |
verbose | bool | Determines whether the task should report detailed build log messages. The default is false. | False |
Executes embedded tasks in the order in which they are defined.
Attribute | Type | Description | Required |
---|---|---|---|
failonerror | bool | Determines if task failure stops the build, or is just reported. The default is true. | False |
if | bool | If true then the task will be executed; otherwise, skipped. The default is true. | False |
unless | bool | Opposite of if . If false then the task will be executed; otherwise, skipped. The default is false. | False |
verbose | bool | Determines whether the task should report detailed build log messages. The default is false. | False |
<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 <
block will not cause the build to fail. try
>
<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 <
block does not cause the build to fail. The failure in the try
><
block does, however. Note that the catch
><
block is executed even though the finally
><
block failed. catch
>
<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 <echo> task in the <
block failed because the "failure" property was not defined after exiting the finally
><
block. Note that the failure in the catch
><
block has eclipsed the failure in the finally
><
block. catch
>
<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.