about_Throw

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

TÓPICO

about_Throw

DESCRIÇÃO BREVE

Descreve a palavra-chave Throw, que gera um erro de terminação.

DESCRIÇÃO LONGA

A palavra-chave Throw causará um erro de terminação. Você pode usar a palavra-chave Throw para interromper o processamento de um comando, uma função ou um 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 em um 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 aparecer em um bloco Catch, e não incluir uma expressão, ela gerará 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, ele gerará o atual RuntimeException 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."

        This is an error.
        At line:1 char:6
        + throw <<<<  "This is an error."
            + CategoryInfo          : OperationStopped: (This is an error.:String) [], RuntimeException
            + FullyQualifiedErrorId : 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 seguinte corpo da seção example:Insert aqui.

        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 $error automática 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 gerar um objeto ErrorRecord ou uma exceção do Microsoft .NET Framework. 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

        One of the identified items was in an invalid format.
        At line:1 char:6
        + throw <<<<  $formatError
            + CategoryInfo          : OperationStopped: (:) [], FormatException
            + FullyQualifiedErrorId : One of the identified items was in an invalid format.

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 o objeto RuntimeException variam de acordo com o objeto que gera a 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.

Essa é uma alternativa ao uso do 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 para e exibe o registro de erro.

Por exemplo, a palavra-chave Throw na subexpressão parâmetro torna o parâmetro Path um parâmetro obrigatório na função.

Nesse caso, a palavra-chave Throw gera uma cadeia de caracteres da mensagem, mas é a presença da palavra-chave Throw que gera o erro de terminação se o parâmetro Path não for especificado. A expressão que segue Throw é opcional.

        function Get-XMLFiles
        {
            param ($path = $(throw "The Path parameter is required."))
            dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name  -auto
        }

CONSULTE TAMBÉM

about_Break

about_Continue

about_Scope

about_Trap

about_Try_Catch_Finally