about_Throw

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