Acerca de Trap

Descripción breve

Describe una palabra clave que controla un error de terminación.

Descripción larga

Un error de terminación impide que se ejecute una instrucción. Si PowerShell no controla un error de terminación de alguna manera, PowerShell también deja de ejecutar la función o el script en la canalización actual. En otros lenguajes, como C#, los errores de terminación se conocen como excepciones.

La palabra clave Trap especifica una lista de instrucciones que se van a ejecutar cuando se produce un error de terminación. Las instrucciones de captura controlan los errores de terminación y permiten que la ejecución del script o la función continúe en lugar de detenerse.

Las instrucciones de captura también pueden ser más complejas. La lista de instrucciones de la trampa puede incluir varias condiciones o llamadas a funciones. Una trampa puede escribir registros, probar condiciones o incluso ejecutar otro programa.

Sintaxis

La instrucción Trap tiene la siguiente sintaxis:

trap [[<error type>]] {<statement list>}

La instrucción Trap incluye una lista de instrucciones que se deben ejecutar cuando se produce un error de terminación. Una instrucción Trap consta de la trap palabra clave, opcionalmente seguida de una expresión de tipo, y el bloque de instrucciones que contiene la lista de instrucciones que se van a ejecutar cuando se atrapa un error. La expresión de tipo refina los tipos de errores que detecta la trampa.

Un script o comando puede tener varias instrucciones Trap. Las instrucciones de captura pueden aparecer en cualquier parte del script o comando.

Capturando todos los errores de terminación

Cuando se produce un error de terminación que no se controla de otra manera en un script o comando, PowerShell comprueba si hay una instrucción Trap que controle el error. Si hay una instrucción Trap, PowerShell continúa ejecutando el script o el comando en la instrucción Trap.

El siguiente ejemplo es una instrucción Trap muy sencilla:

trap {"Error found."}

Esta instrucción Trap intercepta cualquier error de terminación.

En el ejemplo siguiente, la función incluye una cadena sin sentido que provoca un error en tiempo de ejecución.

function TrapTest {
    trap {"Error found."}
    nonsenseString
}

TrapTest

Al ejecutar esta función, se devuelve lo siguiente:

Error found.

En el ejemplo siguiente se incluye una instrucción Trap que muestra el error mediante la $_ variable automática:

function TrapTest {
    trap {"Error found: $_"}
    nonsenseString
}

TrapTest

Al ejecutar esta versión de la función, se devuelve lo siguiente:

Error found: The term 'nonsenseString' is not recognized as the name of a
cmdlet, function, script file, or operable program. Check the spelling of the
name, or if a path was included verify that the path is correct, and then try
again.

Importante

Las instrucciones de captura se pueden definir en cualquier lugar dentro de un ámbito determinado, pero siempre se aplican a todas las instrucciones de ese ámbito. En tiempo de ejecución, las trampas de un bloque se definen antes de que se ejecuten otras instrucciones. En JavaScript, esto se conoce como elevación. Esto significa que las trampas se aplican a todas las sentencias de ese bloque, incluso si la ejecución no ha avanzado más allá del punto en el que están definidas. Por ejemplo, si se define una trampa al final de un script y se produce un error en la primera instrucción, se activa esa trampa.

Intercepción de errores específicos

Un script o comando puede tener varias instrucciones Trap. Las trampas se pueden definir para manejar errores específicos.

El ejemplo siguiente es una instrucción Trap que intercepta el error específico CommandNotFoundException:

trap [System.Management.Automation.CommandNotFoundException]
    {"Command error trapped"}

Cuando una función o script encuentra una cadena que no coincide con un comando conocido, esta instrucción Trap muestra la cadena "Error de comando atrapado". Después de ejecutar la lista de instrucciones Trap, PowerShell escribe el objeto de error en la secuencia de errores y, a continuación, continúa el script.

PowerShell usa los tipos de excepción de Microsoft .NET Framework. En el ejemplo siguiente se especifica el tipo de error System.Exception:

trap [System.Exception] {"An error trapped"}

El tipo de error CommandNotFoundException se hereda del tipo System.Exception. Esta instrucción intercepta un error creado por un comando desconocido. También intercepta otros tipos de error.

Puede tener más de una instrucción Trap en un script. Cada tipo de error puede ser atrapado por una sola instrucción Trap. Cuando se produce un error de terminación, PowerShell busca la trampa con la coincidencia más específica, empezando por el ámbito de ejecución actual.

El siguiente ejemplo de script contiene un error. El script incluye una instrucción Trap general que intercepta cualquier error de terminación y una instrucción específica Trap que especifica el tipo CommandNotFoundException .

trap {"Other terminating error trapped" }
trap [System.Management.Automation.CommandNotFoundException] {
  "Command error trapped"
}
nonsenseString

La ejecución de este script genera el siguiente resultado:

Command error trapped
nonsenseString : The term 'nonsenseString' is not recognized as the name of a
cmdlet, function, script file, or operable program. Check the spelling of the
name, or if a path was included, verify that the path is correct and try again.
At C:\temp\test\traptest.ps1:5 char:1
+ nonsenseString
+ ~~~~~~~~~~~~~~
+ CategoryInfo          : ObjectNotFound: (nonsenseString:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException

Dado que PowerShell no reconoce "nonsenseString" como un cmdlet u otro elemento, devuelve un error CommandNotFoundException . Este error de terminación es atrapado por la instrucción Trap específica.

El siguiente ejemplo de script contiene las mismas instrucciones Trap con un error diferente:

trap {"Other terminating error trapped" }
trap [System.Management.Automation.CommandNotFoundException]
    {"Command error trapped"}
1/$null

La ejecución de este script genera el siguiente resultado:

Other terminating error trapped
Attempted to divide by zero.
At C:\temp\test\traptest.ps1:5 char:1
+ 1/$null
+ ~~~~~~~
+ CategoryInfo          : NotSpecified: (:) [], RuntimeException
+ FullyQualifiedErrorId : RuntimeException

El intento de dividir por cero no crea un error CommandNotFoundException . En su lugar, ese error es atrapado por la otra instrucción Trap, que atrapa cualquier error de terminación.

Captura de errores y ámbito

Si se produce un error de terminación en el mismo ámbito que la instrucción Trap, PowerShell ejecuta la lista de instrucciones definidas por la captura. La ejecución continúa en la instrucción después del error. Si la instrucción Trap se encuentra en un ámbito diferente al del error, la ejecución continúa en la siguiente instrucción que se encuentra en el mismo ámbito que la instrucción Trap.

Por ejemplo, si se produce un error en una función y la instrucción Trap está en la función, el script continúa en la siguiente instrucción. El siguiente script contiene un error y una instrucción trap:

function function1 {
    trap { "An error: " }
    NonsenseString
    "function1 was completed"
    }

Más adelante en el script, la ejecución de la función Function1 produce el siguiente resultado:

function1
An error:
The term 'NonsenseString' is not recognized as the name of a cmdlet,
function, script file, or operable program. Check the spelling of the
name, or if a path was included verify that the path is correct, and
then try again.
At C:\PS>TestScript1.ps1:3 char:19
+     NonsenseString <<<<

function1 was completed

La instrucción Trap de la función intercepta el error. Después de mostrar el mensaje, PowerShell reanuda la ejecución de la función. Tenga en cuenta que Function1 se completó.

Compare esto con el siguiente ejemplo, que tiene el mismo error y Trap la misma instrucción. En este ejemplo, la instrucción trap se produce fuera de la función:

function function2 {
    NonsenseString
    "function2 was completed"
    }

trap { "An error: " }

function2

La ejecución de la función Function2 genera el siguiente resultado:

An error:
The term 'NonsenseString' is not recognized as the name of a cmdlet,
function, script file, or operable program. Check the spelling of the
name, or if a path was included verify that the path is correct, and
then try again.
At C:\PS>TestScript2.ps1:4 char:19
+     NonsenseString <<<<

En este ejemplo, no se ejecutó el comando "function2 was completed". En ambos ejemplos, el error de terminación se produce dentro de la función . En este ejemplo, sin embargo, la instrucción Trap está fuera de la función. PowerShell no vuelve a la función después de que se ejecute la instrucción Trap.

Precaución

Cuando se definen varias trampas para la misma condición de error, se utiliza la primera trampa definida léxicamente (la más alta en el ámbito).

En el siguiente ejemplo, solo se ejecuta la trampa con "whoops 1".

Remove-Item -ErrorAction Stop ThisFileDoesNotExist
trap { "whoops 1"; continue }
trap { "whoops 2"; continue }

Uso de las `break` palabras clave y `continue`

Puede utilizar las Break palabras clave and Continue de una instrucción Trap para determinar si un script o comando continúa ejecutándose después de un error de terminación.

Si incluye una Break instrucción en una lista de instrucciones Trap, PowerShell detiene la función o el script. La siguiente función de ejemplo utiliza la Break palabra clave en una instrucción Trap:

function break_example {
    trap {
        "Error trapped"
        break
    }
    1/$null
    "Function completed."
}

break_example

Error trapped
Attempted to divide by zero.
At line:4 char:7

Dado que la instrucción Trap incluía la Break palabra clave, la función no continúa ejecutándose y la línea "Función completada" no se ejecuta.

Si incluye una Continue instrucción en una instrucción Trap, PowerShell se reanuda después de la instrucción que causó el error, tal como lo haría sin Break o Continue. Sin embargo, con la Continue palabra clave, PowerShell no escribe un error en la secuencia de errores.

La siguiente función de ejemplo usa la palabra clave Continue en una instrucción Trap:

function continue_example {
    trap {
        "Error trapped"
        continue
    }
    1/$null
    "Function completed."
}

continue_example

Error trapped
Function completed.

La función se reanuda después de que se atrapa el error y se ejecuta la instrucción "Función completada". No se escribe ningún error en el flujo de errores.

Notas

Las instrucciones de captura proporcionan una manera sencilla de garantizar ampliamente que se controlan todos los errores de terminación dentro de un ámbito. Para un control de errores más detallado y preciso, use los bloques try/catch donde se definen trampas mediante declaraciones Catch. Las instrucciones Catch solo se aplican al código dentro de la instrucción Try asociada. Para obtener más información, consulte about_Try_Catch_Finally.