Sobre o Trap

Breve descrição

Descreve uma palavra-chave que lida com um erro de terminação.

Descrição longa

Um erro de encerramento interrompe a execução de uma instrução. Se o PowerShell não manipular 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 terminação são conhecidos como exceções.

A palavra-chave Trap especifica uma lista de instruções a serem executadas quando ocorre um erro de encerramento. As instruções Trap manipulam os erros de terminação e permitem que a execução do script ou função continue em vez de parar.

As declarações de armadilha também podem ser mais complexas. 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 ocorre um erro de encerramento. Uma instrução Trap consiste na palavra-chave trap , opcionalmente seguida por uma expressão de tipo, e no bloco de instrução que contém a lista de instruções a serem executadas quando um erro é intercetado. 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 de trap podem aparecer em qualquer lugar no script ou comando.

Intercetando todos os erros de terminação

Quando ocorre um erro de encerramento que não é tratado de outra forma 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 comando na instrução Trap.

O exemplo a seguir é uma instrução Trap muito simples:

trap {"Error found."}

Esta instrução Trap interceta qualquer erro de encerramento.

No exemplo a seguir, a função inclui uma cadeia de caracteres nonsense que causa um erro de tempo de execução.

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

TrapTest

A execução desta 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 de trap podem ser definidas em qualquer lugar dentro de um determinado escopo, mas sempre se aplicam a todas as instruções nesse escopo. No tempo de execução, os traps em um bloco são definidos antes que quaisquer outras instruções sejam executadas. Em JavaScript, isso é conhecido como elevação. Isso significa que as armadilhas 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, definir uma armadilha no final de um script e lançar um erro na primeira instrução ainda aciona essa armadilha.

Intercetação de erros específicos

Um script ou comando pode ter várias instruções Trap. Traps podem ser definidos para lidar com erros específicos.

O exemplo a seguir é uma instrução Trap que interceta 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 erro e 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 System.Exception. Esta instrução interceta um erro que é criado por um comando desconhecido. Também captura outros tipos de erro.

Você pode ter mais de uma instrução Trap em um script. Cada tipo de erro pode ser capturado por apenas uma instrução Trap. Quando ocorre um erro de encerramento, o PowerShell procura o trap 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 Trap geral que interceta qualquer erro de terminação 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 : 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 "nonsenseString" como um cmdlet ou outro item, ele retorna um erro CommandNotFoundException . Esse erro de encerramento é capturado 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

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 é capturado pela outra instrução Trap, que interceta qualquer erro de encerramento.

Erros de trapping e escopo

Se ocorrer um erro de encerramento no mesmo escopo da instrução Trap, o 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 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. O script a seguir contém um erro e uma instrução trap:

function function1 {
    trap { "An error: " }
    NonsenseString
    "function1 was completed"
    }

Mais adiante 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 interceta o erro. Depois de exibir a mensagem, o PowerShell retoma a execução da função. Note que Function1 foi concluído.

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 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 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 depois que a instrução Trap é executada.

Atenção

Quando vários traps são definidos para a mesma condição de erro, o primeiro trap definido lexicamente (mais alto no escopo) é usado.

No exemplo a seguir, apenas a armadilha com "whoops 1" é executada.

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

Usando o `break` e `continue` palavras-chave

Você pode usar as Break palavras-chave e Continue 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 Trap, o PowerShell interromperá a função ou o script. A função de exemplo a seguir 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 incluiu a palavra-chave Break , 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 palavra-chave Continue , no entanto, o 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:

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 é intercetado e a instrução "Função concluída" é executada. Nenhum erro é gravado no fluxo de erro.

Observações

As instruções de trap fornecem uma maneira simples de garantir amplamente que todos os erros de terminação dentro de um escopo sejam tratados. Para um tratamento de erros mais refinado, use blocos try/catch onde as armadilhas são definidas usando instruções Catch. As instruções Catch só se aplicam ao código dentro da instrução Try associada. Para obter mais informações, consulte about_Try_Catch_Finally.