TÓPICO

about_Throw

DESCRIÇÃO RESUMIDA
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, uma função ou um script.

Por exemplo, é possível usar a palavra-chave Throw no bloco de

script de uma instrução If para responder a uma condição, ou
então 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 acionar qualquer objeto, como uma

cadeia de caracteres de mensagem para o usuário ou o objeto que
causou o erro.

SINTAXE
A sintaxe da palavra-chave Throw é a seguinte:

throw [<expressão>]

A expressão na sintaxe de Throw é opcional. Quando a instrução

Throw não aparece em um bloco Catch e não inclui uma expressão,
gera um erro ScriptHalted.

C:\PS> throw

ScriptHalted
At line:1 char:6
+ throw <<<<
+ CategoryInfo : OperationStopped: (:) [], RuntimeException
+ FullyQualifiedErrorId : ScriptHalted

Se a palavra-chave Throw for usada em um bloco Catch sem uma

expressão, acionará a RuntimeException atual novamente. Para
obter mais informações, consulte about_Try_Catch_Finally.

ACIONANDO 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 "Isto é um erro."

Isto é um erro.
At line:1 char:6
+ throw <<<< "Isto é um erro."
+ CategoryInfo : OperationStopped: (Isto é um erro.:String)
[], RuntimeException
+ FullyQualifiedErrorId : Isto é um erro.
 ACIONANDO OUTROS OBJETOS
A expressão também pode ser um objeto, que aciona o objeto que
representa o processo do PowerShell, conforme mostrado no
exemplo a seguir:

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

System.Diagnostics.Process (powershell) At line:1 char:6

+ throw <<<< (get-process powershell)
+ CategoryInfo : OperationStopped: (System.Diagnostics.Process
(powershell):Process) [], RuntimeException
+ FullyQualifiedErrorId : System.Diagnostics.Process (powershell)

Você pode usar a propriedade TargetObject do objeto ErrorRecord

na variável automática $error para examinar o erro.

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

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ -- -----------

-----------
319 26 61016 70864 568 3.28 5548 powershell

Você também pode acionar um objeto ErrorRecord ou uma exceção do

Microsoft .NET Framework. O exemplo a seguir usa a palavra-chave Throw para
acionar um objeto System.FormatException.

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

C:\PS> throw $formatError

Um dos itens identificados tinha um formato inválido.

At line:1 char:6
+ throw <<<< $formatError
+ CategoryInfo : OperationStopped: (:) [], FormatException
+ FullyQualifiedErrorId : Um dos itens identificados tinha um formato
inválido.

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 acionado pela
palavra-chave Throw.

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

Você pode usar a palavra-chave Throw para tornar um parâmetro de
função obrigatório.

Isso é uma alternativa a usar o parâmetro Mandatory da

 palavra-chave Parameter. Quando você usa o parâmetro Mandatory, o
sistema solicita ao usuário o valor de parâmetro necessário.
Quando você usa a palavra-chave Throw, o comando é interrompido e
exibe o registro de erro.

Por exemplo, a palavra-chave Throw na subexpressão do parâmetro

torna o parâmetro Path obrigatório na função.

Nesse caso, a palavra-chave Throw aciona uma cadeia de caracteres

de mensagem, mas será a presença da palavra-chave Throw que irá
gerar o erro de encerramento se o parâmetro Path não for
especificado. A expressão após Throw é opcional.

function Get-XMLFiles
{
param ($path = $(throw "O parâmetro Path é obrigatório."))
dir -path $path\* -include *.xml -recurse | sort
lastwritetime | ft lastwritetime, attributes, name -auto }

CONSULTE TAMBÉM
about_Break
about_Continue
about_Scope
about_Trap
about_Try_Catch_Finally