about_Trap

  • Artigo

Breve descrição

Descreve uma palavra-chave que manipula um erro de encerramento.

Descrição longa

Um erro de encerramento interrompe a execução de uma instrução. Se o PowerShell não manipular um erro de encerramento de alguma forma, o PowerShell também interromperá a execução da função ou do script no pipeline atual. Em outras linguagens, como C#, os erros de terminação são conhecidos como exceções.

A trap palavra-chave especifica uma lista de instruções a serem executadas quando ocorre um erro de encerramento. trap As instruções podem lidar com os erros de encerramento das seguintes maneiras:

  • Exiba o erro depois de processar o trap bloco de instrução e continuar a execução do script ou função que contém o trap. Esse comportamento é o padrão.

    Nota

    Quando o erro de encerramento ocorre em um bloco de script subordinado, como uma if instrução ou foreach loop, as instruções no bloco são executadas e a trap execução continua na próxima instrução fora do bloco de script subordinado.

  • Exiba o erro e anule a execução do script ou função que contém o trap trap uso break na instrução.

  • Silencie o erro, mas continue a execução do script ou função que contém o trap usando continue na trap instrução.

A lista de instruções do trap pode incluir várias condições ou chamadas de função. A trap pode escrever logs, condições de teste ou até mesmo executar outro programa.

Sintaxe

A trap instrução tem a seguinte sintaxe:

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

A trap instrução inclui uma lista de instruções a serem executadas quando ocorre um erro de encerramento. Uma trap instrução consiste na trap palavra-chave, opcionalmente seguida por uma expressão de tipo, e no bloco de instrução contendo a lista de instruções a serem executadas quando um erro é intercetado. A expressão de tipo refina os tipos de erros capturados trap .

Um script ou comando pode ter várias trap instruções. trap instruções podem aparecer em qualquer lugar no script ou comando.

Intercetando todos os erros de terminação

Quando ocorre um erro de encerramento que não é tratado de outra forma em um script ou comando, o PowerShell verifica se há uma trap instrução que manipula o erro. Se uma trap instrução estiver presente, o PowerShell continuará executando o script ou comando trap na instrução.

O exemplo a seguir é uma instrução mínima trap :

trap { 'Error found.' }

Esta trap instrução interceta qualquer erro de encerramento.

No exemplo a seguir, a função inclui uma cadeia de caracteres nonsense que causa um erro de tempo de execução.

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

TrapTest

A execução desta função retorna a seguinte saída:

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.

O exemplo a seguir inclui uma trap instrução que exibe o erro usando a $_ variável automática:

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

TrapTest

A execução desta versão da função retorna a seguinte saída:

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 As instruções podem ser definidas em qualquer lugar dentro de um determinado bloco de script, mas sempre se aplicam a todas as instruções nesse bloco de script. No tempo de execução, trap as instruções em um bloco são definidas antes que quaisquer outras instruções sejam executadas. Em JavaScript, isso é conhecido como içamento. Isso significa que as instruções se aplicam a todas as instruções nesse bloco, mesmo que trap a execução não tenha avançado além do ponto em que estão definidas. Por exemplo, definir um trap no final de um script e lançar um erro na primeira instrução ainda aciona esse trap.

Intercetação de erros específicos

Um script ou comando pode ter várias trap instruções. A trap pode ser definido para lidar com erros específicos.

O exemplo a seguir é uma trap instrução que interceta o erro específico CommandNotFoundException:

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

Quando uma função ou script encontra uma cadeia de caracteres que não corresponde a um comando conhecido, essa trap instrução exibe a Command error trapped cadeia de caracteres. Depois de executar a lista de instruções, o trap PowerShell grava o objeto de erro no fluxo de erro e continua o script.

O PowerShell usa tipos de exceção .NET. O exemplo a seguir especifica o tipo de erro System.Exception :

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

O tipo de erro CommandNotFoundException herda do tipo System.Exception . Esta instrução interceta quaisquer erros gerados por comandos desconhecidos. Ele também interceta outros tipos de erro.

Você pode encontrar o tipo de exceção para um erro inspecionando o objeto de erro. O exemplo a seguir mostra como obter o nome completo da exceção para o último erro em uma sessão:

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

Você pode ter mais de uma trap instrução em um script. Apenas uma trap instrução pode intercetar cada tipo de erro. Quando ocorre um erro de encerramento, o PowerShell procura a trap correspondência mais específica, começando no bloco de execução de script atual.

O exemplo de script a seguir contém um erro. O script inclui uma instrução geral trap que interceta qualquer erro de terminação e uma instrução específica trap que especifica o tipo CommandNotFoundException .

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

A execução desse script produz o seguinte 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.

Como o PowerShell não reconhece nonsenseString como um cmdlet ou outro item, ele retorna um erro CommandNotFoundException . A instrução específica trap interceta esse erro de encerramento.

O exemplo de script a seguir contém as mesmas trap instruções com um erro diferente:

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

A execução desse script produz o seguinte resultado:

Other terminating error trapped
RuntimeException:
Line |
   5 |  1/$null
     |  ~~~~~~~
     | Attempted to divide by zero.

A tentativa de dividir por zero não cria um erro CommandNotFoundException . A outra trap instrução, que interceta qualquer erro de encerramento, interceta a divisão por erro zero.

Erros de intercetação em um bloco de script

Por padrão, quando um erro de encerramento é lançado, a execução é transferida para a instrução trap. Depois que o trap bloco é executado, o controle retorna para o próximo bloco de instrução após o local do erro.

Por exemplo, quando ocorre um erro de encerramento em uma foreach instrução, a instrução é executada e a trap execução continua na próxima instrução após o foreach bloco, não dentro do foreach bloco.

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

Na saída, você pode ver os loops continuarem até a última iteração. Quando o script tenta dividir 1 por 0, o PowerShell lança um erro de encerramento. O script ignora o foreach restante do bloco de script, executa a try instrução e continua após o foreach bloco de script.

Erros de trapping e escopo

Se ocorrer um erro de encerramento no mesmo bloco de script que a instrução, o trap PowerShell executará a lista de instruções definidas pelo trap. A execução continua na instrução após o erro. Se a trap instrução estiver em um bloco de script diferente do erro, a execução continuará na próxima instrução que está no mesmo bloco de script que a trap instrução.

Por exemplo, se ocorrer um erro em uma função e a trap instrução estiver na função, o script continuará na próxima instrução. O script a seguir contém um erro e uma trap instrução:

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

function1

A execução desse script produz o seguinte 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

A trap instrução na função interceta o erro. Depois de exibir a mensagem, o PowerShell retoma a execução da função. Observe que Function1 completou após a trap declaração.

Compare esse comportamento com o exemplo a seguir, que tem o mesmo erro e trap instrução. Neste exemplo, a trap instrução ocorre fora da função:

function function2 {
    NonsenseString
    'function2 was completed'
}

trap { 'An error:' }

function2

A execução da Function2 função produz o seguinte 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.

Neste exemplo, o function2 was completed comando não foi executado. Em ambos os exemplos, o erro de encerramento ocorre dentro da função. Neste exemplo, no entanto, a trap instrução está fora da função. O PowerShell não volta para a função depois que a trap instrução é executada.

Atenção

Quando várias armadilhas são definidas para a mesma condição de erro, a primeira trap definida lexicamente (mais alta no bloco de script) é usada.

No exemplo a seguir, apenas o trap com whoops 1 execuções.

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

Importante

Uma trap instrução tem como escopo o local onde ela é compilada. Se você tiver uma trap instrução dentro de uma função ou script de origem de ponto, quando a função ou script de origem de ponto for encerrada, todas as trap instruções dentro serão removidas.

Usando as palavras-chave break e continue

Você pode usar as break palavras-chave e continue em uma trap instrução para determinar se um script ou comando continua a ser executado após um erro de encerramento.

Se você incluir uma break instrução em uma lista de trap instruções, o PowerShell interromperá a função ou o script. A função de exemplo a seguir usa a break palavra-chave em uma trap instrução:

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.

Como a trap instrução incluiu a break palavra-chave, a função não continua a ser executada e a Function completed linha não é executada.

Se você incluir uma continue palavra-chave em uma trap instrução, o PowerShell será retomado após a instrução que causou o erro, assim como faria sem break ou continue. Com a palavra-chave, no entanto, o continue PowerShell não grava um erro no fluxo de erros.

A função de exemplo a seguir usa a continue palavra-chave em uma trap instrução:

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

A função é retomada depois que o erro é intercetado e a End of function instrução é executada. Nenhum erro é gravado no fluxo de erro.

Notas

trap fornecem uma maneira de garantir que todos os erros de encerramento dentro de um bloco de script sejam tratados. Para um tratamento de erros mais refinado, use try/catch blocos onde os traps são definidos usando catch instruções. As catch instruções só se aplicam ao código dentro da instrução associada try . Para obter mais informações, consulte about_Try_Catch_Finally.

Consulte também