Share via

Sobre o Trap

  • Artigo

Descrição breve

Descreve um palavra-chave que manipula um erro de encerramento.

Descrição longa

Um erro de encerramento impede 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 outros idiomas, como C#, erros de encerramento são conhecidos como exceções.

O trap palavra-chave especifica uma lista de instruções a serem executadas quando ocorre um erro de encerramento. trap As instruções lidam com os erros de encerramento das seguintes maneiras:

  • Exiba o erro depois de processar o trap bloco de instrução e continuar a execução do script ou função que contém o trap. Esse é o comportamento padrão.

  • Exiba o erro e anule a execução do script ou da função que contém o trap uso break na trap instrução .

  • Silencie o erro, mas continue a execução do script ou da função que contém o trap usando continue na trap instrução .

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.

Syntax

A instrução trap utiliza esta sintaxe:

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

A trap instrução inclui uma lista de instruções a serem executadas quando ocorrer um erro de encerramento. Uma trap instrução consiste no trap palavra-chave, opcionalmente seguido por uma expressão de tipo e o bloco de instrução que contém a lista de instruções a serem executadas quando um erro é interceptado. A expressão de tipo refina os tipos de erros que a trap captura.

Um script ou comando pode ter várias trap instruções. trap as instruções podem aparecer em qualquer lugar no script ou no comando.

Interceptando todos os erros de encerramento

Quando ocorre um erro de encerramento que não é tratado de outra forma em um script ou comando, o PowerShell verifica se há uma trap instrução que manipula o erro. Se uma trap instrução estiver presente, o PowerShell continuará executando o script ou o comando na trap instrução .

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

trap {"Error found."}

Essa trap instrução intercepta qualquer erro de encerramento.

No exemplo a seguir, a função inclui uma cadeia de caracteres sem sentido que causa um erro de runtime.

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

TrapTest

Executar essa função retorna o seguinte:

Error found.
nonsenseString:
Line |
   3 |      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.

O exemplo a seguir inclui uma trap instrução que exibe o erro usando a $_ variável automática:

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

TrapTest

Executar esta 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 try again.
nonsenseString:
Line |
   3 |      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.

Importante

trap as instruções podem ser definidas em qualquer lugar dentro de um determinado escopo, mas sempre se aplicam a todas as instruções nesse escopo. Em runtime, trap as instruções em um bloco são definidas antes que quaisquer outras instruções sejam executadas. Em JavaScript, isso é conhecido como içamento. Isso significa que trap as instruções 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 são definidas. Por exemplo, definir um trap no final de um script e gerar um erro na primeira instrução ainda dispara esse trap.

Interceptando erros específicos

Um script ou comando pode ter várias trap instruções. Um trap pode ser definido para lidar com erros específicos.

O exemplo a seguir é uma trap instrução 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 trap instrução exibe a cadeia de caracteres "Erro de comando preso". Depois de executar a lista de instruções, o trap PowerShell grava o objeto de erro no fluxo de erros e continua o script.

O PowerShell usa tipos de exceção do .NET. 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 criado por um comando desconhecido. Ele também intercepta outros tipos de erro.

Você pode ter mais de uma trap instrução em um script. Cada tipo de erro pode ser interceptado por apenas uma trap instrução. Quando ocorre um erro de encerramento, o PowerShell pesquisa o trap com a correspondência mais específica, começando no escopo atual da execução.

O exemplo de script a seguir contém um erro. O script inclui uma instrução geral trap que intercepta 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:
Line |
   5 |  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.

Como o PowerShell não reconhece "nonsenseString" como um cmdlet ou outro item, ele retorna um erro CommandNotFoundException . Esse erro de encerramento é interceptado pela instrução específica trap .

O exemplo de script a seguir contém as mesmas trap instruções 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
RuntimeException:
Line |
   4 |  1/$null
     |  ~~~~~~~
     | Attempted to divide by zero.

A tentativa de dividir por zero não cria um erro CommandNotFoundException . Em vez disso, esse erro é interceptado pela outra trap instrução, que intercepta qualquer erro de encerramento.

Interceptação de erros e escopo

Se ocorrer um erro de encerramento no mesmo escopo da instrução , o trap PowerShell executará a lista de instruções definidas pelo trap. A execução continua na instrução após o erro. Se a trap instrução estiver em um escopo diferente do erro, a execução continuará na próxima instrução que está no mesmo escopo da trap instrução .

Por exemplo, se ocorrer um erro em uma função e a trap instrução estiver na função , o script continuará na próxima instrução. O script a seguir contém um erro e uma trap instrução:

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

function1

A execução desse script produz o seguinte resultado:

An error:
NonsenseString:
Line |
   3 |      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.
function1 was completed

A trap instrução 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ído.

Compare isso com o exemplo a seguir, que tem o mesmo erro e trap instrução. Neste exemplo, a trap instrução 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:
NonsenseString:
Line |
   2 |      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.

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 trap instrução está fora da função. O PowerShell não volta para a função após a execução da trap instrução.

Cuidado

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

No exemplo a seguir, somente o trap com "whoops 1" é executado.

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

Importante

Uma instrução Trap tem o escopo de onde ela é compilada. Se você tiver uma trap instrução dentro de uma função ou script de origem de ponto, quando a função ou o script de origem de ponto for encerrado, todas as trap instruções internas serão removidas.

Usando as palavras-chave break e continue

Você pode usar as break palavras-chave e continue em uma trap instrução 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 trap lista de instruções, o PowerShell interromperá a função ou o script. A função de exemplo a seguir usa o break palavra-chave em uma trap instrução :

function break_example {
    trap {
        "Error trapped"
        break
    }
    1/$null
    "Function completed."
}

break_example

Error trapped
ParentContainsErrorRecordException:
Line |
   6 |      1/$null
     |      ~~~~~~~
     | Attempted to divide by zero.

Como a trap instrução incluiu o 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 um continue palavra-chave em uma trap instrução , o PowerShell será retomado após a instrução que causou o erro, assim como faria sem break ou continue. No entanto, com o continue palavra-chave, o PowerShell não grava um erro no fluxo de erros.

A função de exemplo a seguir usa o 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 erros.

Observações

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

Confira também

about_Break

about_Continue

about_Scopes

about_Throw

about_Try_Catch_Finally