about_Functions_CmdletBindingAttribute

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

TÓPICO

about_Functions_CmdletBindingAttribute

DESCRIÇÃO BREVE

Descreve o atributo que faz com que uma função funcione como um cmdlet compilado.

DESCRIÇÃO LONGA

O atributo CmdletBinding é um atributo de funções que faz com que eles operem como cmdlets compilados que são escritos em C# e fornece acesso aos recursos dos cmdlets.

O Windows PowerShell® associa os parâmetros de funções que têm o atributo CmdletBinding da mesma maneira que associa os parâmetros de cmdlets compilado. A variável automática $PSCmdlet está disponível para as funções com o atributo CmdletBinding, mas a variável $Args não está disponível.

Em funções que têm o atributo CmdletBinding, parâmetros desconhecidos e argumentos posicionais com nenhuma correspondência de parâmetros posicionais fazem com que a associação de parâmetro falhe.

Observação: Cmdlets compilados usam o atributo necessário do Cmdlet, que é semelhante ao atributo CmdletBinding descrito neste tópico.

SINTAXE

O exemplo a seguir mostra o formato de uma função que especifica todos os argumentos opcionais do atributo CmdletBinding. Uma breve descrição de cada argumento segue este exemplo.

        {
          [CmdletBinding(ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>,
                     HelpURI=<URI>,
                     SupportsPaging=<Boolean>,
                     SupportsShouldProcess=<Boolean>,
                     PositionalBinding=<Boolean>)]

          Param ($Parameter1)
          Begin{}
          Process{}
          End{}
        }

ConfirmImpact

O argumento ConfirmImpact especifica quando a ação da função deve ser confirmada por uma chamada para o método ShouldProcess. A chamada para o método ShouldProcess exibe um prompt de confirmação somente quando o argumento ConfirmImpact é igual ou maior que o valor da variável $ConfirmPreference de preferência. (O valor padrão do argumento é médio.) Especifique esse argumento somente quando o argumento SupportsShouldProcess também for especificado.

Para mais informações sobre as solicitações de confirmação, consulte "Solicitação de confirmação" na biblioteca MSDN (Microsoft Developer Network) em https://go.microsoft.com/fwlink/?LinkId=136658.

DefaultParameterSetName

O argumento DefaultParameterSetName especifica o nome do conjunto de parâmetros que Windows PowerShell tentará usar quando não for possível determinar qual parâmetro definido deverá ser usado. Você pode evitar esse problema fazendo com que o parâmetro exclusivo de cada parâmetro defina um parâmetro obrigatório.

HelpURI

O argumento HelpURI especifica o endereço da Internet (URI (Uniform Resource Identifier)) da versão online do tópico de ajuda que descreve a função. O valor do argumento HelpURI deve começar com "http" ou "https".

O valor do argumento HelpURI é usado para o valor da propriedade HelpURI do objeto CommandInfo que Get-Command retorna para a função.

No entanto, quando os arquivos de ajuda são instalados no computador e o valor do primeiro link na seção RelatedLinks do arquivo de ajuda é uma URI ou o valor do primeiro, a diretiva .Link na ajuda baseada em comentários é uma URI, e a URI no arquivo de ajuda é usada como o valor da propriedade HelpUri da função.

O cmdlet Get-Help usa o valor da propriedade HelpURI para localizar a versão online do tópico de ajuda de função quando o parâmetro de Get-Help online é especificado em um comando.

SupportsPaging

O argumento SupportsPaging adiciona os parâmetros First, Skip e IncludeTotalCount na função. Esses parâmetros permitem que os usuários selecionem a saída de um conjunto de resultados muito grandes. Esse argumento foi projetado para cmdlets e funções que retornam dados de armazenamentos de dados grandes que dão suporte à seleção de dados, como um banco de dados SQL.

Este argumento foi introduzido no Windows PowerShell 3.0.

Primeiro:

Obtém somente os primeiros objetos 'n'.

Ignorar:

Ignora os primeiros objetos 'n' e, em seguida, obtém os objetos restantes.

IncludeTotalCount:

Informa o número de objetos no conjunto de dados (um inteiro) seguido pelos objetos. Se o cmdlet não pode determinar a contagem total, ele retornará "Contagem total desconhecida".

O Windows PowerShell inclui NewTotalCount, um método auxiliar que obtém o valor da contagem total para retornar e inclui uma estimativa da precisão do valor da contagem total.

A função de exemplo a seguir mostra como adicionar suporte para os parâmetros de paginação para uma função avançada.

         function Get-Numbers
         {
             [CmdletBinding(SupportsPaging = $true)]
             param()

             $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
             $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100)

             if ($PSCmdlet.PagingParameters.IncludeTotalCount)
             {
                 $TotalCountAccuracy = 1.0
                 $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy)
                 Write-Output $TotalCount
             }
             $FirstNumber .. $LastNumber | Write-Output
         }

SupportsShouldProcess

O argumento SupportsShouldProcess adiciona os parâmetros Confirm e WhatIf à função. O parâmetro Confirm avisa o usuário antes de executar o comando em cada objeto no pipeline. O parâmetro WhatIf lista as alterações que o comando faria, em vez de executar o comando.

PositionalBinding

O argumento PositionalBinding determina se os parâmetros da função são posicionais por padrão. O valor padrão é $True. Você pode usar o argumento PositionalBinding com um valor de $False para desabilitar a associação posicional.

O argumento PositionalBinding é apresentado no Windows PowerShell3.0.

Quando os parâmetros são posicionais, o nome do parâmetro é opcional. O Windows PowerShell associa valores de parâmetro não nomeados com os parâmetros de função, de acordo com a ordem ou posição dos parâmetros de valor não nomeados no comando de função.

Quando os parâmetros não são posicionais (eles são "nomeados"), o nome do parâmetro (ou uma abreviação ou alias do nome) é necessária no comando.

Quando PositionalBinding é $True, os parâmetros de função são posicionais por padrão. O Windows PowerShell alinha o número da posição com os parâmetros na ordem em que eles foram declarados na função.

Quando PositionalBinding for $False, os parâmetros de função não são posicionais por padrão. A menos que o argumento Position do atributo de parâmetro for declarado no parâmetro, o nome do parâmetro (ou um alias ou abreviação) deve ser incluído quando o parâmetro é usado em uma função.

O argumento Position do atributo de parâmetro tem precedência sobre o valor padrão de PositionalBinding. Você pode usar o argumento Position para especificar um valor de posição para um parâmetro. Para obter mais informações sobre o argumento Position, consulte about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).

OBSERVAÇÕES

Não há suporte para o argumento SupportsTransactions em funções avançadas.

PALAVRAS-CHAVE

about_Functions_CmdletBinding_Attribute

CONSULTE TAMBÉM

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute