about_Functions_Argument_Completion

Artikel
10/04/2023

Kurze Beschreibung

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

Lange Beschreibung

In diesem Artikel werden die verschiedenen Möglichkeiten beschrieben, wie Sie Argumentvervollständigen für PowerShell-Funktionen implementieren können. Argumentvervollständigen 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 zum Definieren eines Argumentvervollständigens für einen Parameter.

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 den Abschluss der Registerkarte. PowerShell generiert einen Fehler, wenn ein Parameter oder Variablenwert nicht mit einem Wert im Satz übereinstimmt. Im folgenden Beispiel kann der Wert des Parameters "Fruit" nur "Apfel", "Bananen" oder "Birne" lauten.

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 und nicht nur für Parameter verwendet werden.

[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 der folgende Fehler zur Laufzeit 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 mit 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 mit dem Namen SoundNames generiert, die drei Dateisystempfade auf verfügbare Audiodateien ü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.

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 den Abschluss der Registerkarte 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 werden auf die folgenden Werte festgelegt:

$commandName (Position 0) – Dieser Parameter wird auf den Namen des Befehls festgelegt, für den der Skriptblock den Tabstoppabschluss bereitstellt.
$parameterName (Position 1) – Dieser Parameter wird auf den Parameter festgelegt, dessen Wert die Tabulatorvervollständigung erfordert.
$wordToComplete(Position 2) – Dieser Parameter wird auf den Wert festgelegt, den der Benutzer angegeben hat, bevor er die TAB-TASTE gedrückt hat. Ihr Skriptblock sollte diesen Wert verwenden, um die Werte für den Tabstoppabschluss zu ermitteln.
$commandAst (Position 3) – Dieser Parameter wird für die aktuelle Eingabezeile auf die abstrakte Syntaxstruktur (AST) festgelegt. Weitere Informationen finden Sie in der AST-Typdokumentation .
$fakeBoundParameters(Position 4) – Dieser Parameter wird auf eine Hashtable festgelegt, die das $PSBoundParameters 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 eine andere geeignete Methode. Wenn Sie ein Array von Werten zurückgeben, wird das gesamte Array von PowerShell als ein Tabstopp-Abschlusswert behandelt.

Im folgenden Beispiel wird dem Parameter Value der Tabstoppabschluss hinzugefügt. Wenn nur der Parameter Value angegeben ist, werden alle möglichen Werte oder Argumente für Value angezeigt. Wenn der Parameter Type angegeben wird, 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 den Tab-Abschluss 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
      )
}

Register-ArgumentCompleter

Das Register-ArgumentCompleter Cmdlet registriert einen benutzerdefinierten Argument completer. Ein Argument completer ermöglicht es Ihnen, zur Laufzeit für jeden von Ihnen angegebenen Befehl dynamischen Tabstoppabschluss bereitzustellen.

Weitere Informationen finden Sie unter Register-ArgumentCompleter.

Freigeben über