about_Trap
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
TÓPICO
about_Trap
DESCRIÇÃO BREVE
Descreve uma palavra-chave que manipula um erro de terminação.
DESCRIÇÃO LONGA
Um erro de terminação interrompe uma instrução de execução. Se o Windows PowerShell® não manipula um erro de terminação de alguma forma, o Windows PowerShell também para de executar o script ou a função do pipeline atual. Em outras linguagens, como C#, os erros de finalização são denominados exceções.
A palavra-chave Trap especifica uma lista de instruções a serem executadas quando ocorre um erro de terminação. Instruções de captura tratam os erros de finalização e permitem que a execução do script ou função continuem em vez de parar.
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 ocorre um erro de terminação. A palavra-chave Trap pode opcionalmente especificar um tipo de erro. Um tipo de erro requer colchetes.
Um comando ou script pode ter várias instruções Trap. Instruções de captura podem aparecer em qualquer lugar no script ou no comando.
CAPTURA DE TODOS OS ERROS DE FINALIZAÇÃO
Quando ocorre um erro de finalização que não é tratado de forma diferente em um script ou comando, o Windows PowerShell procura uma instrução Trap que manipula o erro. Se uma instrução Trap estiver presente, o Windows PowerShell continua a executar o script ou o comando na instrução Trap.
O exemplo a seguir é uma instrução Trap muito simples:
trap {"Error found."}
Essa instrução Trap intercepta qualquer erro de terminação. O exemplo a seguir é uma função que contém essa instrução Trap:
function TrapTest {
trap {"Error found."}
nonsenseString
}
Essa função inclui uma cadeia de caracteres sem sentido que causa um erro. Executar essa função retorna o seguinte:
C:\PS> TrapTest
Error found.
O exemplo a seguir inclui uma instrução Trap que exibe o erro usando a variável $_ automatic:
function TrapTest {
trap {"Error found: $_"}
nonsenseString
}
Executar essa versão da função retorna o seguinte:
C:\PS> TrapTest
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.
Instruções de captura também podem ser mais complexas. Uma instrução Trap pode incluir várias condições ou chamadas de função. Pode fazer logon, testar ou até mesmo executar outro programa.
CAPTURA DE ERROS DE FINALIZAÇÃO ESPECIFICADOS
O exemplo a seguir é uma instrução Trap que intercepta o tipo de erro de 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 "Erro do comando interceptado". Depois de executar todas as instruções na lista de instrução Trap, o Windows PowerShell grava o objeto de erro para o fluxo de erro e, em seguida, 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] {"An error trapped"}
O tipo de erro CommandNotFoundException herda do tipo System.Exception. Essa instrução intercepta o erro que é criado por um comando desconhecido. Ela também intercepta outros tipos de erro.
Você pode ter mais de uma instrução Trap em um script. Cada erro pode ser interceptado por apenas uma instrução Trap. Se ocorrer um erro, e mais de uma instrução Trap estiver disponível, o Windows PowerShell usa a instrução Trap com o tipo de erro mais específico que corresponde ao erro.
O exemplo de script a seguir contém um erro. O script inclui uma instrução Trap geral que intercepta qualquer erro de terminação e uma instrução Trap específica que especifica o tipo de CommandNotFoundException.
trap {"Other terminating error trapped" }
trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"}
nonsenseString
Executar esse script gera o seguinte resultado:
Command error trapped
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 <<<<
Como o Windows PowerShell não reconhece "nonsenseString" como um cmdlet ou outro item, ele retorna um erro de CommandNotFoundException. Esse erro de terminação é 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 {"Other terminating error trapped" }
trap [System.Management.Automation.CommandNotFoundException]
{"Command error trapped"}
1/$null
Executar esse script gera o seguinte resultado:
Other terminating error trapped
Attempted to divide by zero.
At C:PS> errorX.ps1:3 char:7
+ 1/ <<<< $null
A tentativa de divisão por zero não cria um erro CommandNotFoundException. Em vez disso, esse erro é interceptado pela outra instrução Trap, que intercepta qualquer erro de terminação.
CAPTURA DE ERROS E ESCOPO
Se ocorrer um erro de terminação no mesmo escopo da instrução Trap, depois de executar as instruções Trap, o Windows PowerShell continua na instrução após o erro. Se a instrução Trap estiver em um escopo diferente do erro, a execução continua na próxima instrução que está no mesmo escopo da 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. Por exemplo, o script a seguir contém um erro e uma instrução Trap:
function function1 {
trap { "An error: " }
NonsenseString
"function1 was completed"
}
Posteriormente no script, a execução da função Function1 produz 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 Windows 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 a instrução Trap. Neste exemplo, a instrução Trap ocorre fora da função:
function function2 {
NonsenseString
"function2 was completed"
}
trap { "An error: " }
. . .
function2
Posteriormente no script, a execução da função Function2 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ída" não foi executado. Embora ambos os erros de finalização ocorreram dentro de uma função, se a instrução Trap estiver fora da função, o Windows PowerShell não voltará para a função após a instrução Trap ser executada.
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 continuará a ser executado após um erro de terminação.
Se você incluir uma instrução Break em uma lista de instruções Trap, o Windows PowerShell interromperá a função ou script. A função de exemplo a seguir usa a palavra-chave Break em uma instrução Trap:
C:\PS> function break_example {
trap {"Error trapped"; break;}
1/$null
"Function completed."
}
C:\PS> break_example
Error trapped
Attempted to divide by zero.
At line:4 char:7
Como a instrução Trap incluiu a palavra-chave Break, a função não continua a executar 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 retoma após a instrução que causou o erro, exatamente como ele faria sem Break ou Continue. Com a palavra-chave Continue, no entanto, o Windows PowerShell não grava 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 {"Error trapped"; continue;}
1/$null
"Function completed."}
C:\PS> continue_example
Error trapped
Function completed.
A função continua após o erro ser interceptado e executa a instrução "Função concluída". Nenhum erro é gravado para o fluxo de erros.
CONSULTE TAMBÉM
about_Break
about_Continue
about_Scopes
about_Throw
about_Try_Catch_Finally