Sobre interceptação
Descrição breve
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 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 # , os erros de encerramento 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. As instruções Trap lidam com os erros de encerramento e permitem a execução do script ou da função para continuar em vez de parar.
As instruções Trap também podem ser mais complexas. A lista de instruções da interceptação pode incluir várias condições ou chamadas de função. Uma interceptação pode gravar logs, condições de teste ou até mesmo executar outro programa.
Syntax
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 ocorre um erro de encerramento. Uma instrução Trap consiste na trap palavra-chave, opcionalmente seguida por uma expressão de tipo, e o bloco de instruções que contém a lista de instruções a serem executadas quando um erro é interceptado. A expressão de tipo restringe os tipos de erros que a interceptação captura.
Um script ou comando pode ter várias instruções de interceptação. As instruções Trap podem aparecer em qualquer lugar no script ou comando.
Interceptando todos os erros de encerramento
Quando ocorre um erro de encerramento que não é tratado de outra maneira em um script ou comando, o PowerShell verifica se há 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.
O exemplo a seguir é uma instrução de interceptação muito simples:
trap {"Error found."}
Essa instrução Trap intercepta qualquer erro de encerramento.
No exemplo a seguir, a função inclui uma cadeia de caracteres de sentido que causa um erro de tempo de execução.
function TrapTest {
trap {"Error found."}
nonsenseString
}
TrapTest
A execução dessa função retorna o seguinte:
Error found.
O exemplo a seguir inclui uma instrução Trap 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 then try
again.
Importante
As instruções Trap podem ser definidas em qualquer lugar dentro de um determinado escopo, mas sempre se aplicam a todas as instruções nesse escopo. Em tempo de execução, as interceptações em um bloco são definidas antes de qualquer outra instrução ser executada. No JavaScript, isso é conhecido como guindaste. Isso significa que as interceptações se aplicam a todas as instruções nesse bloco, mesmo que a execução não tenha sido avançada após o ponto no qual elas são definidas. Por exemplo, definir uma interceptação no final de um script e lançar um erro na primeira instrução ainda dispara essa interceptação.
Interceptando erros específicos
Um script ou comando pode ter várias instruções de interceptação. As interceptações podem ser definidas 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 de interceptação exibe a cadeia de caracteres "erro de comando interceptado". Depois de executar a Trap lista de instruções, o PowerShell grava o objeto de erro no fluxo de erros e, em seguida, continua o script.
O PowerShell usa os tipos de exceção do Microsoft .NET Framework. 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 que é criado por um comando desconhecido. Ele também intercepta outros tipos de erro.
Você pode ter mais de uma instrução Trap em um script. Cada tipo de erro pode ser interceptado por apenas uma instrução Trap. Quando ocorre um erro de encerramento, o PowerShell pesquisa a interceptação com a correspondência mais específica, começando no escopo atual de execução.
O exemplo de script a seguir contém um erro. O script inclui uma instrução de interceptação geral que intercepta qualquer erro de encerramento e uma Trap instrução 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 : 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.
At C:\temp\test\traptest.ps1:5 char:1
+ nonsenseString
+ ~~~~~~~~~~~~~~
+ CategoryInfo : ObjectNotFound: (nonsenseString:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException
Como o PowerShell não reconhece "não-Sense" como um cmdlet ou outro item, ele retorna um erro CommandNotFoundException . Esse erro de encerramento é interceptado pela instrução Trap específica.
O exemplo de script a seguir contém as mesmas instruções de interceptação 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
Attempted to divide by zero.
At C:\temp\test\traptest.ps1:5 char:1
+ 1/$null
+ ~~~~~~~
+ CategoryInfo : NotSpecified: (:) [], RuntimeException
+ FullyQualifiedErrorId : RuntimeException
A tentativa de dividir por zero não cria um erro CommandNotFoundException . Em vez disso, esse erro é interceptado pela outra instrução Trap, que intercepta qualquer erro de encerramento.
Interceptando erros e escopo
Se um erro de encerramento ocorrer no mesmo escopo que a instrução Trap, o PowerShell executará a lista de instruções definidas pela interceptação. 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 instrução Trap.
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 de interceptação:
function function1 {
trap { "An error: " }
NonsenseString
"function1 was completed"
}
Posteriormente, no script, a execução da função function1 produzirá o seguinte resultado:
function1
An error:
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
then try again.
At C:\PS>TestScript1.ps1:3 char:19
+ NonsenseString <<<<
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 foi concluída.
Compare isso com o exemplo a seguir, que tem o mesmo erro e Trap instrução. 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 Function2 função produz o seguinte resultado:
An error:
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
then try again.
At C:\PS>TestScript2.ps1:4 char:19
+ NonsenseString <<<<
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 instrução Trap está fora da função. O PowerShell não volta à função depois que a instrução Trap é executada.
Cuidado
Quando várias interceptações são definidas para a mesma condição de erro, a primeira interceptação definida lexicalmente (mais alta no escopo) é usada.
No exemplo a seguir, somente a interceptação com "Opa 1" é executada.
Remove-Item -ErrorAction Stop ThisFileDoesNotExist
trap { "whoops 1"; continue }
trap { "whoops 2"; continue }
Usando as break continue palavras-chave e
Você pode usar as Break Continue palavras-chave e em uma instrução Trap 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 instruções de interceptação, o PowerShell interromperá a função ou o script. A seguinte função de exemplo usa a Break palavra-chave em uma instrução Trap:
function break_example {
trap {
"Error trapped"
break
}
1/$null
"Function completed."
}
break_example
Error trapped
Attempted to divide by zero.
At line:4 char:7
Como a instrução Trap inclui a 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 uma Continue instrução em uma instrução Trap, o PowerShell será retomado após a instrução que causou o erro, assim como faria sem Break ou Continue . Com a Continue palavra-chave, no entanto, o PowerShell não grava um erro no fluxo de erros.
A seguinte função de exemplo usa a 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 erro.
Observações
As instruções de interceptação fornecem uma maneira simples de garantir amplamente que todos os erros de encerramento dentro de um escopo sejam manipulados. Para tratamento de erros mais refinado, use try / catch blocos em que as interceptações são definidas usando Catch instruções. As Catch instruções se aplicam somente ao código dentro da Try instrução associada. Para obter mais informações, consulte about_Try_Catch_Finally.