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 es el comportamiento 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 trap instrucción que controle el error. Si existe una instrucción trap, PowerShell sigue ejecutando el script o comando en la instrucción trap.

El siguiente ejemplo es una declaración muy simple trap :

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 lo siguiente:

Error found.
nonsenseString:
Line |
   3 |      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.

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 try again.
nonsenseString:
Line |
   3 |      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.

Importante

trap Las instrucciones se pueden definir en cualquier lugar dentro de un ámbito determinado, pero siempre se aplican a todas las instrucciones de ese ámbito. 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 trap las sentencias 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, 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 trap instrucción 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 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 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 trap sola instrucción. Cuando se produce un error de terminación, PowerShell busca el trap 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 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 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.

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 específica trap .

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 |
   4 |  1/$null
     |  ~~~~~~~
     | Attempted to divide by zero.

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

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: untitled:Untitled-1:3:4
Line |
   3 |     1/$x
     |     ~~~~
     | Attempted to divide by zero.

after loop

En el resultado anterior, puede ver que los bucles continúan hasta la última iteración. Cuando el script intenta dividir 1 por 0, se produce un error de terminación. Se omite el resto del foreach bloque de scripts, se ejecuta la try instrucción y el script continúa después del bloque de foreach scripts.

Captura de errores y ámbito

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

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 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.
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:
NonsenseString:
Line |
   2 |      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.

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 trap instrucción.

Precaución

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

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

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

Importante

Una instrucción Trap se limita al 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 trap instrucción 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 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 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

trap Las instrucciones 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.

Consulte también

  • Last updated on