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 dos cmdlets.
Quando você usa o atributo, o CmdletBinding PowerShell adiciona automaticamente os Parâmetros Comuns. Você não pode criar parâmetros que usem os mesmos nomes que os Parâmetros comuns. Para obter mais informações, confira about_CommonParameters.
O PowerShell associa os parâmetros de funções que têm o CmdletBinding atributo da mesma forma que associa os parâmetros de 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âmetros falhe.
Observação
Os cmdlets compilados usam o atributo required Cmdlet , que é semelhante ao CmdletBinding atributo descrito neste tópico.
Sintaxe
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 padronizados como False quando omitidos do atributo CmdletBinding . Defina o valor do argumento como $true ou apenas liste o argumento pelo nome. Por exemplo, os atributos CmdletBinding a seguir 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 é Médio.) 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 conjunto de parâmetros usar. Você pode evitar esse problema tornando o parâmetro exclusivo de cada conjunto de parâmetros um parâmetro obrigatório.
AjudaURI
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.
SuportesPaginação
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 'n' objetos.
- Ignorar: Ignora os primeiros 'n' objetos e, em seguida, obtém os objetos restantes.
- IncludeTotalCount: relata o número de objetos no conjunto de dados (um número 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 da contagem total a ser retornado 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 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 os 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 da 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
