about_Functions_CmdletBindingAttribute
Descrição breve
Descreve o atributo que faz uma função funcionar como um cmdlet compilado.
Descrição longa
O CmdletBinding atributo é um atributo de funções que as faz operar como cmdlets compilados escritos em C#. Ele fornece acesso aos recursos de cmdlets.
O PowerShell associa os parâmetros de funções que têm o CmdletBinding atributo da mesma forma que associa os parâmetros dos cmdlets compilados. A $PSCmdlet variável automática está disponível para funções com o CmdletBinding atributo , mas a $Args variável não está disponível.
Em funções que têm o CmdletBinding atributo , parâmetros desconhecidos e argumentos posicionais que não têm parâmetros posicionais correspondentes fazem com que a associação de parâmetro falhe.
Observação
Os cmdlets compilados usam o atributo necessário Cmdlet , que é semelhante ao CmdletBinding atributo descrito neste tópico.
Syntax
O exemplo a seguir mostra o formato de uma função que especifica todos os argumentos opcionais do CmdletBinding atributo. 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{}
}
Os tipos de argumento booliano do atributo CmdletBinding são padrão para False quando omitidos do atributo CmdletBinding . Defina o valor do argumento como $true ou apenas liste o argumento por nome. Por exemplo, os seguintes atributos CmdletBinding são equivalentes.
{
[CmdletBinding(SupportsPaging=$true)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
# Boolean arguments can be defined using this shorthand syntax
{
[CmdletBinding(SupportsPaging)]
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 de $ConfirmPreference preferência. (O valor padrão do argumento é Medium.) Especifique esse argumento somente quando o argumento SupportsShouldProcess também for especificado.
Para obter mais informações sobre solicitações de confirmação, consulte Solicitando confirmação.
DefaultParameterSetName
O argumento DefaultParameterSetName especifica o nome do conjunto de parâmetros que o PowerShell tentará usar quando não puder determinar qual parâmetro deve 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 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 é um URI ou o valor da primeira .Link diretiva na ajuda baseada em comentários é um URI, o URI no arquivo de ajuda é usado como o valor da propriedade HelpUri da função.
O Get-Help cmdlet usa o valor da propriedade HelpURI para localizar a versão online do tópico de ajuda da função quando o parâmetro Online de Get-Help é especificado em um comando.
SupportsPaging
O argumento SupportsPaging adiciona os parâmetros First, Skip e IncludeTotalCount à função . Esses parâmetros permitem que os usuários selecionem a saída de um conjunto de resultados muito grande. Esse argumento foi projetado para cmdlets e funções que retornam dados de grandes armazenamentos de dados que dão suporte à seleção de dados, como um banco de dados SQL.
Esse argumento foi introduzido no Windows PowerShell 3.0.
- Primeiro: obtém apenas os primeiros objetos 'n'.
- Ignorar: ignora os primeiros objetos 'n' e, em seguida, obtém os objetos restantes.
- IncludeTotalCount: relata o número de objetos no conjunto de dados (um inteiro) seguido pelos objetos. Se o cmdlet não puder determinar a contagem total, ele retornará "Contagem total desconhecida".
O PowerShell inclui NewTotalCount, um método auxiliar que obtém o valor de contagem total a ser retornado e inclui uma estimativa da precisão do valor total da contagem.
A função de exemplo a seguir mostra como adicionar suporte para os parâmetros de paginação a uma função avançada.
function Get-Numbers {
[CmdletBinding(SupportsPaging)]
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 parâmetros Confirm e WhatIf à função. O parâmetro Confirm solicita ao 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 na 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 é introduzido no Windows PowerShell 3.0.
Quando os parâmetros são posicionais, o nome do parâmetro é opcional. O PowerShell associa valores de parâmetro sem nome aos parâmetros de função de acordo com a ordem ou posição dos valores de parâmetro sem nome 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ário no comando .
Quando PositionalBinding é $True, os parâmetros de função são posicionais por padrão. O PowerShell atribui o número de posição aos parâmetros na ordem em que eles são declarados na função.
Quando PositionalBinding é $False, os parâmetros de função não são posicionais por padrão. A menos que o argumento Position do atributo Parameter seja 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 Parameter tem precedência sobre o valor padrão 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.
Observações
Não há suporte para o argumento SupportsTransactions em funções avançadas.
Palavras-chave
about_Functions_CmdletBinding_Attribute