about_Functions_Argument_Completion

Artikel
05/09/2024

Kurze Beschreibung

Die Vervollständigung von Argumenten ist ein Feature von PowerShell, das Hinweise bereitstellt, die Ermittlung aktiviert 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 die TAB-TASTE nach dem Parameternamen drückt. Es gibt mehrere Möglichkeiten, einen Argument completer für einen Parameter zu definieren.

Hinweis

Tab ist die Standardschlüsselbindung unter Windows. Diese Schlüsselbindung kann vom PSReadLine-Modul oder der Anwendung geändert werden, die PowerShell hostt. 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 aktiviert die Tabulatoren-Vervollständigung. 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 Apple, Banana oder Pear sein.

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

Im folgenden Beispiel muss der Wert der Variablen $flavor entweder Schokolade, Erdbeere oder Vanille 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 Tabstoppvervollständigungswerte hinzufügen. Für jeden Parameter, der eine Registerkartenvervollständigung erfordert, muss ein ArgumentCompletions-Attribut definiert werden. 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 ähneln eher Vorschlägen. 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 zum Definieren der Optionen benötigt. 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('Tomato', 'Corn', 'Squash')]
        $Vegetable
    )
}

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

Dieses Attribut wurde in PowerShell 6.0 eingeführt.

ArgumentCompleter-Attribut

Mit dem ArgumentCompleter-Attribut können Sie einem bestimmten Parameter Tabstoppvervollständigungswerte hinzufügen. Für jeden Parameter, der eine Registerkartenvervollständigung erfordert, muss ein ArgumentCompleter-Attribut definiert werden.

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 wird auf den Namen des Befehls festgelegt, für den der Skriptblock die Tabulatorvervollstä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 angegeben hat, bevor er die Tabulatortaste gedrückt hat. Ihr Skriptblock sollte diesen Wert verwenden, um Tabstopp-Vervollständigungswerte zu bestimmen.
$commandAst (Position 3): Dieser Parameter ist auf die Abstrakte Syntaxstruktur (AST) für die aktuelle Eingabezeile 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 Tabulatortaste 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. Das Zurückgeben eines Arrays von Werten bewirkt, dass PowerShell das gesamte Array als Einen Tab-Vervollständigungswert behandelt.

Im folgenden Beispiel wird dem Value-Parameter die Vervollständigung der Registerkarte hinzugefügt. Wenn nur der Wertparameter angegeben wird, werden alle möglichen Werte oder Argumente für Value angezeigt. Wenn der Type-Parameter angegeben wird, zeigt der Wertparameter 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 Tabstopp-Vervollständigung verwendet.

Test-ArgumentCompleter -Type Fruits -Value A

function MyArgumentCompleter{
    param ( $commandName,
            $parameterName,
            $wordToComplete,
            $commandAst,
            $fakeBoundParameters )

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Tomato', 'Squash', 'Corn')
    }

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

Register-ArgumentCompleter

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

Weitere Informationen finden Sie unter Register-ArgumentCompleter.

Freigeben über