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