Sobre Trap

Breve descrição

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

Longa descrição

Um erro de terminação impede que uma declaração decorra. Se o PowerShell não lidar com um erro de terminação de alguma forma, o PowerShell também deixa de executar a função ou o script no pipeline atual. Noutras línguas, como # C, os erros de terminação são conhecidos como exceções.

A Trap palavra-chave especifica uma lista de declarações a executar quando ocorre um erro de terminação. As declarações de armadilhagem lidam com os erros de terminação e permitem que a execução do script ou função continue em vez de parar.

As declarações das armadilhas também podem ser mais complexas. A lista de declaração da armadilha pode incluir múltiplas condições ou chamadas de função. Uma armadilha pode escrever registos, condições de teste ou até executar outro programa.

Syntax

A declaração de Trap tem a seguinte sintaxe:

trap [[<error type>]] {<statement list>}

A declaração de Trap inclui uma lista de declarações a executar quando ocorre um erro de terminação. Uma declaração de Trap consiste na trap palavra-chave, opcionalmente seguida de uma expressão tipo, e no bloco de declaração que contém a lista de declarações a executar quando um erro está preso. A expressão tipo refina os tipos de erros que a armadilha apanha.

Um script ou comando pode ter várias declarações de Trap. As declarações de armadilhas podem aparecer em qualquer lugar do script ou comando.

Prender todos os erros de terminação

Quando ocorre um erro de terminação que não é tratado de outra forma num script ou comando, o PowerShell verifica se existe uma declaração de Trap que lida com o erro. Se uma declaração de Armadilha estiver presente, a PowerShell continua a executar o script ou o comando na declaração de Trap.

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

trap {"Error found."}

Esta declaração de Armadilha prende qualquer erro de terminação.

No exemplo seguinte, a função inclui uma cadeia sem sentido que causa um erro de tempo de execução.

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

TrapTest

Executar esta função devolve o seguinte:

Error found.

O exemplo a seguir inclui uma declaração de Trap que exibe o erro utilizando a $_ variável automática:

function TrapTest {
    trap {"Error found: $_"}
    nonsenseString
}

TrapTest

Executar esta versão da função devolve 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 declarações de armadilhas podem ser definidas em qualquer lugar dentro de um determinado âmbito, mas aplicam-se sempre a todas as declarações nesse âmbito. No tempo de execução, as armadilhas num bloco são definidas antes de quaisquer outras declarações serem executadas. No JavaScript, isto é conhecido como içar. Isto significa que as armadilhas se aplicam a todas as declarações desse bloco, mesmo que a execução não tenha avançado para além do ponto em que são definidas. Por exemplo, definir uma armadilha no final de um script e lançar um erro na primeira declaração ainda dispara essa armadilha.

Capturar erros específicos

Um script ou comando pode ter várias declarações de Trap. As armadilhas podem ser definidas para lidar com erros específicos.

O exemplo a seguir é uma declaração de Trap que prende o erro específico CommandNotFoundException:

trap [System.Management.Automation.CommandNotFoundException]
    {"Command error trapped"}

Quando uma função ou script encontra uma cadeia que não corresponde a um comando conhecido, esta declaração de Trap exibe a corda "Erro de comando preso". Depois de executar a Trap lista de declaração, a PowerShell escreve o objeto de erro no fluxo de erro e, em seguida, continua o script.

O PowerShell utiliza os tipos de exceção Quadro Microsoft .NET. O exemplo a seguir especifica o tipo de erro Sistema.Exceção:

trap [System.Exception] {"An error trapped"}

O tipo de erro CommandNotFoundException herda do tipo Sistema.Exceção. Esta afirmação prende um erro que é criado por um comando desconhecido. Também prende outros tipos de erros.

Podes ter mais do que uma declaração do Trap num guião. Cada tipo de erro pode ser preso apenas por uma declaração de Armadilha. Quando ocorre um erro de terminação, o PowerShell procura a armadilha com a correspondência mais específica, a partir do âmbito atual da execução.

O seguinte exemplo de script contém um erro. O script inclui uma declaração de Trap geral que prende qualquer erro de terminação e uma declaração específica Trap que especifica o tipo CommandNotFoundException.

trap {"Other terminating error trapped" }
trap [System.Management.Automation.CommandNotFoundException] {
  "Command error trapped"
}
nonsenseString

Executar este 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 o "nonsenseString" como um cmdlet ou outro item, devolve um erro de ComandoNotFoundException. Este erro de terminação está encurralado pela declaração específica do Trap.

O seguinte exemplo de script contém as mesmas declarações de Trap com um erro diferente:

trap {"Other terminating error trapped" }
trap [System.Management.Automation.CommandNotFoundException]
    {"Command error trapped"}
1/$null

Executar este 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 divisão por zero não cria um erro de verificação CommandNotFoundException. Em vez disso, esse erro é apanhado pela outra declaração de Trap, que prende qualquer erro de términa.

Erros de armadilhagem e âmbito

Se ocorrer um erro de terminação no mesmo âmbito que a declaração de Armadilha, a PowerShell executa a lista de declarações definidas pela armadilha. A execução continua na declaração após o erro. Se a declaração de Trap estiver num âmbito diferente do erro, a execução continua na próxima declaração que está no mesmo âmbito que a declaração de Trap.

Por exemplo, se ocorrer um erro numa função e a declaração de Trap estiver na função, o script continua na próxima declaração. O seguinte script contém um erro e uma declaração de armadilha:

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

Mais tarde no script, a execução da função Função1 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 declaração de Armadilha na função prende o erro. Depois de visualizar a mensagem, o PowerShell volta a executar a função. Nota que Function1 foi concluída.

Compare-o com o seguinte exemplo, que tem o mesmo erro e Trap declaração. Neste exemplo, a declaração de armadilha ocorre fora da função:

function function2 {
    NonsenseString
    "function2 was completed"
    }

trap { "An error: " }

function2

Executar a 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 "função2 foi concluído" não foi executado. Em ambos os exemplos, o erro de terminação ocorre dentro da função. Neste exemplo, no entanto, a declaração de Trap está fora da função. O PowerShell não volta a entrar na função depois da declaração de Armadilha.

Atenção

Quando várias armadilhas são definidas para a mesma condição de erro, a primeira armadilha definida lexicamente (mais alta no âmbito) é utilizada.

No exemplo seguinte, apenas a armadilha com "gritos 1" é executada.

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

Usando as `break` `continue` palavras-chave

Pode utilizar as Break Continue palavras-chave e as palavras-chave numa declaração de Trap para determinar se um script ou comando continua a funcionar após um erro de terminação.

Se incluir uma Break declaração numa lista de declaração de Trap, o PowerShell para a função ou o script. A seguinte função de amostra utiliza a Break palavra-chave numa declaração de armadilha:

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 declaração de Trap incluía a Break palavra-chave, a função não continua a funcionar e a linha "Função concluída" não é executada.

Se incluir uma Continue declaração numa declaração de Trap, a PowerShell retoma após a declaração que causou o erro, tal como faria sem ou Break Continue . No entanto, com a Continue palavra-chave, o PowerShell não escreve um erro no fluxo de erro.

A seguinte função de amostra utiliza a Continue palavra-chave numa Trap declaração:

function continue_example {
    trap {
        "Error trapped"
        continue
    }
    1/$null
    "Function completed."
}

continue_example

Error trapped
Function completed.

A função retoma após o erro ser preso e a declaração "Função concluída" é executado. Não se escreve qualquer erro no fluxo de erros.

Notas

As declarações de armadilhas fornecem uma forma simples de garantir que todos os erros de terminação num âmbito são tratados. Para um manuseamento de erros mais finos, utilize try / catch blocos onde as armadilhas são definidas com Catch declarações. As Catch declarações aplicam-se apenas ao código dentro da Try declaração associada. Para mais informações, consulte about_Try_Catch_Finally.