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