TÓPICO
about_Functions_Advanced_Methods
DESCRIÇÃO RESUMIDA
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
vários métodos e propriedades pela variável $ pscmdlet. Esses métodos
incluem:
- Métodos de processamento de entrada que cmdlets compilados
usam para fazer seu trabalho.
- Os métodos ShouldProcess e ShouldContinue que são usados
para obter comentários de usuário antes de uma ação ser
executada.
- O método ThrowTerminatingError para gerar registros de erro.
- Vários métodos de gravação que retornam tipos diferentes de
saída.
- Vários métodos de gravação 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 do 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, estes 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 quando estiver
executando uma função. (Esses blocos também estão disponíveis a
funções que não usam o atributo CmdletBinding.)
Begin
Esse bloco é usado para fornecer um único pré-processamento
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 pré-processamento, registro
por registro, para a função. Esse bloco pode ser usado várias
vezes, ou não, 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 receber do pipeline. Se não
houver nenhuma entrada do pipeline, o bloco Process não será usado.
Esse bloco deve ser definido se um parâmetro de função for
definido para aceitar entrada do pipeline. Se esse bloco não
for definido e o parâmetro aceitar entrada do pipeline, a
função perderá os valores que são transmitidos pelo pipeline.
Além disso, quando a função aceita solicitações de confirmação
(quando o parâmetro SupportsShouldProcess do atributo Parameter
é definido como $True), a chamada ao método ShouldProcess deve
ser feita do bloco Process.
End
Esse bloco é usado para fornecer um único prós-processamento
opcional para a função.
O exemplo a seguir mostra a estrutura de tópicos de uma função
que contém um bloco Begin para um único pré-processamento, um bloco
Process para vários processamento de registro e um bloco End para um
único pós-processamento.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
Métodos de confirmação
ShouldProcess
Este método é chamado para solicitar confirmação do usuário
antes de a função executar uma ação que alteraria o sistema.
A função pode continuar baseada no valor Booleano retornado pelo
método. Esse método só pode ser chamado do bloco Process{} da
função. E o atributo CmdletBinding deve declarar que a função
dá suporte a ShouldProcess (como mostrado no exemplo anterior).
Para obter mais informações sobre este método, consulte
System.Management.Automation.Cmdlet.ShouldProcess na biblioteca
do MSDN em https://go.microsoft.com/fwlink/?LinkId=142142.
Para obter mais informações sobre como solicitar confirmação,
consulte "Pedindo confirmação" na biblioteca do MSDN em
https://go.microsoft.com/fwlink/?LinkID=136658.
ShouldContinue
Esse 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 na
biblioteca do MSDN em https://go.microsoft.com/fwlink/?LinkId=142143.
Métodos de erro
As funções podem chamar dois métodos diferentes quando ocorrerem
erros. Durante um erro de nonterminating, a função deve chamar o
método WriteError que é descrito na seção "Métodos de gravação".
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 de nonterminating.
Para obter mais informações, consulte System.Management.Automation.Cmdlet.
ThrowTerminatingError na biblioteca do MSDN em
https://go.microsoft.com/fwlink/?LinkId=142144.
Métodos de gravação
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 os vários cmdlets de
gravação, como Write-Error.
WriteCommandDetail
Para obter mais informações sobre o método WriteCommandDetails,
consulte System.Management.Automation.Cmdlet.WriteCommandDetail na
biblioteca do 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 chamada de função do método
WriteDebug. Isso exibe mensagens de depuração ao usuário. Para
obter mais informações, consulte
System.Management.Automation.Cmdlet.WriteDebug na biblioteca do MSDN em
https://go.microsoft.com/fwlink/?LinkId=142156.
WriteError
As funções devem chamar esse método quando ocorrem erros
nonterminating e a função é criada para continuar processando
os registros. Para obter mais informações, consulte
System.Management.Automation.Cmdlet.WriteError na biblioteca do MSDN em
https://go.microsoft.com/fwlink/?LinkId=142157.
Observação: se ocorrer um erro de encerramento, a função não
deverá chamar o método ThrowTerminatingError.
WriteObject
Esse método permite que a função envie um objeto ao 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
do 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 à função chamar o método
WriteProgress de forma 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 do 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 a chamada de função do método WriteVerbose para exibir
mensagens detalhadas ao usuário. Por padrão, não são exibidas mensagens
detalhadas. Para obter mais informações, consulte
System.Management.Automation.PSCmdlet.WriteVerbose na biblioteca do
MSDN em https://go.microsoft.com/fwlink/?LinkId=142162.
WriteWarning
Para fornecer informações sobre condições que podem causar
resultados inesperados, faça a chamada de função do 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 na
biblioteca do 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 outros métodos e propriedades
que podem ser acessados pela variável $PSCmdlet, consulte
System.Management.Automation.PSCmdlet na biblioteca do MSDN em
https://go.microsoft.com/fwlink/?LinkId=142139.
Por exemplo, a propriedade ParameterSetName lhe permite consultar 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
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters