about_Functions_Argument_Completion

Descrição breve

A conclusão de argumento é um recurso do PowerShell que fornece dicas, permite a descoberta e acelera a entrada de entrada de valores de argumento.

Descrição longa

Este artigo descreve as diferentes maneiras pelas quais você pode implementar complementadores de argumento para funções do PowerShell. Os complementadores de argumento fornecem os valores possíveis para um parâmetro. Os valores disponíveis são calculados em tempo de execução quando o usuário pressiona a tecla Tab após o nome do parâmetro. Há várias maneiras de definir um completador de argumento para um parâmetro.

Atributo ValidateSet

O atributo ValidateSet especifica um conjunto de valores válidos para um parâmetro ou variável e permite o preenchimento de tabulação. O PowerShell gerará um erro se um valor de parâmetro ou variável não corresponder a um valor no conjunto. No exemplo a seguir, o valor do parâmetro Fruit só pode ser Apple, Banana ou Pear.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet('Apple', 'Banana', 'Pear')]
    [string[]]
    $Fruit
)

No exemplo a seguir, o valor da variável $flavor deve ser Chocolate, Morango ou Baunilha. O ValidateSet atributo pode ser usado em qualquer variável, não apenas em parâmetros.

[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'

A validação ocorre sempre que essa variável é atribuída mesmo dentro do script.

Param(
    [ValidateSet('hello', 'world')]
    [string]$Message
)

$Message = 'bye'

Este exemplo retorna o seguinte erro em tempo de execução:

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

Para obter mais informações sobre a expansão da guia, consulte about_Tab_Expansion.

Valores dinâmicos de ValidateSet usando classes

Você pode usar uma classe para gerar dinamicamente os valores para ValidateSet em tempo de execução. No exemplo a seguir, os valores válidos para a variável $Sound são gerados por meio de uma classe chamada SoundNames que verifica três caminhos do sistema de arquivos para arquivos de som disponíveis:

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
                      '/Library/Sounds',
                      '~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

A classe é então implementada [SoundNames] como um valor dinâmico ValidateSet da seguinte maneira:

Param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Atributo ArgumentCompletions

O atributo ArgumentCompletions permite adicionar valores de preenchimento de tabulação a um parâmetro específico. Um atributo ArgumentCompletions deve ser definido para cada parâmetro que precisa de preenchimento de tabulação. O atributo ArgumentCompletions é semelhante a ValidateSet. Ambos os atributos usam uma lista de valores a serem apresentados quando o usuário pressiona Tab após o nome do parâmetro. No entanto, ao contrário de ValidateSet, os valores não são validados e mais como sugestões. Portanto, o usuário pode fornecer qualquer valor, não apenas os valores na lista.

O atributo ArgumentCompletions não deve ser confundido com o atributo ArgumentCompleter , que precisa de um scriptblock para definir as opções. os valores especificados estão disponíveis

A sintaxe dela é a seguinte:

function Test-ArgumentCompletions {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ArgumentCompletions('Fruits', 'Vegetables')]
        $Type,

        [Parameter()]
        [ArgumentCompletions('Apple', 'Banana', 'Orange')]
        $Fruit,

        [Parameter()]
        [ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
        $Vegetable
    )
}

Cada um dos parâmetros recebe uma lista de opções para o atributo ArgumentCompletions para habilitar o preenchimento de tabulação.

Esse atributo foi introduzido no PowerShell 6.0.

Atributo ArgumentCompleter

O atributo ArgumentCompleter permite adicionar valores de preenchimento de tabulação a um parâmetro específico. Um atributo ArgumentCompleter deve ser definido para cada parâmetro que precisa de preenchimento de tabulação.

Para adicionar um atributo ArgumentCompleter , você precisa definir um bloco de script que determina os valores. O bloco de script deve usar os seguintes parâmetros na ordem especificada abaixo. Os nomes dos parâmetros não importam, pois os valores são fornecidos posicionalmente.

A sintaxe dela é a seguinte:

function MyArgumentCompleter {
    Param(
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )
            # Perform calculation of tab completed values here.
        } )]
        $ParamName
    )
}

Bloco de script ArgumentCompleter

Os parâmetros do bloco de script são definidos com os seguintes valores:

• $commandName (Posição 0) - Este parâmetro é definido como o nome do comando para o qual o bloco de script está fornecendo o preenchimento da guia.
• $parameterName (Posição 1) - Este parâmetro é definido como o parâmetro cujo valor requer o preenchimento da tabulação.
• $wordToComplete (Posição 2) - Este parâmetro é definido como o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar os valores de preenchimento de tabulação.
• $commandAst (Posição 3) - Este parâmetro é definido como a Árvore de Sintaxe Abstrata (AST) para a linha de entrada atual. Para obter mais informações, consulte a documentação do tipo AST .
• $fakeBoundParameters (Posição 4) – esse parâmetro é definido como uma tabela de hash que contém o $PSBoundParameters cmdlet para o cmdlet, antes que o usuário pressione Tab. Para obter mais informações, consulte about_Automatic_Variables.

O bloco de script ArgumentCompleter deve desenrolar os valores usando o pipeline, como ForEach-Object, Where-Object, ou outro método adequado. Retornar uma matriz de valores faz com que o PowerShell trate toda a matriz como um valor de conclusão de tabulação.

O exemplo a seguir adiciona o preenchimento de tabulação ao parâmetro Value . Se apenas o parâmetro Value for especificado, todos os valores ou argumentos possíveis para Value serão exibidos. Quando o parâmetro Type é especificado, o parâmetro Value exibe apenas os valores possíveis para esse tipo.

Além disso, o -like operador garante que, se o usuário digitar o comando a seguir e usar a conclusão de tabulação , somente a Apple será retornada.

Test-ArgumentCompleter -Type Fruits -Value A

function MyArgumentCompleter{
    param ( $commandName,
            $parameterName,
            $wordToComplete,
            $commandAst,
            $fakeBoundParameters )

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Onion', 'Carrot', 'Lettuce')
    }

    if ($fakeBoundParameters.ContainsKey('Type')) {
        $possibleValues[$fakeBoundParameters.Type] | Where-Object {
            $_ -like "$wordToComplete*"
        }
    } else {
        $possibleValues.Values | ForEach-Object {$_}
    }
}

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,

        [Parameter(Mandatory=$true)]
        [ArgumentCompleter({ MyArgumentCompleter @args })]
        $Value
      )
}

Concluidores de argumentos baseados em classe

A partir do PowerShell 7.2, foi adicionado um novo recurso que permite definir implementações mais genéricas de completadores de argumentos parametrizados.

Ao derivar de ArgumentCompleterAttribute, é possível criar completadores genéricos que podem ser reutilizados, por exemplo:

[DirectoryCompleter(ContainingFile="pwsh.exe", Depth=2)]

[DateCompleter(WeekDay='Monday', From="LastYear")]

[GitCommits(Branch='release')]

Os atributos derivados devem implementar a IArgumentCompleterFactory interface e usar valores de propriedade para criar um completador especializado.

using namespace System.Collections
using namespace System.Collections.Generic
using namespace System.Management.Automation
using namespace System.Management.Automation.Language

class NumberCompleter : IArgumentCompleter {

    [int] $From
    [int] $To
    [int] $Step

    NumberCompleter([int] $from, [int] $to, [int] $step) {
        if ($from -gt $to) {
            throw [ArgumentOutOfRangeException]::new("from")
        }
        $this.From = $from
        $this.To = $to
        $this.Step = $step -lt 1 ? 1 : $step
    }

    [IEnumerable[CompletionResult]] CompleteArgument(
        [string] $CommandName,
        [string] $parameterName,
        [string] $wordToComplete,
        [CommandAst] $commandAst,
        [IDictionary] $fakeBoundParameters) {

        $resultList = [List[CompletionResult]]::new()
        $local:to = $this.To
        $local:step = $this.Step
        for ($i = $this.From; $i -lt $to; $i += $step) {
            $resultList.Add([CompletionResult]::new($i.ToString()))
        }

        return $resultList
    }
}

class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {
    [int] $From
    [int] $To
    [int] $Step

    NumberCompletionsAttribute([int] $from, [int] $to, [int] $step) {
        $this.From = $from
        $this.To = $to
        $this.Step = $step
    }

    [IArgumentCompleter] Create() { return [NumberCompleter]::new($this.From, $this.To, $this.Step) }
}

O uso do PowerShell seria:

function Add{
    param(
       [NumberCompletions(0, 100, 5)]
       [int] $X,

       [NumberCompletions(0, 100, 5)]
       [int] $Y
    )
    $X + $Y
}

Register-ArgumentCompleter

O Register-ArgumentCompleter cmdlet registra um completador de argumento personalizado. Um completador de argumentos permite que você forneça o preenchimento dinâmico de tabulação, em tempo de execução para qualquer comando especificado.

Para obter mais informações, consulte Register-ArgumentCompleter.

Confira também

• about_Functions_Advanced_Parameters
• about_Tab_Expansion
• Register-ArgumentCompleter