about_Functions_Advanced_Methods

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

TÓPICO

about_Functions_Advanced_Methods

DESCRIÇÃO BREVE

Descreve como as funções que especificam o atributo CmdletBinding podem usar os métodos e propriedades que estão disponíveis para cmdlets compilados.

DESCRIÇÃO LONGA

As funções que especificam o atributo CmdletBinding podem acessar uma série de métodos e propriedades através da variável $pscmdlet. Esses métodos incluem os seguintes métodos:

- Métodos de processamento de entrada que os cmdlets compilados usam para realizar seu trabalho.

- Os métodos ShouldProcess e ShouldContinue que são usados para obter comentários dos usuários antes de uma ação ser executada.

- O método ThrowTerminatingError para gerar registros de erro.

- Vários métodos Write que retornam tipos diferentes de saída.

Todos os métodos e propriedades da classe PSCmdlet estão disponíveis para funções avançadas. Para obter mais informações sobre esses métodos e propriedades, consulte System.Management.Automation.PSCmdlet na biblioteca MSDN (Microsoft Developer Network) em https://go.microsoft.com/fwlink/?LinkId=142139.

MÉTODOS DE PROCESSAMENTO DE ENTRADA

Os métodos descritos nesta seção são chamados de métodos de processamento de entrada. Para funções, esses três métodos são representados pelos blocos Begin, Process e End da função. Cada função deve incluir um ou mais desses blocos. O tempo de execução do Windows PowerShell® usa o código dentro desses blocos durante a execução de uma função. (Esses blocos também estão disponíveis para as funções que não usam o atributo CmdletBinding).

Begin

Esse bloco é usado para fornecer o pré-processamento único opcional para a função. O tempo de execução do Windows PowerShell usa o código nesse bloco uma vez para cada instância da função no pipeline.

Process

Esse bloco é usado para fornecer processamento de registro por registro para a função. Este bloco pode ser usado qualquer número de vezes, ou não ser usado de modo algum, dependendo da entrada para a função. Por exemplo, se a função for o primeiro comando no pipeline, o bloco Process será usado uma vez. Se a função não for o primeiro comando no pipeline, o bloco Process será usado uma vez para cada entrada que a função recebe do pipeline. Se não houver nenhuma entrada do pipeline, o bloco Process não é usado.

Esse bloco deve ser definido se um parâmetro de função for configurado para aceitar a entrada do pipeline. Se esse bloco não estiver definido e o parâmetro aceitar a entrada do pipeline, a função perderá os valores que são passados para a função por meio do pipeline.

Além disso, quando a função dá suporte a solicitações de confirmação (quando o parâmetro SupportsShouldProcess do atributo Parameter é definido como $True), a chamada para o método ShouldProcess deve ser feita de dentro do bloco Process.

End

Esse bloco é usado para fornecer o pós-processamento único opcional para a função.

O exemplo a seguir mostra a estrutura de uma função que contém um bloco Begin para o pré-processamento único, um bloco Process para processamento de vários registros e um bloco End para o pós-processamento único.

          Function Test-ScriptCmdlet
          {
            [CmdletBinding(SupportsShouldProcess=$True)] 
            Param ($Parameter1)
            Begin{}
            Process{}
            End{}
          }

MÉTODOS DE CONFIRMAÇÃO

ShouldProcess

Esse método é chamado para solicitar uma confirmação do usuário antes de a função executar uma ação modificaria o sistema. A função pode continuar com base no valor booliano retornado pelo método. Esse método pode ser chamado apenas de dentro do bloco Process{} da função. Além disso, o atributo CmdletBinding deve declarar que a função dá suporte para ShouldProcess (conforme mostrado no exemplo anterior).

Para obter mais informações sobre esse método, consulte System.Management.Automation.Cmdlet.ShouldProcess na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142142.

Para obter mais informações sobre como solicitar uma confirmação, consulte "Requesting Confirmation" (Solicitando confirmação) na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkID=136658.

ShouldContinue

Este método é chamado para solicitar uma segunda mensagem de confirmação. Deve ser chamado quando o método ShouldProcess retorna $true. Para obter mais informações sobre esse método, consulte System.Management.Automation.Cmdlet.ShouldContinue na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142143.

MÉTODOS ERROR

As funções podem chamar dois métodos diferentes quando ocorrem erros. Quando ocorre um erro de não encerramento, a função deve chamar o método WriteError, que é descrito na seção "Métodos Write". Quando ocorre um erro de encerramento e a função não pode continuar, ela deve chamar o método ThrowTerminatingError. Você também pode usar a instrução Throw para erros de encerramento e o cmdlet Write-Error para erros de não encerramento.

Para obter mais informações, consulte System.Management.Automation.Cmdlet. ThrowTerminatingError na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142144.

MÉTODOS WRITE

Uma função pode chamar os seguintes métodos para retornar tipos diferentes de saída. Observe que nem toda a saída vai para o próximo comando no pipeline. Você também pode usar vários cmdlets Write, como Write-Error.

WriteCommandDetail

Para obter informações sobre o método WriteCommandDetails, consulte System.Management.Automation.Cmdlet.WriteCommandDetail na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142155.

WriteDebug

Para fornecer informações que podem ser usadas para solucionar problemas de uma função, faça a função chamar o método WriteDebug. Isso exibe mensagens de depuração para o usuário. Para obter mais informações, consulte System.Management.Automation.Cmdlet.WriteDebug na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142156.

WriteError

As funções devem chamar este método quando ocorrerem erros de não encerramento e a função for projetada para continuar processando registros. Para obter mais informações, consulte System.Management.Automation.Cmdlet.WriteError na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142157.

Observação:

Se ocorrer um erro de encerramento, a função deve chamar o método de ThrowTerminatingError.

WriteObject

Este método permite que a função envie um objeto para o próximo comando no pipeline. Na maioria dos casos, esse é o método a ser usado quando a função retorna dados. Para obter mais informações, consulte System.Management.Automation.PSCmdlet.WriteObject na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142158.

WriteProgress

Para funções cujas ações levam muito tempo para serem concluídas, esse método permite que a função chame o método WriteProgress para que as informações de progresso sejam exibidas. Por exemplo, você pode exibir a porcentagem concluída. Para obter mais informações, consulte System.Management.Automation.PSCmdlet.WriteProgress na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142160.

WriteVerbose

Para fornecer informações detalhadas sobre o que a função está fazendo, faça com que a função chame o método WriteVerbose para exibir mensagens detalhadas para o usuário. Por padrão, as mensagens detalhadas não são exibidas. Para obter mais informações, consulte System.Management.Automation.PSCmdlet.WriteVerbose na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142162.

WriteWarning

Para fornecer informações sobre as condições que podem causar resultados inesperados, faça a função chamar o método WriteWarning para exibir mensagens de aviso para o usuário. Por padrão, as mensagens de aviso são exibidas. Para obter mais informações, consulte System.Management.Automation.PSCmdlet.WriteWarning na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142164.

Observação:

Você também pode exibir mensagens de aviso configurando a variável WarningPreference ou usando as opções de linha de comando Verbose e Debug.

OUTROS MÉTODOS E PROPRIEDADES

Para obter informações sobre os métodos e propriedades que podem ser acessadas por meio da variável $PSCmdlet, consulte System.Management.Automation.PSCmdlet na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142139.

Por exemplo, a propriedade ParameterSetName permite que você veja que o parâmetro definido que está sendo usado. Os conjuntos de parâmetros permitem que você crie uma função que realiza diferentes tarefas com base nos parâmetros especificados quando a função é executada.

CONSULTE TAMBÉM

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute