# <trycatch>

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 `<`try`>` block will be executed in turn, as they normally would in a target.

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

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

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

### Parameters

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

### Nested Elements:

#### <try>

The tasks in this block will be executed as a normal part of the build script.

Executes embedded tasks in the order in which they are defined.

### Parameters

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

#### </try>

#### <catch>

The tasks in this block will be executed if any task in the try block fails.

### Parameters

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

#### </catch>

#### <finally>

The tasks in this block will always be executed, regardless of what happens in the try and catch blocks.

Executes embedded tasks in the order in which they are defined.

### Parameters

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

#### </finally>

### Examples

-     <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 `<`try`>` 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 `<`try`>` block does not cause the build to fail. The failure in the `<`catch`>` block does, however. Note that the `<`finally`>` block is executed even though the `<`catch`>` 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 <echo> task in the `<`finally`>` block failed because the "failure" property was not defined after exiting the `<`catch`>` block. Note that the failure in the `<`finally`>` block has eclipsed the failure in the `<`catch`>` 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

Assembly: NAnt.Contrib.Tasks (0.91.4312.0)