about_Functions_Argument_Completion

Descrição curta

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

Descrição longa

Este artigo descreve as diferentes maneiras de implementar completadores de argumentos para funções do PowerShell. Os concluidores de argumento fornecem os valores possíveis para um parâmetro. Os valores disponíveis são calculados em runtime quando o usuário pressiona a tecla Tab após o nome do parâmetro. Há várias maneiras de definir um concluídor de argumento para um parâmetro.

Nota

Tab é a associação de chave padrão no Windows. Essa associação de chaves pode ser alterada pelo módulo PSReadLine ou pelo aplicativo que está hospedando o PowerShell. A associação de chaves é diferente em plataformas que não são do Windows. Para obter mais informações, consulte about_PSReadLine.

Atributo ValidateSet

O atributo ValidateSet especifica um conjunto de valores válidos para um parâmetro ou variável e permite a conclusão da guia. O PowerShell gerará 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, Bananaou Pear.

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

No exemplo a seguir, o valor da variável $flavor deve ser de Chocolate, de Morango ou de Baunilha. O atributo ValidateSet 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 runtime:

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 de ValidateSet Dinâmico usando classes

Você pode usar um class para gerar dinamicamente os valores para ValidateSet em runtime. No exemplo a seguir, os valores válidos para a variável $Sound são gerados por meio de um class chamado 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 [SoundNames] é então implementada como um valor ValidateSet dinâmico da seguinte maneira:

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

Nota

A classe IValidateSetValuesGenerator foi introduzida no PowerShell 6.0.

Atributo ArgumentCompletions

O atributo ArgumentCompletions permite adicionar valores de conclusão de guia a um parâmetro específico. Um atributo ArgumentCompletions deve ser definido para cada parâmetro que precisa de conclusão da guia. O atributo ArgumentCompletions é semelhante ao ValidateSet. Ambos os atributos levam 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 recebe uma lista de opções para o atributo ArgumentCompletions para habilitar a conclusão da guia.

Esse atributo foi introduzido no PowerShell 6.0.

Atributo ArgumentCompleter

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

Para adicionar um atributo ArgumentCompleter , você precisa definir um scriptblock que determine os valores. O scriptblock deve usar os seguintes parâmetros na ordem especificada abaixo. Os nomes do parâmetro 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
    )
}

Scriptblock argumentCompleter

Os parâmetros do scriptblock são definidos para os seguintes valores:

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

O scriptblock ArgumentCompleter deve cancelar o registro dos valores usando o pipeline, como ForEach-Object, Where-Objectou outro método adequado. Retornar uma matriz de valores faz com que o PowerShell trate toda a matriz como um valor de conclusão da guia.

O exemplo a seguir adiciona a conclusão da guia 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 -like garante que, se o usuário digitar o comando a seguir e usar Tab conclusão, somente Apple será retornado.

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 concluidores 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 interface IArgumentCompleterFactory e usar valores de propriedade para criar um concluídor 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 cmdlet Register-ArgumentCompleter registra um concluídor de argumento personalizado. Um concluídor de argumento permite que você forneça a conclusão da guia dinâmica em tempo de execução para qualquer comando especificado.

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

Consulte também

Comentários

Esta página foi útil?

Last updated on 2026-01-19