TÓPICO
about_Trap
DESCRIÇÃO RESUMIDA
Descreve uma palavra-chave que trata um erro de encerramento.
DESCRIÇÃO LONGA
Um erro de encerramento interrompe a execução de uma instrução.
Se o Windows PowerShell não tratar um erro de encerramento de
algum modo, o Windows PowerShell também deixará de executar a
função ou o script no pipeline atual. Em outras linguagens, como
C#, esses erros são chamados de 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 tratam os erros de encerramento e permitem que a execução do
script ou da função continue, em vez de ser interrompida.
Sintaxe
Esta é a sintaxe da instrução Trap:
trap [[<tipo de erro>]] {<lista de instruções>}
A instrução Trap inclui uma lista de instruções a serem
executadas quando ocorrer um erro de encerramento. A
palavra-chave Trap pode, opcionalmente, especificar um tipo de
erro. Um tipo de erro requer colchetes.
Um script ou um comando pode ter várias instruções Trap. As
instruções Trap podem aparecer em qualquer parte do script ou
comando.
Interceptando todos os erros de encerramento
Quando ocorre um erro de encerramento que não é tratado de
outro modo em um script ou comando, o Windows PowerShell
procura uma instrução Trap que possa tratá-lo. Se uma instrução
Trap estiver presente, o Windows PowerShell continuará
executando o script ou o comando na instrução Trap.
O exemplo a seguir é uma instrução Trap muito simples:
trap {"Erro encontrado."}
Essa instrução Trap intercepta qualquer erro de encerramento. O
exemplo a seguir é uma função que contém essa instrução Trap:
function TrapTest {
trap {"Erro encontrado."}
nonsenseString
}
Essa função inclui uma cadeia de caracteres sem sentido que
causa um erro. Executar a função retorna o seguinte:
C:\PS> TrapTest
Erro encontrado.
O exemplo a seguir inclui uma instrução Trap que exibe o erro
usando a variável automática $_:
function TrapTest {
trap {"Erro encontrado: $_"}
nonsenseString
}
Executar essa versão da função retorna o seguinte:
C:\PS> TrapTest
Erro encontrado: O termo 'nonsenseString' não é reconhecido
como nome de cmdlet, função, arquivo de script ou programa
operável. Verifique a grafia do nome ou, se um caminho
tiver sido incluído, veja se o caminho está correto e tente
novamente.
As instruções Trap também podem ser mais complexas. Uma
instrução Trap pode incluir várias condições ou chamadas de
função. Ela pode registrar em log, testar ou até mesmo executar
outro programa.
Interceptando erros de encerramento especificados
O exemplo a seguir é uma instrução Trap que intercepta o tipo
de erro CommandNotFoundException:
trap [System.Management.Automation.CommandNotFoundException]
{"Erro de comando interceptado"}
Quando uma função ou um script encontra uma cadeia de
caracteres que não corresponde a um comando conhecido, essa
instrução Trap exibe a cadeia de caracteres "Erro de comando
interceptado". Depois de executar qualquer instrução na lista
de instruções Trap, o Windows PowerShell grava o objeto de erro
no fluxo de erros, e então continua o script.
O Windows 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] {"Um erro interceptado"}
O tipo de erro CommandNotFoundException é herdeiro do tipo
System.Exception. Essa instrução intercepta um erro criado por
um comando desconhecido. Ela intercepta também outros tipos de erro.
É possível ter mais de uma instrução Trap em um script. Cada
erro pode ser interceptado por somente uma instrução Trap. Se
um erro ocorrer e houver mais de uma instrução Trap disponível,
o Windows PowerShell usará a instrução Trap com o tipo de erro
de correspondência mais específica com o erro.
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 estabelece o tipo
CommandNotFoundException.
trap {"Outro erro de encerramento interceptado" } trap
[System.Management.Automation.CommandNotFoundException] {"Erro de
comando interceptado"} nonsenseString
A execução desse script produz o seguinte resultado:
Erro de comando interceptado
O termo 'nonsenseString' não é reconhecido como nome de
cmdlet, função, arquivo de script ou programa operável.
Verifique a grafia do nome ou, se um caminho tiver sido
incluído, veja se o caminho está correto e tente novamente.
At C:\PS>testScript1.ps1:3 char:19
+ nonsenseString <<<<
Como o Windows PowerShell não reconhece "nonsenseString" como
um cmdlet ou outro item, retorna um erro CommandNotFoundExceptio
n. Esse erro de encerramento é interceptado pela instrução Trap
específica.
O exemplo de script a seguir contém as mesmas instruções Trap
com um erro diferente:
trap {"Outro erro de encerramento interceptado" }
trap [System.Management.Automation.CommandNotFoundException]
{"Erro de comando interceptado"}
1/$null
A execução desse script produz o seguinte resultado:
Outro erro de encerramento interceptado
Tentativa de divisão por zero.
At C:PS> errorX.ps1:3 char:7
+ 1/ <<<< $null
A tentativa de dividir por zero não cria um erro CommandNotFound
Exception. Em vez disso, o erro é interceptado pela outra
instrução Trap, que intercepta qualquer erro de encerramento.
Interceptação de erros e escopo
Se um erro de encerramento ocorrer no mesmo escopo da instrução
Trap, depois de executar as instruções Trap, o Windows
PowerShell continuará 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 estiver no mesmo escopo da
instrução Trap.
Por exemplo, se um erro ocorrer em uma função, e a instrução
Trap estiver nessa função, o script continuará na próxima
instrução. O script a seguir, por exemplo, contém um erro e uma
instrução Trap:
function function1 {
trap { "Um erro: " }
NonsenseString
"function1 foi concluída"
}
Posteriormente no script, a execução da função Function1 gera o
seguinte resultado:
function1
Um erro:
O termo 'NonsenseString' não é reconhecido como nome de
cmdlet, função, arquivo de script ou programa operável.
Verifique a grafia do nome ou, se um caminho tiver sido
incluído, veja se o caminho está correto e tente novamente.
At C:\PS>TestScript1.ps1:3 char:19
+ NonsenseString <<<<
function1 foi concluída
A instrução Trap na função intercepta o erro. Depois de exibir
a mensagem, o Windows PowerShell continua a executar a função.
Observe que Function1 foi concluída.
Compare isso com o exemplo a seguir, que tem o mesmo erro e a
mesma instrução Trap. Neste exemplo, a instrução Trap ocorre
fora da função:
function function2 {
NonsenseString
"function2 foi concluída"
}
trap { "Um erro: " }
. . .
function2
Posteriormente no script, a execução da função Function2 gera o
seguinte resultado:
Um erro:
O termo 'NonsenseString' não é reconhecido como nome de
cmdlet, função, arquivo de script ou programa operável.
Verifique a grafia do nome ou, se um caminho tiver sido
incluído, veja se o caminho está correto e tente novamente.
At C:\PS>TestScript2.ps1:4 char:19
+ NonsenseString <<<<
Nesse exemplo, o comando "function2 foi concluída" não foi
executado. Embora os dois erros de encerramento ocorram dentro
de uma função, se a instrução Trap estiver fora da função, o
Windows PowerShell não voltará a ela depois de executar a
instrução Trap.
Usando as 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
continuará em execução após um erro de encerramento.
Se você incluir uma instrução Break em uma lista de instruções
Trap, o Windows PowerShell interromperá a função ou o script. A
função de exemplo a seguir usa a palavra-chave Break em uma
instrução Trap:
C:\PS> function break_example {
trap {"Erro interceptado"; break;}
1/$null
"Função concluída."
}
C:\PS> break_example
Erro interceptado
Tentativa de divisão por zero.
At line:4 char:7
Como a instrução Trap inclui a palavra-chave Break, a função
não continua em execução, e a linha "Função concluída" não é
executada.
Se você incluir uma instrução Continue em uma instrução Trap, o
Windows PowerShell continuará depois da instrução que causou o
erro, da mesma forma que faria sem Break ou Continue. No
entanto, com a palavra-chave Continue, o Windows PowerShell não
gravará um erro no fluxo de erros.
A função de exemplo a seguir usa a palavra-chave Continue em
uma instrução Trap:
C:\PS> function continue_example {
trap {"Erro interceptado"; continue;} 1/$null
"Função concluída."}
C:\PS> continue_example
Erro interceptado
Função concluída.
A função continua depois que o erro é interceptado, e a
instrução "Função concluída" é executada. Nenhum erro é gravado
no fluxo de erros.
CONSULTE TAMBÉM
about_Break
about_Continue
about_Throw
about_Try_Catch_Finally
about_Scopes