about_Functions_Argument_Completion

Breve descrição

A conclusão de argumentos é 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 de implementar preenchedores de argumento para funções do PowerShell. Os completadores de argumentos 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 preenchedor 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 guias. O PowerShell gera um erro se um parâmetro ou valor de 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 de guias, consulte about_Tab_Expansion.

Valores Dynamic 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 [SoundNames] classe é então implementada como um valor ValidateSet dinâmico da seguinte maneira:

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

Atributo ArgumentCompletions

O atributo ArgumentCompletions permite adicionar valores de conclusão de tabulação a um parâmetro específico. Um atributo ArgumentCompletions deve ser definido para cada parâmetro que precisa ser preenchido com 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 é 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 é fornecida uma lista de opções para o atributo ArgumentCompletions para habilitar o preenchimento de guias.

Esse atributo foi introduzido no PowerShell 6.0.

Atributo ArgumentCompleter

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

Para adicionar um atributo ArgumentCompleter , você precisa definir um bloco de script que determine os valores. O bloco de script deve ter 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 é 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 preenchimento de tabulação.
• $parameterName (Posição 1) - Este parâmetro é definido como o parâmetro cujo valor requer preenchimento de tabulação.
• $wordToComplete (Posição 2) - Este parâmetro é definido para o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar os valores de conclusão 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) – Este parâmetro está definido para uma tabela hash que contenha o cmdlet $PSBoundParameters, antes de o utilizador premir a Tecla de Tabulação. Para obter mais informações, veja about_Automatic_Variables.

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

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 operador garante que, se o usuário digitar o seguinte comando e usar a conclusão de tabulação, apenas a -like 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
      )
}

Conclusores 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 preenchedores de argumentos parametrizados.

Ao derivar do 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 completo 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 completo de argumento personalizado. Um completador de argumentos permite que você forneça preenchimento dinâmico de guias, em tempo de execução, para qualquer comando que você especificar.

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

Consulte também

• about_Functions_Advanced_Parameters
• about_Tab_Expansion
• Register-ArgumentCompleter