Compartilhar via

about_Functions_Advanced_Methods

  • Artigo

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 métodos e propriedades adicionais por meio da $PSCmdlet variável. Esses métodos incluem os seguintes métodos:

  • Os mesmos métodos de processamento de entrada disponíveis para todas as funções.
  • Os ShouldProcess métodos e ShouldContinue 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 atributo, consulte about_Functions_CmdletBindingAttributeCmdletBinding. 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. O PowerShell 7.3 adiciona um método de processo de clean bloco.

Você não é obrigado a usar nenhum desses blocos em suas funções. Se você não usar um bloco nomeado, o PowerShell colocará o end código no bloco da função. No entanto, se você usar qualquer um desses blocos nomeados ou definir um dynamicparam bloco, deverá colocar todo o código em um bloco nomeado.

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{}
    clean{}
}

Observação

Esses blocos se aplicam a todas as funções, não apenas às funções que usam o CmdletBinding atributo.

begin

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.

process

Esse bloco é usado para fornecer processamento registro por registro para a função. Você pode usar um process bloco sem definir os outros blocos. O número de execuções em bloco depende de process como você usa a função e qual entrada a função recebe.

A variável $_ automática or $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 do pipeline que atinge a função estiver vazia, o process bloco não será executado.
    • Os beginblocos , end, e clean 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 registro por registro falhará. Nesse caso, sua função será executada apenas uma vez, independentemente da entrada.

Quando você cria uma função que aceita entrada de pipeline e usa CmdletBinding, o process bloco deve usar a variável de parâmetro definida para entrada de pipeline em vez de $_ ou $PSItem. Por exemplo:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

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

clean

O clean bloco foi adicionado no PowerShell 7.3.

O bloco clean é uma forma conveniente para os usuários limparem os recursos que abrangem os blocos begin, process e end. Ele é semanticamente semelhante a um bloco finally que abrange todos os outros blocos nomeados de uma função de script ou um cmdlet de script. A limpeza de recursos é imposta para os seguintes cenários:

  1. quando a execução do pipeline termina normalmente sem erro de encerramento
  2. quando a execução do pipeline é interrompida devido a um erro de encerramento
  3. quando o pipeline é interrompido por Select-Object -First
  4. quando o pipeline está sendo interrompido por Ctrl+C ou StopProcessing()

O bloco clean descarta qualquer saída gravada no fluxo de sucesso .

Cuidado

Adicionar o bloco clean é uma alteração interruptiva. Como o clean é analisado como uma palavra-chave, ele impede que os usuários chamem diretamente um comando chamado clean como a primeira instrução em um bloco de script. No entanto, não é provável que seja um problema. O comando ainda pode ser invocado usando o operador de chamada (& clean).

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 altere o sistema. A função pode continuar com base no valor booleano 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 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.

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.

Detalhe do Comando Escrever

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.

Erro de gravação

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.

Progresso de gravação

Para funções com ações que levam muito tempo para serem concluídas, esse método permite que a função chame o método para que as WriteProgress 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.

Aviso de gravação

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 ao 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 variável, consulte about_Preference_Variables$WarningPreference.

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.

Confira também