about_Functions_Argument_Completion
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.
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 den Tabstoppabschluss benötigt. Das ArgumentCompletions-Attribut ähnelt ValidateSet. Beide Attribute verwenden eine Liste der Werte, die angezeigt werden sollen, wenn der Benutzer die TAB-TASTE hinter dem Parameternamen drückt. Im Gegensatz zu ValidateSet werden die Werte jedoch nicht überprüft und mehr 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
)
}
Jeder Parameter wird eine Liste der Optionen für das ArgumentCompletions-Attribut bereitgestellt, um den Tabstoppabschluss zu ermöglichen.
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 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$PSBoundParametersCmdlet 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
)
}
Klassenbasierte Argumentvervollständigen
Ab PowerShell 7.2 wurde ein neues Feature hinzugefügt, mit dem Sie allgemeinere Implementierungen parametrisierter Argumentvervollständigen definieren können.
Durch die Ableitung von ArgumentCompleterAttribute, ist es möglich, generische Completer 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 Eigenschaftswerte verwenden, um einen speziellen 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ürde dann wie nachfolgend beschrieben sein:
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 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.
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für