about_Trap

Descrição curta

Descreve uma palavra-chave que lida com um erro de encerramento.

Descrição longa

Um erro de encerramento impede que uma instrução seja executada. Se o PowerShell não lidar com 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 outros idiomas, como C#, erros de encerramento são conhecidos como exceções.

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

• Exiba o erro após o processamento do bloco da instrução trap e continue a execução do script ou da função que contém o trap. Esse comportamento é o padrão.

  Nota

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

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

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

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

Sintaxe

A instrução trap tem a seguinte sintaxe:

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

A instrução trap inclui uma lista de instruções a serem executadas quando ocorrer um erro de encerramento. Uma instrução trap consiste na palavra-chave trap, opcionalmente seguida por uma expressão de tipo e o bloco de instrução que contém a lista de instruções a serem executadas quando um erro é interceptado. A expressão de tipo refina os tipos de erros que o trap captura.

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

Interceptação de todos os erros de encerramento

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

Este é um exemplo de uma instrução trap mínima:

trap { 'Error found.' }

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

No exemplo a seguir, a função inclui uma cadeia de caracteres sem sentido que causa um erro de runtime.

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

TrapTest

A execução dessa 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 ou $PSItem 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 scriptblock, mas sempre se aplicam a todas as instruções nesse scriptblock. Em runtime, as instruções trap em um bloco são definidas antes de qualquer outra instrução ser executada. Em outras linguagens, como JavaScript, isso é conhecido como içamento. Isso significa que trap instruções se aplicam a todas as instruções nesse bloco, mesmo que a execução não tenha avançado além do ponto em que estão definidas. Por exemplo, a definição de trap no final de um script e geração de um erro na primeira instrução ainda aciona trap.

Interceptando erros específicos

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

O exemplo a seguir é uma instrução trap que intercepta 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 instrução trap exibe a cadeia de caracteres Command error trapped. Depois de executar a lista de instruções trap, o PowerShell grava o objeto de erro no fluxo de erros 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. Essa instrução intercepta todos os erros gerados por comandos desconhecidos. Ele também captura 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 instrução trap em um script. Apenas uma instrução trap pode interceptar cada tipo de erro. Quando ocorre um erro de encerramento, o PowerShell pesquisa a trap correspondência com a mais específica, começando no bloco de scripts atual da execução.

O exemplo de script a seguir contém um erro. O script inclui uma instrução trap geral que intercepta qualquer erro de encerramento e uma instrução trap específica 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 trap específica intercepta esse erro de encerramento.

O exemplo de script a seguir contém as mesmas instruções trap 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 de CommandNotFoundException. A outra instrução trap, que captura qualquer erro de encerramento, captura o erro de divisão por zero.

Interceptando erros em um scriptblock

Por padrão, quando um erro de encerramento é gerado, a execução é transferida para a instrução trap. Depois que o bloco trap for executado, o controle retornará ao 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 que os loops continuam até a última iteração. Quando o script tenta dividir 1 por 0, o PowerShell gera um erro de encerramento. O script ignora o restante da foreach instrução, executa a try instrução e continua após a foreach instrução.

Erros de interceptação e escopo

Se ocorrer um erro de encerramento no mesmo scriptblock da 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 scriptblock diferente do erro, a execução continuará na próxima instrução que está no mesmo scriptblock que a trap instrução.

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

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 instrução trap na função intercepta o erro. Depois de exibir a mensagem, o PowerShell retoma a execução da função. Observe que Function1 concluiu após a instrução trap.

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

function function2 {
    NonsenseString
    'function2 was completed'
}

trap { 'An error:' }

function2

A execução da função Function2 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 comando function2 was completed não foi executado. Em ambos os exemplos, o erro de encerramento ocorre dentro da função. Neste exemplo, no entanto, a instrução trap está fora da função. O PowerShell não volta para a função após a execução da instrução trap.

Cuidado

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

No exemplo a seguir, apenas trap com whoops 1 é executado.

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

Importante

Uma instrução trap está restrita ao local onde é compilada. Se você tiver uma instrução trap dentro de uma função ou script dot sourced, quando a função ou script dot sourced sair, todas as instruções trap dentro dela serão removidas.

Uso das palavras-chave break e continue

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

Se você incluir uma instrução break em uma lista de instruções trap, o PowerShell interromperá a função ou o script. A seguinte função de exemplo usa a palavra-chave break em uma instrução 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.

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

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

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

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 é interceptado e a instrução End of function é executada. Nenhum erro é gravado no fluxo de erros.

Anotações

trap as instruções fornecem uma maneira de garantir que todos os erros de encerramento em um scriptblock sejam tratados. Para tratamento de erros mais refinados, use try/catch blocos em que as armadilhas são definidas usando catch instruções. As instruções catch se aplicam apenas ao código dentro da instrução try associada. Para obter mais informações, consulte about_Try_Catch_Finally.

Consulte também

• about_Break
• about_Continue
• about_Scopes
• about_Throw
• about_Try_Catch_Finally