about_Throw

Descrição curta

Descreve a palavra-chave Throw, que gera um erro de encerramento.

Descrição longa

A palavra-chave Throw causa um erro de encerramento. Você pode usar a palavra-chave Throw para interromper o processamento de um comando, função ou script.

Por exemplo, você pode usar a palavra-chave Throw no bloco de script de uma instrução If para responder a uma condição ou no bloco Catch de uma instrução Try-Catch-Finally. Você também pode usar a palavra-chave Throw em uma declaração de parâmetro para tornar um parâmetro de função obrigatório.

A palavra-chave Throw pode lançar qualquer objeto, como uma cadeia de caracteres de mensagem do usuário ou o objeto que causou o erro.

Sintaxe

A sintaxe da palavra-chave Throw é a seguinte:

throw [<expression>]

A expressão na sintaxe Throw é opcional. Quando a instrução Throw não aparece em um bloco Catch e não inclui uma expressão, ela gera um erro ScriptHalted.

C:\PS> throw

Exception: ScriptHalted

Se a palavra-chave Throw for usada em um bloco Catch sem uma expressão, ela gerará o RuntimeException atual novamente. Para obter mais informações, consulte about_Try_Catch_Finally.

Gerando uma cadeia de caracteres

A expressão opcional em uma instrução Throw pode ser uma cadeia de caracteres, conforme mostrado no exemplo a seguir:

C:\PS> throw "This is an error."

Exception: This is an error.

Gerando outros objetos

A expressão também pode ser um objeto que gera o objeto que representa o processo do PowerShell, conforme mostrado no exemplo a seguir:

C:\PS> throw (get-process Pwsh)

Exception: System.Diagnostics.Process (pwsh) System.Diagnostics.Process (pwsh) System.Diagnostics.Process (pwsh)

Você pode usar a propriedade TargetObject do objeto ErrorRecord na variável automática $error para examinar o erro.

C:\PS> $error[0].targetobject

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    125   174.44     229.57      23.61    1548   2 pwsh
     63    44.07      81.95       1.75    1732   2 pwsh
     63    43.32      77.65       1.48    9092   2 pwsh

Você também pode lançar um objeto ErrorRecord ou uma exceção .NET. O exemplo a seguir usa a palavra-chave Throw para gerar um objeto System.FormatException.

C:\PS> $formatError = new-object system.formatexception

C:\PS> throw $formatError

OperationStopped: One of the identified items was in an invalid format.

O erro resultante

A palavra-chave Throw pode gerar um objeto ErrorRecord. A propriedade Exception do objeto ErrorRecord contém um objeto RuntimeException. O restante do objeto ErrorRecord e do objeto RuntimeException varia de acordo com o objeto que a palavra-chave Throw gera.

O objeto RunTimeException é encapsulado em um objeto ErrorRecord e o objeto ErrorRecord é salvo automaticamente na variável automática $Error.

Usando Throw para criar um parâmetro obrigatório

Ao contrário das versões anteriores do PowerShell, não use a palavra-chave Throw para validação de parâmetro. Consulte about_Functions_Advanced_Parameters para conhecer a maneira correta.

Consulte também

  • Last updated on