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
string 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 string
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