Compartir a través de

about_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 trap pueden controlar los errores de terminación de las maneras siguientes:

  • Muestra el error después de procesar el bloque de instrucciones trap y continuar con la ejecución del script o la función que contiene el trap. Este comportamiento es el valor predeterminado.

    Nota:

    Cuando el error de terminación se produce en un bloque de script subordinado, como una instrucción if o un bucle foreach, las instrucciones del bloque trap se ejecutan y la ejecución continúa en la siguiente instrucción fuera del bloque de script subordinado.

  • Muestra el error y anula la ejecución del script o la función que contiene el trap mediante break en la instrucción trap.

  • Silencia el error, pero continúa la ejecución del script o la función que contiene el trap mediante continue en la instrucción trap.

La lista de instrucciones del trap puede incluir varias condiciones o llamadas de función. Un trap puede escribir registros, condiciones de prueba o incluso ejecutar otro programa.

Sintaxis

La instrucción trap tiene la sintaxis siguiente:

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

La instrucción trap incluye una lista de instrucciones que se van a ejecutar cuando se produce un error de terminación. Una instrucción trap consta de la palabra clave trap, 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 captura un error. La expresión de tipo refina los tipos de errores que detecta el trap.

Un script o comando puede tener varias instrucciones trap. Las instrucciones trap pueden aparecer en cualquier lugar 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 controla el error. Si existe una instrucción trap, PowerShell sigue ejecutando el script o comando en la instrucción trap.

A continuación, se muestra un ejemplo de una instrucción trap mínima:

trap { 'Error found.' }

Esta instrucción trap captura 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 la siguiente salida:

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

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 la siguiente salida:

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
try again.
nonsenseString:
Line |
   3 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Importante

Las instrucciones trap se pueden definir en cualquier parte de cualquier bloque de script, pero siempre se aplican a todas las instrucciones en el mismo. Durante la ejecución, las instrucciones trap de un bloque se definen antes de ejecutar cualquier otra instrucción. En JavaScript, esto se conoce como elevación. Esto significa que las declaraciones trap se aplican a todas las declaraciones de ese bloque, incluso si la ejecución no ha avanzado más allá del punto en el que se definen. Por ejemplo, al definir un trap al final de un script y lanzar un error en la primera instrucción se sigue desencadenado ese trap.

Intercepción de errores específicos

Un script o comando puede tener varias instrucciones trap. Se puede definir un trap para controlar 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 Command error trapped. 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 tipos de excepción de .NET. 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 los errores generados por comandos desconocidos. También intercepta otros tipos de error.

Puede encontrar el tipo de excepción de un error inspeccionando el objeto de error. En el ejemplo siguiente se muestra cómo obtener el nombre completo de la excepción para el último error de una sesión:

nonsenseString
$Error[0].Exception.GetType().FullName

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

System.Management.Automation.CommandNotFoundException

Puede tener más de una instrucción trap en un script. Solo una instrucción trap puede interceptar cada tipo de error. Cuando se produce un error de terminación, PowerShell busca el trap con la coincidencia más específica, empezando por el bloque de ejecución del script 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 trap específica 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:
Line |
   5 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Dado que PowerShell no reconoce nonsenseString como cmdlet u otro elemento, devuelve un error CommandNotFoundException. La instrucción trap específica captura este error de terminación.

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
RuntimeException:
Line |
   5 |  1/$null
     |  ~~~~~~~
     | Attempted to divide by zero.

El intento de dividir por cero no crea un error CommandNotFoundException. La otra instrucción trap, que captura cualquier error de terminación, captura el error de división por cero.

Captura de errores en un bloque de script

De forma predeterminada, cuando se produce un error de terminación, la ejecución se transfiere a la instrucción trap. Una vez ejecutado el bloque trap, el control vuelve al siguiente bloque de instrucciones después de la ubicación del error.

Por ejemplo, cuando se produce un error de terminación en una instrucción foreach, la instrucción trap se ejecuta y la ejecución continúa en la siguiente instrucción después del bloque foreach, no dentro del bloque foreach.

trap { 'An error occurred!'}
foreach ($x in 3..0) {
   1/$x
   'after division'
}
'after loop'

0.333333333333333
after division
0.5
after division
1
after division
An error occurred!
RuntimeException:
Line |
   3 |     1/$x
     |     ~~~~
     | Attempted to divide by zero.
after loop

En la salida, puede ver que los bucles continúan hasta la última iteración. Cuando el script intenta dividir entre 1 y 0, PowerShell produce un error de terminación. El script omite el resto del bloque de script de foreach, ejecuta la sentencia try y continúa después del bloque de script de foreach.

Captura de errores y ámbito

Si se produce un error de terminación en el mismo bloque de script que la instrucción trap, PowerShell ejecuta la lista de instrucciones definidas por el trap. La ejecución continúa en la instrucción después del error. Si la instrucción trap está en un bloque de script diferente del error, la ejecución continúa en la siguiente instrucción que se encuentra en el mismo bloque de script 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 instrucción siguiente. El script siguiente contiene un error y una instrucción trap:

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

function1

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

An error:
NonsenseString:
Line |
   3 |      NonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'NonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.
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. Observe que Function1 se completó después de la instrucción trap.

Compare este comportamiento con el ejemplo siguiente, que tiene el mismo error e instrucción trap. 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:
NonsenseString:
Line |
   2 |      NonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'NonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

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 . Sin embargo, en este ejemplo, 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 usa la primera trap definida en el léxico (ubicada más arriba en el bloque de script).

En el ejemplo siguiente, solo se ejecuta el trap con whoops 1.

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

Importante

Una instrucción trap tiene como ámbito el lugar donde se compila. Si tiene una instrucción trap dentro de una función o script con uso del operador punto, cuando la función o el script con uso del operador punto sale, se quitan todas las instrucciones trap que contiene.

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

Puede usar las palabras clave break y continue en 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 instrucción break en una lista de instrucciones trap, PowerShell detiene la función o el script. La siguiente función de ejemplo usa la palabra clave break en una instrucción trap:

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

break_example

Error trapped
ParentContainsErrorRecordException:
Line |
   6 |      1/$null
     |      ~~~~~~~
     | Attempted to divide by zero.

Dado que la instrucción trap incluyó la palabra clave break, la función no continúa ejecutándose y no se ejecuta la línea Function completed.

Si incluye una palabra clave continue en una instrucción trap, PowerShell se reanuda después de la instrucción que provocó el error, como lo haría sin break o continue. Sin embargo, con la palabra clave continue, 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 intercepte el error y se ejecuta la instrucción Function completed. No se escribe ningún error en el flujo de errores.

Notas

Las instrucciones trap proporcionan una forma de garantizar que se gestionen todos los errores de terminación dentro de un bloque de script. 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.

Consulte también

  • Last updated on