about_Functions_Argument_Completion

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

tabulátoru je výchozí vazba kláves 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 umožňuje 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, Banananebo 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 buď Chocolate, Strawberrynebo 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 naleznete v tématu about_Tab_Expansion.

Dynamické hodnoty ValidateSet pomocí tříd

Pomocí class můžete dynamicky generovat hodnoty pro ValidateSet za běhu. V následujícím příkladu se platné hodnoty pro proměnnou $Sound generují prostřednictvím class pojmenovaného 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čování 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ý atributu ValidateSet. Oba atributy přebírají seznam hodnot, které se zobrazí, když uživatel stiskne Tab za názvem parametru. 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 blok skriptu. 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í ArgumentCompletions atribut 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 skriptblock, který určuje hodnoty. Skriptblock musí mít 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
    )
}

ArgumentCompleter scriptblock

Parametry scriptblock jsou nastaveny na následující hodnoty:

$commandName (Pozice 0) – Tento parametr je nastaven na název příkazu, pro který skriptblock 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. Skriptblock by měl tuto hodnotu použít k určení hodnot dokončení tabulátoru.
$commandAst (Position 3) – Tento parametr je nastaven na strom abstraktní 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í $PSBoundParameters rutiny, a teprve potom uživatel stiskl Tab. 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 Hodnota, zobrazí se všechny možné hodnoty nebo argumenty pro Hodnota. Pokud je zadán parametr Typ, parametr Hodnota zobrazí pouze možné hodnoty pro daný typ.

Kromě toho operátor -like zajišťuje, že pokud uživatel zadá následující příkaz a použije Tabulátor dokončení, vrátí se pouze 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 ArgumentCompleterAttributeje možné vytvořit obecné completery, které lze opakovaně použít, například:

[DirectoryCompleter(ContainingFile="pwsh.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é

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-01-19