Partilhar via

about_Funções_Avançadas_Métodos

Breve descrição

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

Descrição longa

As funções que especificam o atributo CmdletBinding podem acessar métodos e propriedades adicionais por meio da variável $PSCmdlet. Esses métodos incluem os seguintes métodos:

  • Os mesmos métodos de processamento de entrada disponíveis para todas as funções.
  • Os métodos ShouldProcess e ShouldContinue usados para obter comentários do usuário antes que uma ação seja executada.
  • O método ThrowTerminatingError para gerar registros de erro.
  • Vários métodos Write 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 CmdletBinding, 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 blocos begin, processe end da função. O PowerShell 7.3 introduz um método de processamento de bloco clean.

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 código no bloco end da função. No entanto, se você usar qualquer um desses blocos nomeados, ou definir um bloco dynamicparam, você deve colocar todo o código em um bloco nomeado.

O exemplo a seguir mostra o esquema de uma função que contém um bloco begin para pré-processamento único, um bloco process para processamento de vários registos, e um bloco end 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 atributo CmdletBinding.

begin

Este bloco é usado para fornecer pré-processamento único opcional para a função. O runtime do PowerShell utiliza o código neste bloco uma vez para cada instância da função no pipeline.

process

Este bloco é usado para fornecer processamento registro a registro para a função. Você pode usar um bloco process sem definir os outros blocos. O número de execuções de bloco de process 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 usar no bloco process. A $input variável automática contém um enumerador disponível apenas para funções e blocos de script. Para obter mais informações, consulte sobre_Variáveis_Automáticas.

  • Chamar a função no início do processo, ou fora de um pipeline, executa o bloco process apenas uma vez.
  • Dentro de um pipeline, o bloco process é 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 bloco processnão é executado.
    • Os blocos begin, ende clean ainda são executados.

Importante

Se um parâmetro de função for definido para aceitar entrada de pipeline e um bloco de process não estiver definido, o processamento registro a registro falhará. Neste caso, a sua função só será executada uma vez, independentemente da entrada.

Quando você cria uma função que aceita entrada de pipeline e usa CmdletBinding, o bloco process 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

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

clean

O bloco clean foi adicionado no PowerShell 7.3.

O bloco clean é uma maneira conveniente para os usuários limparem recursos que abrangem os blocos begin, processe end. É semanticamente semelhante a um bloco finally que abrange todos os outros blocos nomeados de uma função de script ou de 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 gasoduto é interrompido por Select-Object -First
  4. quando o pipeline está a ser interrompido por Ctrl+c ou StopProcessing()

O bloco clean descarta qualquer saída escrita no stream Success.

Atenção

Adicionar o bloco clean é uma mudança significativa. Por clean ser analisada como palavra-chave, impede os utilizadores de chamar diretamente um comando nomeado clean como primeira instrução num 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

Deve Processar

Este 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 booleano retornado pelo método. Este método só pode ser chamado de dentro do bloco process {} da função. O atributo CmdletBinding também deve declarar que a função suporta ShouldProcess (como 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.

Deve Continuar

Este método é chamado para solicitar uma segunda mensagem de confirmação. Ele 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.

Métodos de erro

As funções podem chamar dois métodos diferentes quando ocorrem erros. Quando ocorre um erro não terminal, a função deve chamar o método WriteError, que é descrito na seção de métodos Write. Quando ocorre um erro de encerramento e a função não pode continuar, ele 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 não terminativos.

Para obter mais informações, consulte System.Management.Automation.Cmdlet.ThrowTerminatingError.

Métodos de escrita

Uma função pode chamar os seguintes métodos 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 cmdlets Write, como Write-Error.

EscreverDetalheComando

Para obter informações sobre o método WriteCommandDetails, 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 método WriteDebug. O método WriteDebug 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 este método quando ocorrerem erros não terminais e a função estiver desenvolvida para continuar a processar registos. Para obter mais informações, consulte System.Management.Automation.Cmdlet.WriteError.

Observação

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

WriteObject

O método WriteObject 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 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.

EscreverVerbose

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, mensagens detalhadas não são exibidas. Para obter mais informações, consulte System.Management.Automation.PSCmdlet.WriteVerbose.

EscreverAviso

Para fornecer informações sobre 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.

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. Para obter mais informações sobre a variável $WarningPreference, 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 variável $PSCmdlet, 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 criar uma função que executa tarefas diferentes com base nos parâmetros especificados quando a função é executada.

Consulte também

  • Last updated on