Sobre métodos avançados de funções

Artigo
06/21/2023

Descrição breve

Descreve como as funções que especificam o CmdletBinding atributo podem usar os métodos e as propriedades 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 realizar seu trabalho.
Os ShouldProcess métodos e ShouldContinue 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 Beginblocos , Processe 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 neste 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 bloco depende de Process 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 e End ainda são executados.

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

Usar 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 a 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 é compatível 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 terminação, a função deve chamar o WriteError método , que é descrito na Write seção 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 terminação.

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 terminação 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, 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.