Compartir a través de

about_Trap

  • Artículo

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 trap palabra clave especifica una lista de instrucciones que se ejecutarán cuando se produce un error de terminación. trap Las instrucciones pueden controlar los errores de terminación de las maneras siguientes:

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

    Nota:

    Cuando el error de terminación se produce en un bloque de script subordinado, como una if instrucción o foreach bucle, las instrucciones del trap bloque 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 uso break en la trap instrucción .

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

La lista de instrucciones de 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 utiliza la sintaxis siguiente:

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

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

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

Captura de 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 controla el error. Si hay una trap instrucción presente, PowerShell sigue ejecutando el script o el comando en la trap instrucción .

El ejemplo siguiente es una instrucción mínima trap :

trap { 'Error found.' }

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

trap Las instrucciones se pueden definir en cualquier lugar dentro de un bloque de script determinado, pero siempre se aplican a todas las instrucciones de ese bloque de script. En tiempo de ejecución, trap las instrucciones de un bloque se definen antes de que se ejecuten otras instrucciones. En JavaScript, esto se conoce como elevación. Esto significa que trap las instrucciones se aplican a todas las instrucciones de ese bloque incluso si la ejecución no ha avanzado más allá del punto en el que se definen. Por ejemplo, definir un trap al final de un script y producir un error en la primera instrucción todavía desencadena que trap.

Captura de errores específicos

Un script o comando puede tener varias trap instrucciones. trap se puede definir para controlar errores específicos.

El ejemplo siguiente es una trap instrucción 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 Command error trapped cadena. Después de ejecutar la trap lista de instrucciones, 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 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 trap instrucción en un script. Solo una trap instrucción puede interceptar cada tipo de error. Cuando se produce un error de terminación, PowerShell busca con trap la coincidencia más específica, comenzando en el bloque de ejecución de script actual.

El siguiente ejemplo de script contiene un error. El script incluye una instrucción general trap 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:
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 un cmdlet u otro elemento, devuelve un error CommandNotFoundException . La instrucción específica trap intercepta este error de terminación.

El siguiente ejemplo de script contiene las mismas trap instrucciones 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 trap instrucción, que intercepta cualquier error de terminación, intercepta la división por cero error.

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 trap bloque, 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 foreach instrucción , la instrucción se ejecuta y la trap ejecución continúa en la siguiente instrucción después del foreach bloque, no dentro del foreach bloque.

trap { 'An error occurred!'}
foreach ($x in 3..-1) {
       "1/$x = "
       "`t$(1/$x)"
}
'after loop'

1/3 =
        0.333333333333333
1/2 =
        0.5
1/1 =
        1
1/0 =
An error occurred!
RuntimeException:
Line |
   4 |         "`t$(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 foreach scripts, ejecuta la try instrucción y continúa después del bloque de foreach script.

Captura de errores y ámbito

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

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

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

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

function function2 {
    NonsenseString
    'function2 was completed'
}

trap { 'An error:' }

function2

La ejecución de la Function2 función 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, el function2 was completed comando no se ejecutó. En ambos ejemplos, el error de terminación se produce dentro de la función . Sin embargo, en este ejemplo, la trap instrucción está fuera de la función . PowerShell no vuelve a la función una vez que se ejecuta la trap instrucción .

Precaución

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

En el ejemplo siguiente, solo con trap whoops 1 ejecuciones.

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

Importante

Una trap instrucción tiene como ámbito dónde se compila. Si tiene una trap instrucción dentro de una función o script de origen de puntos, cuando se cierra la función o el script de origen de puntos, se quitan todas las trap instrucciones dentro.

Uso de las palabras clave break y continue

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

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 incluyó la break palabra clave , la función no continúa ejecutándose y la Function completed línea no se ejecuta.

Si incluye una continue palabra clave en una trap instrucción , 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 continue palabra clave en una trap instrucción :

function ContinueExample {
    trap {
        'Error trapped'
        continue
    }
    foreach ($x in 3..-1) {
       "1/$x = "
       "`t$(1/$x)"
    }
    'End of function'
}

ContinueExample

1/3 =
        0.333333333333333
1/2 =
        0.5
1/1 =
        1
1/0 =
Error trapped
End of function

La función se reanuda después de que se intercepte el error y se ejecuta la End of function instrucción . No se escribe ningún error en la secuencia de errores.

Notas

trap Las instrucciones proporcionan una manera de asegurarse de que se controlan todos los errores de terminación dentro de un bloque de script. Para un control de errores más preciso, use try/catch bloques en los que se definen capturas mediante catch instrucciones . Las catch instrucciones solo se aplican al código dentro de la instrucción asociada try . Para obtener más información, consulte about_Try_Catch_Finally.

Consulte también