about_Trap
Descrição breve
Descreve uma palavra-chave que manipula um erro de encerramento.
Descrição longa
Um erro de encerramento impede a execução de uma instrução. Se o PowerShell não tratar 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#, erros de encerramento são conhecidos como exceções.
O trap
palavra-chave especifica uma lista de instruções a serem executadas quando ocorrer 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 otrap
. Esse é o comportamento padrão.Observação
Quando o erro de encerramento ocorre em um bloco de script subordinado, como uma instrução
if
ouforeach
um loop, as instruções notrap
bloco são executadas e a 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
usandobreak
natrap
instrução .Silencie o erro, mas continue a execução do script ou da função que contém o
trap
usandocontinue
na instruçãotrap
.
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.
Syntax
A instrução trap
utiliza esta sintaxe:
trap [[<error type>]] {<statement list>}
A trap
instrução inclui uma lista de instruções a serem executadas quando ocorrer um erro de encerramento. Uma trap
instrução consiste no trap
palavra-chave, opcionalmente seguido 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 a trap
captura.
Um script ou comando pode ter várias trap
instruções. trap
as instruções podem aparecer em qualquer lugar no script ou no comando.
Interceptando 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 se há uma trap
instrução que manipula o erro. Se uma trap
instrução estiver presente, o PowerShell continuará executando o script ou o comando na instrução trap
.
O exemplo a seguir é uma instrução muito simples trap
:
trap {"Error found."}
Essa trap
instrução 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 o seguinte:
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.
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 o seguinte:
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
as instruções podem ser definidas em qualquer lugar dentro de um determinado escopo, mas sempre se aplicam a todas as instruções nesse escopo. Em runtime, trap
as instruções em um bloco são definidas antes de qualquer outra instrução ser executada. Em JavaScript, isso é conhecido como içamento. Isso significa que trap
as 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 são definidas. Por exemplo, definir um trap
no final de um script e gerar um erro na primeira instrução ainda dispara esse trap
.
Interceptando erros específicos
Um script ou comando pode ter várias trap
instruções. Um trap
pode ser definido para lidar com erros específicos.
O exemplo a seguir é uma trap
instrução 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 trap
instrução exibe a cadeia de caracteres "Erro de comando preso".
Depois de executar a trap
lista de instruções, o PowerShell grava o objeto de erro no fluxo de erros e continua o script.
O PowerShell usa tipos de exceção do .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 um erro criado por um comando desconhecido. Ele também intercepta outros tipos de erro.
Você pode ter mais de uma trap
instrução em um script. Cada tipo de erro pode ser interceptado por apenas uma trap
instrução. Quando ocorre um erro de encerramento, o PowerShell pesquisa o com a trap
correspondência mais específica, começando no escopo atual da execução.
O exemplo de script a seguir contém um erro. O script inclui uma instrução geral trap
que intercepta qualquer erro de encerramento 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 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.
Como o PowerShell não reconhece "nonsenseString" como um cmdlet ou outro item, ele retorna um erro CommandNotFoundException . Esse erro de encerramento é interceptado pela instrução específica trap
.
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 |
4 | 1/$null
| ~~~~~~~
| Attempted to divide by zero.
A tentativa de dividir por zero não cria um erro CommandNotFoundException . Em vez disso, esse erro é interceptado pela outra trap
instrução , que intercepta qualquer erro de encerramento.
Interceptando erros em um bloco de script
Por padrão, quando um erro de encerramento é gerado, a execução é transferida para a instrução trap. Depois que o bloco é executado, o trap
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 instrução foreach
, 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..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
Na saída acima, você pode ver os loops continuarem até a última iteração.
Quando o script tenta dividir 1 por 0, um erro de encerramento é gerado. O restante do foreach
scriptblock é ignorado, a try
instrução é executada e o script continua após o foreach
scriptblock.
Interceptação de erros e escopo
Se ocorrer um erro de encerramento no mesmo escopo 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 instrução trap
estiver em um escopo diferente do erro, a execução continuará na próxima instrução que está no mesmo escopo 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 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
A trap
instrução na função intercepta o erro. Depois de exibir a mensagem, o PowerShell retoma a execução da função. Observe que Function1
foi concluído.
Compare isso 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 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.
Neste exemplo, o comando "function2 foi concluído" 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.
Cuidado
Quando várias interceptações são definidas para a mesma condição de erro, a primeira trap
definida lexicamente (mais alta no escopo) é usada.
No exemplo a seguir, somente o trap
com "whoops 1" é executado.
Remove-Item -ErrorAction Stop ThisFileDoesNotExist
trap { "whoops 1"; continue }
trap { "whoops 2"; continue }
Importante
Uma instrução Trap tem como escopo 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 o script de origem de ponto for encerrado, todas as trap
instruções internas 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 sendo executado após um erro de encerramento.
Se você incluir uma break
instrução em uma trap
lista de instruções, o PowerShell interromperá a função ou o script. A seguinte função de exemplo usa o 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 o break
palavra-chave, a função não continua a ser executada e a linha "Função concluída" não é executada.
Se você incluir um 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
. No entanto, com o continue
palavra-chave, o PowerShell não grava um erro no fluxo de erros.
A função de exemplo a seguir usa o continue
palavra-chave em uma trap
instrução :
function continue_example {
trap {
"Error trapped"
continue
}
1/$null
"Function completed."
}
continue_example
Error trapped
Function completed.
A função é retomada depois que o erro é interceptado e a instrução "Função concluída" é executada. Nenhum erro é gravado no fluxo de erros.
Observações
trap
As instruções fornecem uma maneira simples de garantir amplamente que todos os erros de encerramento dentro de um escopo sejam tratados. Para tratamento de erros mais refinados, use try
/catch
blocos em que as armadilhas são definidas 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.