about_Functions_Argument_Completion

Artykuł
10/04/2023

Krótki opis

Uzupełnianie argumentów to funkcja programu PowerShell, która udostępnia wskazówki, umożliwia odnajdywanie i przyspiesza wprowadzanie wartości argumentów.

Długi opis

W tym artykule opisano różne sposoby implementowania uzupełniania argumentów dla funkcji programu PowerShell. Uzupełnianie argumentów udostępnia możliwe wartości parametru. Dostępne wartości są obliczane w czasie wykonywania, gdy użytkownik naciska Tab po nazwie parametru. Istnieje kilka sposobów definiowania kompletnego argumentu dla parametru.

Uwaga

Karta jest domyślnym powiązaniem klucza w systemie Windows. To powiązanie kluczy można zmienić za pomocą modułu PSReadLine lub aplikacji obsługującej program PowerShell. Powiązanie kluczy różni się na platformach innych niż Windows. Aby uzyskać więcej informacji, zobacz about_PSReadLine.

ValidateSet, atrybut

Atrybut ValidateSet określa zestaw prawidłowych wartości dla parametru lub zmiennej i włącza uzupełnianie kart. Program PowerShell generuje błąd, jeśli wartość parametru lub zmiennej nie jest zgodna z wartością w zestawie. W poniższym przykładzie wartość parametru Fruit może być tylko Apple, Banana lub Pear.

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

W poniższym przykładzie wartość zmiennej $flavor musi być czekoladowa, truskawkowa lub waniliowa. Atrybut ValidateSet może być używany w dowolnej zmiennej, a nie tylko parametrach.

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

Walidacja odbywa się za każdym razem, gdy ta zmienna zostanie przypisana nawet w skry skrycie.

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

$Message = 'bye'

Ten przykład zwraca następujący błąd w czasie wykonywania:

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

Aby uzyskać więcej informacji na temat rozszerzania kart, zobacz about_Tab_Expansion.

Dynamiczne wartości ValidateSet przy użyciu klas

Klasa umożliwia dynamiczne generowanie wartości elementu ValidateSet w czasie wykonywania. W poniższym przykładzie prawidłowe wartości zmiennej $Sound są generowane za pośrednictwem klasy o nazwie SoundNames , która sprawdza trzy ścieżki systemu plików dla dostępnych plików dźwiękowych:

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

Klasa [SoundNames] jest następnie implementowana jako dynamiczna wartość ValidateSet w następujący sposób:

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

Uwaga

Klasa została wprowadzona IValidateSetValuesGenerator w programie PowerShell 6.0.

Atrybut ArgumentCompletions

Atrybut ArgumentCompletions umożliwia dodawanie wartości uzupełniania tabulatora do określonego parametru. Atrybut ArgumentCompletions musi być zdefiniowany dla każdego parametru, który wymaga ukończenia karty. Atrybut ArgumentCompletions jest podobny do ValidateSet. Oba atrybuty przyjmują listę wartości, które mają być prezentowane, gdy użytkownik naciska Tab po nazwie parametru. Jednak w przeciwieństwie do elementu ValidateSet wartości nie są weryfikowane i bardziej podobne do sugestii. W związku z tym użytkownik może podać dowolną wartość, a nie tylko wartości na liście.

Atrybut ArgumentCompletions nie powinien być mylony z atrybutem ArgumentCompleter , który wymaga skryptblocku do zdefiniowania opcji. dostępne są określone wartości

Składnia wygląda następująco:

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żdy z parametrów zawiera listę opcji atrybutu ArgumentCompletions w celu włączenia uzupełniania karty.

Ten atrybut został wprowadzony w programie PowerShell 6.0.

ArgumentCompleter, atrybut

Atrybut ArgumentCompleter umożliwia dodawanie wartości uzupełniania tabulacji do określonego parametru. Atrybut ArgumentCompleter musi być zdefiniowany dla każdego parametru, który wymaga ukończenia karty.

Aby dodać atrybut ArgumentCompleter , należy zdefiniować blok skryptu określający wartości. Blok skryptu musi przyjmować następujące parametry w kolejności określonej poniżej. Nazwy parametru nie mają znaczenia, ponieważ wartości są podawane w pozycji.

Składnia wygląda następująco:

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

Blok skryptu ArgumentCompleter

Parametry bloku skryptu są ustawione na następujące wartości:

$commandName (Pozycja 0) — ten parametr jest ustawiony na nazwę polecenia, dla którego blok skryptu udostępnia uzupełnianie kart.
$parameterName (Pozycja 1) — ten parametr jest ustawiony na parametr, którego wartość wymaga ukończenia karty.
$wordToComplete (Pozycja 2) — ten parametr jest ustawiony na wartość podaną przez użytkownika przed naciśnięciem Tab. Blok skryptu powinien używać tej wartości do określania wartości uzupełniania tabulacji.
$commandAst (Pozycja 3) — ten parametr jest ustawiony na abstrakcyjne drzewo składni (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz dokumentację typu AST .
$fakeBoundParameters (Pozycja 4) — ten parametr jest ustawiony na tabelę skrótową zawierającą $PSBoundParameters polecenie cmdlet przed naciśnięciem Tab przez użytkownika. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

Blok skryptu ArgumentCompleter musi wyrejestrować wartości przy użyciu potoku, takiego jak ForEach-Object, Where-Objectlub inną odpowiednią metodę. Zwracanie tablicy wartości powoduje, że program PowerShell traktuje całą tablicę jako jedną wartość uzupełniania tabulacji.

Poniższy przykład dodaje uzupełnianie tabulacji do parametru Value . Jeśli zostanie określony tylko parametr Value, zostaną wyświetlone wszystkie możliwe wartości lub argumenty. Po określeniu parametru Typ parametr wartość wyświetla tylko możliwe wartości dla tego typu.

Ponadto operator gwarantuje, -like że jeśli użytkownik wpisze następujące polecenie i używa uzupełniania tabulacji , zwracana jest tylko firma 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
      )
}

Uzupełnianie argumentów opartych na klasach

Począwszy od programu PowerShell 7.2, dodano nową funkcję, która umożliwia zdefiniowanie bardziej ogólnych implementacji sparametryzowanych uzupełniania argumentów.

Wyprowadzając z ArgumentCompleterAttributeklasy , można utworzyć ogólne moduły uzupełniania, które mogą być używane ponownie, na przykład:

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

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

[GitCommits(Branch='release')]

Atrybuty pochodne muszą implementować IArgumentCompleterFactory interfejs i używać wartości właściwości, aby utworzyć wyspecjalizowany kompletny moduł.

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

Użycie z programu PowerShell będzie wtedy:

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

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

Register-ArgumentCompleter

Polecenie Register-ArgumentCompleter cmdlet rejestruje niestandardowy moduł uzupełniania argumentów. Moduł uzupełniania argumentów umożliwia zapewnienie dynamicznego uzupełniania kart w czasie wykonywania dla dowolnego określonego polecenia.

Aby uzyskać więcej informacji, zobacz Register-ArgumentCompleter.

Udostępnij za pośrednictwem