about_Try_Catch_Finally

  • Artigo

Descrição breve

Descreve como usar os tryblocos , catche finally para manipular erros de encerramento.

Descrição longa

Use try, catche finally blocos para responder ou manipular erros de encerramento em scripts. A Trap instrução também pode ser usada para manipular erros de encerramento em scripts. Para obter mais informações, consulte about_Trap.

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 usando o pipeline atual. Em outras linguagens, como C#, os erros de encerramento são chamados de exceções.

Use o bloco para definir uma seção de um script na qual você deseja que o try PowerShell monitore erros. Quando ocorre um erro dentro do try bloco, o erro é salvo primeiro na $Error variável automática. Em seguida, o PowerShell procura um catch bloco para manipular o erro. Se a instrução não tiver um bloco correspondentecatch, o try PowerShell continuará a procurar um bloco ou Trap instrução apropriada catch nos escopos pai. Depois que um catch bloco for concluído ou se nenhum bloco ou Trap instrução apropriada catch for encontrado, o finally bloco será executado. Se o erro não puder ser manipulado, o erro será gravado no fluxo de erros.

Um catch bloco pode incluir comandos para rastrear o erro ou para recuperar o fluxo esperado do script. Um catch bloco pode especificar quais tipos de erro ele captura. Uma try instrução pode incluir vários catch blocos para diferentes tipos de erros.

Um finally bloco pode ser usado para liberar quaisquer recursos que não são mais necessários para o script.

try, catche finally se assemelham às trypalavras-chave , catche finally usadas na linguagem de programação C#.

Sintaxe

Uma try instrução contém um try bloco, zero ou mais catch blocos e zero ou um finally bloco. Uma try instrução deve ter pelo menos um catch bloco ou um finally bloco.

A seguir é mostrada a sintaxe do try bloco:

try {<statement list>}

A try palavra-chave é seguida por uma lista de instruções em chaves. Se ocorrer um erro de encerramento enquanto as instruções na lista de instruções estiverem sendo executadas, o script passará o objeto de erro do try bloco para um bloco apropriado catch .

A seguir é mostrada a sintaxe do catch bloco:

catch [[<error type>][',' <error type>]*] {<statement list>}

Os tipos de erro aparecem entre colchetes. Os colchetes mais externos indicam que o elemento é opcional.

A catch palavra-chave é seguida por uma lista opcional de especificações de tipo de erro e uma lista de instruções. Se ocorrer um erro de encerramento no bloco, o try PowerShell procurará um bloco apropriado catch . Se um for encontrado, as catch instruções no bloco serão executadas.

O catch bloco pode especificar um ou mais tipos de erro. Um tipo de erro é uma exceção do Microsoft .NET Framework ou uma exceção derivada de uma exceção do .NET Framework. Um catch bloco manipula erros da classe de exceção especificada do .NET Framework ou de qualquer classe derivada da classe especificada.

Se um catch bloco especificar um tipo de erro, esse catch bloco manipulará esse tipo de erro. Se um catch bloco não especificar um tipo de erro, esse catch bloco manipulará qualquer erro encontrado no try bloco. Uma try instrução pode incluir vários catch blocos para os diferentes tipos de erro especificados.

A seguir é mostrada a sintaxe do finally bloco:

finally {<statement list>}

A finally palavra-chave é seguida por uma lista de instruções que é executada sempre que o script é executado, mesmo se a instrução foi executada try sem erro ou um erro foi detectado em uma catch instrução.

Observe que pressionar CTRL+C interrompe o pipeline. Os objetos enviados para o pipeline não serão exibidos como saída. Portanto, se você incluir uma instrução a ser exibida, como "Finalmente o bloco foi executado", ela não será exibida depois que você pressionar CTRL+C, mesmo se o finally bloco for executado.

Captura de erros

O script de exemplo a seguir mostra um try bloco com um catch bloco:

try { NonsenseString }
catch { "An error occurred." }

A catch palavra-chave deve seguir imediatamente o try bloco ou outro catch bloco.

O PowerShell não reconhece "NonsenseString" como um cmdlet ou outro item. A execução desse script retorna o seguinte resultado:

An error occurred.

Quando o script encontra "NonsenseString", ele causa um erro de encerramento. O catch bloco manipula o erro executando a lista de instruções dentro do bloco.

Usando várias instruções catch

Uma try instrução pode ter qualquer número de catch blocos. Por exemplo, o script a seguir tem um try bloco que baixa MyDoc.doce contém dois catch blocos:

try {
   $wc = new-object System.Net.WebClient
   $wc.DownloadFile("http://www.contoso.com/MyDoc.doc","c:\temp\MyDoc.doc")
}
catch [System.Net.WebException],[System.IO.IOException] {
    "Unable to download MyDoc.doc from http://www.contoso.com."
}
catch {
    "An error occurred that could not be resolved."
}

O primeiro catch bloco manipula erros dos tipos System.Net.WebException e System.IO.IOException . O segundo catch bloco não especifica um tipo de erro. O segundo catch bloco manipula quaisquer outros erros de terminação que ocorram.

O PowerShell corresponde a tipos de erro por herança. Um catch bloco manipula erros da classe de exceção especificada do .NET Framework ou de qualquer classe derivada da classe especificada. O exemplo a seguir contém um catch bloco que captura um erro "Command Not Found":

catch [System.Management.Automation.CommandNotFoundException]
{"Inherited Exception" }

O tipo de erro especificado, CommandNotFoundException, herda do tipo System.SystemException . O exemplo a seguir também captura um erro de comando não encontrado:

catch [System.SystemException] {"Base Exception" }

Esse catch bloco manipula o erro "Comando não encontrado" e outros erros que herdam do tipo SystemException .

Se você especificar uma classe de erro e uma de suas classes derivadas, coloque o catch bloco para a classe derivada antes do catch bloco para a classe geral.

Observação

O PowerShell encapsula todas as exceções em um tipo RuntimeException . Portanto, especificar o tipo de erro System.Management.Automation.RuntimeException se comporta da mesma forma que um bloco de captura não qualificado.

Usando armadilhas em uma tentativa de captura

Quando ocorre um erro de encerramento em um try bloco com um Trap definido dentro do bloco, mesmo que haja um bloco correspondentecatch, a instrução assume o tryTrap controle.

Se um Trap existir em um bloco superior ao try, e não houver nenhum bloco correspondente catch dentro do escopo atual, o assumirá o Trap controle, mesmo que qualquer escopo pai tenha um bloco correspondente catch .

Acessando informações de exceção

Dentro de um catch bloco, o erro atual pode ser acessado usando $_, que também é conhecido como $PSItem. O objeto é do tipo ErrorRecord.

try { NonsenseString }
catch {
  Write-Host "An error occurred:"
  Write-Host $_
}

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

An Error occurred:
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.

Há propriedades adicionais que podem ser acessadas, como ScriptStackTrace, Exception e ErrorDetails. Por exemplo, se alterarmos o script para o seguinte:

try { NonsenseString }
catch {
  Write-Host "An error occurred:"
  Write-Host $_.ScriptStackTrace
}

O resultado será semelhante a:

An Error occurred:
at <ScriptBlock>, <No file>: line 2

Liberando recursos usando finalmente

Para liberar recursos usados por um script, adicione um finally bloco após os try blocos e catch . As finally instruções de bloco são executadas independentemente de o try bloco encontrar um erro de encerramento. O PowerShell executa o finally bloco antes que o script termine ou antes que o bloco atual saia do escopo.

Um finally bloco é executado mesmo se você usar CTRL+C para parar o script. Um finally bloco também é executado se uma palavra-chave Exit parar o script de dentro de um catch bloco.

Confira também