about_Functions_Argument_Completion

Artikel
05/09/2024

Kurze Beschreibung

Die Argumentvollständigung ist ein Feature von PowerShell, das Hinweise bereitstellt, die Ermittlung ermöglicht und die Eingabe von Argumentwerten beschleunigt.

Lange Beschreibung

In diesem Artikel werden die verschiedenen Möglichkeiten beschrieben, wie Sie Argumentvervollständigenr für PowerShell-Funktionen implementieren können. Argument-Vervollständigungsmodule stellen die möglichen Werte für einen Parameter bereit. Die verfügbaren Werte werden zur Laufzeit berechnet, wenn der Benutzer nach dem Parameternamen die TAB-TASTE drückt. Es gibt mehrere Möglichkeiten, einen Argument completer für einen Parameter zu definieren.

Hinweis

Tab ist die Standardtastenbindung unter Windows. Diese Schlüsselbindung kann durch das PSReadLine-Modul oder die Anwendung geändert werden, die PowerShell hosten. Die Schlüsselbindung unterscheidet sich auf Nicht-Windows-Plattformen. Weitere Informationen finden Sie unter about_PSReadLine.

ValidateSet-Attribut

Das ValidateSet-Attribut gibt einen Satz gültiger Werte für einen Parameter oder eine Variable an und ermöglicht die Vervollständigung der Registerkarte. PowerShell generiert einen Fehler, wenn ein Parameter- oder Variablenwert nicht mit einem Wert in der Gruppe übereinstimmt. Im folgenden Beispiel kann der Wert des Fruit-Parameters nur Apfel, Banane oder Birne sein.

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

Im folgenden Beispiel muss der Wert der Variablen $flavor entweder Chocolate, Strawberry oder Vanilla sein. Das ValidateSet Attribut kann für jede Variable verwendet werden, nicht nur für Parameter.

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

Die Überprüfung erfolgt immer dann, wenn diese Variable auch innerhalb des Skripts zugewiesen wird.

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

$Message = 'bye'

In diesem Beispiel wird zur Laufzeit der folgende Fehler zurückgegeben:

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

Weitere Informationen zur Registerkartenerweiterung finden Sie unter about_Tab_Expansion.

Dynamische ValidateSet-Werte mithilfe von Klassen

Sie können eine -Klasse verwenden, um die Werte für ValidateSet zur Laufzeit dynamisch zu generieren. Im folgenden Beispiel werden die gültigen Werte für die Variable $Sound über eine Klasse namens SoundNames generiert, die drei Dateisystempfade auf verfügbare Sounddateien überprüft:

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

Die [SoundNames] -Klasse wird dann wie folgt als dynamischer ValidateSet-Wert implementiert:

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

Hinweis

Die IValidateSetValuesGenerator -Klasse wurde in PowerShell 6.0 eingeführt.

ArgumentCompletions-Attribut

Mit dem ArgumentCompletions-Attribut können Sie einem bestimmten Parameter Tabstopp-Vervollständigungswerte hinzufügen. Ein ArgumentCompletions-Attribut muss für jeden Parameter definiert werden, der die Tabulatorvervollständigung erfordert. Das ArgumentCompletions-Attribut ähnelt ValidateSet. Beide Attribute verwenden eine Liste von Werten, die angezeigt werden sollen, wenn der Benutzer die TAB-TASTE nach dem Parameternamen drückt. Im Gegensatz zu ValidateSet werden die Werte jedoch nicht überprüft und sind eher wie Vorschläge. Daher kann der Benutzer einen beliebigen Wert angeben, nicht nur die Werte in der Liste.

Das ArgumentCompletions-Attribut sollte nicht mit dem ArgumentCompleter-Attribut verwechselt werden, das einen Scriptblock benötigt, um die Optionen zu definieren. Die angegebenen Werte sind verfügbar.

Die Syntax lautet wie folgt:

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

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

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

Für jeden Parameter wird eine Liste von Optionen für das ArgumentCompletions-Attribut bereitgestellt, um die Tabstoppvervollständigung zu aktivieren.

Dieses Attribut wurde in PowerShell 6.0 eingeführt.

ArgumentCompleter-Attribut

Mit dem ArgumentCompleter-Attribut können Sie einem bestimmten Parameter Tabstopp-Vervollständigungswerte hinzufügen. Ein ArgumentCompleter-Attribut muss für jeden Parameter definiert werden, der eine Tabstopp-Vervollständigung erfordert.

Um ein ArgumentCompleter-Attribut hinzuzufügen, müssen Sie einen Skriptblock definieren, der die Werte bestimmt. Der Skriptblock muss die folgenden Parameter in der unten angegebenen Reihenfolge verwenden. Die Namen des Parameters spielen keine Rolle, da die Werte positionell bereitgestellt werden.

Die Syntax lautet wie folgt:

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

ArgumentCompleter-Skriptblock

Die Skriptblockparameter sind auf die folgenden Werte festgelegt:

$commandName (Position 0): Dieser Parameter ist auf den Namen des Befehls festgelegt, für den der Skriptblock die Tabstoppvervollständigung bereitstellt.
$parameterName (Position 1): Dieser Parameter wird auf den Parameter festgelegt, dessen Wert die Tabulatorvervollständigung erfordert.
$wordToComplete (Position 2): Dieser Parameter ist auf den Wert festgelegt, den der Benutzer vor dem Drücken der TAB-TASTE angegeben hat. Ihr Skriptblock sollte diesen Wert verwenden, um Werte für die Tabstoppabschlussung zu bestimmen.
$commandAst (Position 3): Dieser Parameter wird für die aktuelle Eingabezeile auf die Abstrakte Syntaxstruktur (AST) festgelegt. Weitere Informationen finden Sie in der Dokumentation zum AST-Typ .
$fakeBoundParameters (Position 4): Dieser Parameter wird auf eine Hashtabelle festgelegt, die den $PSBoundParameters für das Cmdlet enthält, bevor der Benutzer die TAB-TASTE gedrückt hat. Weitere Informationen finden Sie unter about_Automatic_Variables.

Der ArgumentCompleter-Skriptblock muss die Registrierung der Werte mithilfe der Pipeline aufheben, z ForEach-Object. B. , Where-Objectoder einer anderen geeigneten Methode. Die Rückgabe eines Arrays von Werten bewirkt, dass PowerShell das gesamte Array als einen Tabstoppabschlusswert behandelt.

Im folgenden Beispiel wird dem Value-Parameter die Vervollständigung der Registerkarte hinzugefügt. Wenn nur der Value-Parameter angegeben wird, werden alle möglichen Werte oder Argumente für Value angezeigt. Wenn der Type-Parameter angegeben ist, zeigt der Value-Parameter nur die möglichen Werte für diesen Typ an.

Darüber hinaus stellt der -like Operator sicher, dass nur Apple zurückgegeben wird, wenn der Benutzer den folgenden Befehl eingibt und die TAB-Vervollständigung verwendet.

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

Klassenbasierte Argumentvervollständigung

Ab PowerShell 7.2 wurde ein neues Feature hinzugefügt, mit dem Sie generischere Implementierungen parametrisierter Argumentvervollständigenr definieren können.

Durch Ableiten von ArgumentCompleterAttributeist es möglich, generische Vervollständigungsmodule zu erstellen, die wiederverwendet werden können, z. B.:

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

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

[GitCommits(Branch='release')]

Die abgeleiteten Attribute müssen die IArgumentCompleterFactory -Schnittstelle implementieren und Eigenschaftenwerte verwenden, um einen spezialisierten Completer zu erstellen.

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

Die Verwendung von PowerShell wäre dann wie folgt:

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

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

Register-ArgumentCompleter

Das Register-ArgumentCompleter Cmdlet registriert einen benutzerdefinierten Argumentvervollständigenr. Mit einem Argument completer können Sie dynamische Tabstopps zur Laufzeit für jeden von Ihnen angegebenen Befehl bereitstellen.

Weitere Informationen finden Sie unter Register-ArgumentCompleter.

Freigeben über