about_Functions_Advanced_Methods
Descrição breve
Descreve como as funções que especificam o CmdletBinding
atributo podem usar os métodos e as propriedades que estão disponíveis para cmdlets compilados.
Descrição longa
As funções que especificam o CmdletBinding
atributo podem acessar vários métodos e propriedades por meio da $PSCmdlet
variável . Esses métodos incluem os seguintes métodos:
- Métodos de processamento de entrada que compilaram cmdlets usam para fazer seu trabalho.
- Os
ShouldProcess
métodos eShouldContinue
que são usados para obter comentários do usuário antes que uma ação seja executada. - O
ThrowTerminatingError
método para gerar registros de erro. - Vários
Write
métodos que retornam diferentes tipos 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, consulte System.Management.Automation.PSCmdlet.
Para obter mais informações sobre o CmdletBinding
atributo, consulte about_Functions_CmdletBindingAttribute.
Para a classe CmdletBindingAttribute , consulte System.Management.Automation.Cmdlet.CmdletBindingAttribute.
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 Begin
blocos , Process
e End
da função . Você não precisa usar nenhum desses blocos em suas funções.
Observação
Esses blocos também estão disponíveis para funções que não usam o CmdletBinding
atributo .
Começar
Esse bloco é usado para fornecer pré-processamento único opcional para a função. O runtime do PowerShell usa o código nesse bloco uma vez para cada instância da função no pipeline.
Processar
Esse bloco é usado para fornecer processamento de registro por registro para a função. Você pode usar um Process
bloco sem definir os outros blocos. O número de execuções de Process
bloco depende de como você usa a função e qual entrada a função recebe.
A variável $_
automática ou $PSItem
contém o objeto atual no pipeline para uso no Process
bloco. A $input
variável automática contém um enumerador que só está disponível para funções e blocos de script.
Para obter mais informações, confira about_Automatic_Variables.
- Chamar a função no início ou fora de um pipeline executa o
Process
bloco uma vez. - Em um pipeline, o
Process
bloco é executado uma vez para cada objeto de entrada que atinge a função. - Se a entrada de pipeline que atinge a função estiver vazia, o
Process
bloco não será executado.- Os
Begin
blocos eEnd
ainda são executados.
- Os
Importante
Se um parâmetro de função for definido para aceitar a entrada do pipeline e um Process
bloco não estiver definido, o processamento de registro por registro falhará. Nesse caso, sua função só será executada uma vez, independentemente da entrada.
End
Esse bloco é usado para fornecer pós-processamento único opcional para a função.
O exemplo a seguir mostra a estrutura de tópicos de uma função que contém um Begin
bloco para pré-processamento único, um Process
bloco para processamento de vários registros e um End
bloco para pós-processamento único.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
Observação
O uso de um Begin
bloco ou End
requer que você defina todos os três blocos. Ao usar todos os três blocos, todo o código do PowerShell deve estar dentro de um dos blocos.
Métodos de confirmação
ShouldProcess
Esse método é chamado para solicitar confirmação do usuário antes que a função execute uma ação que alteraria o sistema. A função pode continuar com base no valor booliano retornado pelo método . Esse método só pode ser chamado de dentro do Process{}
bloco da função. O CmdletBinding
atributo também deve declarar que a função dá suporte ShouldProcess
(conforme mostrado no exemplo anterior).
Para obter mais informações sobre esse método, consulte System.Management.Automation.Cmdlet.ShouldProcess.
Para obter mais informações sobre como solicitar confirmação, consulte Solicitando confirmação.
ShouldContinue
Esse método é chamado para solicitar uma segunda mensagem de confirmação. Ele deve ser chamado quando o ShouldProcess
método retorna $true
. Para obter mais informações sobre esse método, consulte System.Management.Automation.Cmdlet.ShouldContinue.
Métodos de erro
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 WriteError
método , que é descrito na Write
seção de métodos. Quando ocorre um erro de encerramento e a função não pode continuar, ela deve chamar o ThrowTerminatingError
método . Você também pode usar a Throw
instrução para encerrar erros e o cmdlet Write-Error para erros de não encerramento.
Para obter mais informações, consulte System.Management.Automation.Cmdlet.ThrowTerminatingError.
Métodos de gravação
Uma função pode chamar os métodos a seguir para retornar diferentes tipos de saída.
Observe que nem toda a saída vai para o próximo comando no pipeline. Você também pode usar os vários Write
cmdlets, como Write-Error
.
WriteCommandDetail
Para obter informações sobre o WriteCommandDetails
método , consulte System.Management.Automation.Cmdlet.WriteCommandDetail.
WriteDebug
Para fornecer informações que podem ser usadas para solucionar problemas de uma função, faça com que a função chame o WriteDebug
método . O WriteDebug
método exibe mensagens de depuração para o usuário. Para obter mais informações, consulte System.Management.Automation.Cmdlet.WriteDebug.
WriteError
As funções devem chamar esse 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.
Observação
Se ocorrer um erro de encerramento, a função deverá chamar o método ThrowTerminatingError .
Writeobject
O WriteObject
método permite que a função envie um objeto para o próximo comando no pipeline. Na maioria dos casos, WriteObject
é o método a ser usado quando a função retorna dados. Para obter mais informações, consulte System.Management.Automation.PSCmdlet.WriteObject.
WriteProgress
Para funções com ações que levam muito tempo para serem concluídas, esse método permite que a função chame o WriteProgress
método 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.
WriteVerbose
Para fornecer informações detalhadas sobre o que a função está fazendo, faça com que a função chame o WriteVerbose
método 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.
WriteWarning
Para fornecer informações sobre condições que podem causar resultados inesperados, faça com que a função chame 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.
Observação
Você também pode exibir mensagens de aviso configurando a $WarningPreference
variável ou usando as Verbose
opções de linha de comando e Debug
. para obter mais informações sobre a $WarningPreference
variável, consulte about_Preference_Variables.
Outros métodos e propriedades
Para obter informações sobre os outros métodos e propriedades que podem ser acessados por meio da $PSCmdlet
variável , consulte System.Management.Automation.PSCmdlet.
Por exemplo, a propriedade ParameterSetName permite que você veja o conjunto de parâmetros que está sendo usado. Os conjuntos de parâmetros permitem que você crie uma função que executa tarefas diferentes com base nos parâmetros especificados quando a função é executada.