about_Functions_CmdletBindingAttribute

Artigo
07/02/2024

Breve descrição

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. Não é possível criar parâmetros que usem os mesmos nomes que os Parâmetros Comuns. Para obter mais informações, consulte about_CommonParameters.

O PowerShell vincula os parâmetros de funções que têm o CmdletBinding atributo da mesma forma que vincula 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 vinculação de parâmetros falhe.

Nota

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 booleano do atributo CmdletBinding padrão para False quando omitido 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{}
}

ConfirmarImpacto

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.

HelpURI

O argumento HelpURI especifica o endereço Internet da versão online do tópico da 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.

SuportesPaging

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 oferecem 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 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 total da contagem para retornar 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
}

ApoiosDevemProcesso

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 executá-lo.

PositionalBinding

O argumento PositionalBinding determina se os parâmetros na função são posicionais por padrão. O valor predefinido é $True. Você pode usar o argumento PositionalBinding com um valor de $False para desabilitar a vinculaçã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âmetros sem nome aos parâmetros de função de acordo com a ordem ou posição dos valores de parâmetros sem nome no comando function.

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 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 abreviatura) 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.

Partilhar via