about_Functions_Argument_Completion

  • Článek

Krátký popis

Dokončování argumentů je funkce PowerShellu, která poskytuje rady, umožňuje zjišťování a urychluje zadávání vstupních hodnot argumentů.

Dlouhý popis

Tento článek popisuje různé způsoby implementace dokončování argumentů pro funkce PowerShellu. Dokončování argumentů poskytuje možné hodnoty parametru. Dostupné hodnoty se počítají za běhu, když uživatel za názvem parametru stiskne klávesu Tab . Existuje několik způsobů, jak definovat dokončování argumentů pro parametr.

Poznámka:

Tab je výchozí klávesová vazba ve Windows. Tuto vazbu klíčů může změnit modul PSReadLine nebo aplikace, která je hostitelem PowerShellu. Vazby klíčů se liší na platformách jiných než Windows. Další informace najdete v tématu about_PSReadLine.

Atribut ValidateSet

Atribut ValidateSet určuje sadu platných hodnot pro parametr nebo proměnnou a povolí dokončování tabulátoru. PowerShell vygeneruje chybu, pokud parametr nebo hodnota proměnné neodpovídá hodnotě v sadě. V následujícím příkladu může být hodnota parametru Fruit pouze Apple, Banana nebo Pear.

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

V následujícím příkladu musí být hodnota proměnné $flavor Čokoláda, Strawberry nebo Vanilla. Atribut ValidateSet lze použít pro libovolnou proměnnou, nejen parametry.

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

K ověření dojde vždy, když je tato proměnná přiřazena i ve skriptu.

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

$Message = 'bye'

Tento příklad vrátí následující chybu za běhu:

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

Další informace o rozšíření karty najdete v tématu about_Tab_Expansion.

Dynamické hodnoty ValidateSet pomocí tříd

Třídu můžete použít k dynamickému generování hodnot pro ValidateSet za běhu. V následujícím příkladu jsou platné hodnoty pro proměnnou $Sound generovány prostřednictvím třídy s názvem SoundNames , která kontroluje tři cesty systému souborů pro dostupné zvukové soubory:

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
    }
}

Třída [SoundNames] se pak implementuje jako dynamická hodnota ValidateSet následujícím způsobem:

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

Poznámka:

Třída IValidateSetValuesGenerator byla představena v PowerShellu 6.0.

Atribut ArgumentCompletions

Atribut ArgumentCompletions umožňuje přidat hodnoty dokončení tabulátoru do konkrétního parametru. Atribut ArgumentCompletions musí být definován pro každý parametr, který vyžaduje dokončení tabulátoru. Atribut ArgumentCompletions je podobný validateSet. Oba atributy mají seznam hodnot, které se zobrazí, když uživatel po názvu parametru stiskne klávesu Tab . Na rozdíl od ValidateSet se ale hodnoty neověřují a podobně jako návrhy. Uživatel proto může zadat libovolnou hodnotu, nejen hodnoty v seznamu.

Atribut ArgumentCompletions by neměl být zaměňován s atributem ArgumentCompleter , který k definování možností potřebuje skriptblock. jsou k dispozici zadané hodnoty.

Syntaxe je následující:

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

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

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

Každý z parametrů poskytuje seznam možností atributu ArgumentCompletions pro povolení dokončování tabulátoru.

Tento atribut byl zaveden v PowerShellu 6.0.

Atribut ArgumentCompleter

Atribut ArgumentCompleter umožňuje přidat hodnoty dokončení tabulátoru do konkrétního parametru. Atribut ArgumentCompleter musí být definován pro každý parametr, který vyžaduje dokončení tabulátoru.

Pokud chcete přidat atribut ArgumentCompleter , musíte definovat blok skriptu, který určuje hodnoty. Blok skriptu musí obsahovat následující parametry v pořadí uvedeném níže. Na názvech parametru nezáleží, protože hodnoty jsou k dispozici pozičním umístěním.

Syntaxe je následující:

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

Blok skriptu ArgumentCompleter

Parametry bloku skriptu jsou nastavené na následující hodnoty:

  • $commandName (Pozice 0) – Tento parametr je nastaven na název příkazu, pro který blok skriptu poskytuje dokončování tabulátoru.
  • $parameterName (Pozice 1) – Tento parametr je nastaven na parametr, jehož hodnota vyžaduje dokončení tabulátoru.
  • $wordToComplete (Pozice 2) – Tento parametr je nastaven na hodnotu, kterou uživatel zadal před stisknutím klávesy Tab. Blok skriptu by měl tuto hodnotu použít k určení hodnot dokončení tabulátoru.
  • $commandAst (Pozice 3) – Tento parametr je nastavený na abstraktní strom syntaxe (AST) pro aktuální vstupní řádek. Další informace najdete v dokumentaci k typu AST .
  • $fakeBoundParameters (Pozice 4) – Tento parametr je nastavený na hashtable obsahující rutinu $PSBoundParameters před stisknutím klávesy Tab uživatele. Další informace najdete v tématu about_Automatic_Variables.

Blok skriptu ArgumentCompleter musí zrušit registraci hodnot pomocí kanálu, například ForEach-Object, Where-Objectnebo jiné vhodné metody. Vrácení pole hodnot způsobí, že PowerShell považuje celé pole za jednu hodnotu dokončení tabulátoru.

Následující příklad přidá dokončování tabulátoru do parametru Value . Pokud je zadán pouze parametr Value, zobrazí se pro hodnotu všechny možné hodnoty nebo argumenty. Pokud je zadán parametr Type, parametr Value zobrazí pouze možné hodnoty pro tento typ.

Operátor navíc zajistí, -like že pokud uživatel zadá následující příkaz a použije dokončování tabulátoru , vrátí se jenom Apple .

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
      )
}

Dokončování argumentů založených na třídách

Od PowerShellu 7.2 byla přidána nová funkce, která umožňuje definovat obecnější implementace parametrizovaných dokončování argumentů.

Odvozením z ArgumentCompleterAttribute, je možné vytvořit obecné completery, které lze opakovaně použít, například:

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

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

[GitCommits(Branch='release')]

Odvozené atributy musí implementovat IArgumentCompleterFactory rozhraní a používat hodnoty vlastností k vytvoření specializovaného completeru.

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) }
}

Využití z PowerShellu by pak bylo:

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

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

Register-ArgumentCompleter

Rutina Register-ArgumentCompleter zaregistruje vlastní dokončování argumentů. Dokončování argumentů umožňuje zadat dynamické dokončování tabulátoru za běhu pro libovolný zadaný příkaz.

Další informace naleznete v tématu Register-ArgumentCompleter.

Viz také