Register-ArgumentCompleter

Referenz

Modul:: Microsoft.PowerShell.Core

Registriert einen benutzerdefinierten Argument completer.

Syntax

Register-ArgumentCompleter
        -CommandName <String[]>
        -ScriptBlock <ScriptBlock>
        [-Native]
        [<CommonParameters>]

Register-ArgumentCompleter
        [-CommandName <String[]>]
        -ParameterName <String>
        -ScriptBlock <ScriptBlock>
        [<CommonParameters>]

Beschreibung

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.

Beispiele

Beispiel 1: Registrieren eines benutzerdefinierten Argumentvervollständigens

Im folgenden Beispiel wird ein Argument completer für den Id-Parameter des Set-TimeZone Cmdlets registriert.

$scriptBlock = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
          "'$_'"
    }
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $scriptBlock

Mit dem ersten Befehl wird ein Skriptblock erstellt, der die erforderlichen Parameter verwendet, die übergeben werden, wenn der Benutzer die TAB-TASTE drückt. Weitere Informationen finden Sie in der ScriptBlock-Parameterbeschreibung.

Innerhalb des Skriptblocks werden die verfügbaren Werte für die ID mithilfe des Get-TimeZone Cmdlets abgerufen. Die ID-Eigenschaft für jede Zeitzone wird an das Where-Object Cmdlet weitergeleitet. Das Where-Object Cmdlet filtert alle IDs aus, die nicht mit dem von ihnen bereitgestellten $wordToCompleteWert beginnen, der den Text darstellt, den der Benutzer eingegeben hat, bevor er die TAB-TASTE gedrückt hat. Die gefilterten IDs werden an das ForEach-Object Cmdlet weitergeleitet, das jeden Wert in Anführungszeichen einschließt, wenn der Wert Leerzeichen enthält.

Mit dem zweiten Befehl wird das Argument completer registriert, indem der Scriptblock, die ParameterName-ID und der CommandNameSet-TimeZone übergeben werden.

Beispiel 2: Hinzufügen von Details zu den Abschlusswerten der Registerkarte

Im folgenden Beispiel wird der Tababschluss für den Parameter "Name " des Stop-Service Cmdlets überschrieben und nur ausgeführte Dienste zurückgegeben.

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"}
    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_.Name,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

Innerhalb des Skriptblocks ruft der erste Befehl alle ausgeführten Dienste mithilfe des Where-Object Cmdlets ab. Die Dienste werden an das ForEach-Object Cmdlet weitergeleitet. Das ForEach-Object Cmdlet erstellt ein neues [System.Management.Automation.CompletionResult] Objekt und füllt es mit den Werten des aktuellen Diensts (dargestellt durch die Pipelinevariable $_).

Mit dem CompletionResult-Objekt können Sie zusätzliche Details zu jedem zurückgegebenen Wert angeben:

completionText (String) – Der Text, der als Ergebnis der automatischen Vervollständigung verwendet werden soll. Dies ist der Wert, der an den Befehl gesendet wird.
listItemText (String) – Der text, der in einer Liste angezeigt werden soll, z. B. wenn der Benutzer STRG+LEERTASTE drückt. Dies wird nur für die Anzeige verwendet und wird beim Auswählen nicht an den Befehl übergeben.
resultType (CompletionResultType) – Der Typ des Abschlussergebnisses.
QuickInfo (Zeichenfolge) – Der Text für die QuickInfo mit Details, die zum Objekt angezeigt werden sollen. Dies ist sichtbar, wenn der Benutzer ein Element nach dem Drücken der STRG-LEERTASTE+ auswählt.

Der letzte Befehl zeigt, dass beendete Dienste weiterhin manuell an das Stop-Service Cmdlet übergeben werden können. Der Abschluss der Registerkarte ist der einzige Aspekt, der betroffen ist.

Beispiel 3: Registrieren eines benutzerdefinierten nativen Arguments completer

Sie können den nativen Parameter verwenden, um die Tabstoppvervollständigung für einen systemeigenen Befehl bereitzustellen. Im folgenden Beispiel wird die Tabulatorvervollständigung für die dotnet Befehlszeilenschnittstelle (COMMAND Line Interface, CLI) hinzugefügt.

Hinweis

Der dotnet complete Befehl ist nur in Version 2.0 und höher der dotnet cli verfügbar.

$scriptblock = {
    param($wordToComplete, $commandAst, $cursorPosition)
        dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Innerhalb des Skriptblocks wird der dotnet complete Befehl verwendet, um den Abschluss der Registerkarte auszuführen. Die Ergebnisse werden an das ForEach-Object Cmdlet weitergeleitet, das die neue statische Methode der System.Management.Automation.CompletionResult-Klasse verwendet, um ein neues CompletionResult-Objekt für jeden Wert zu erstellen.

Parameter

-CommandName

Gibt den Namen der Befehle als Array an.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Native

Gibt an, dass der Argumentvervollständigener für einen systemeigenen Befehl gilt, bei dem PowerShell keine Parameternamen abschließen kann.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ParameterName

Gibt den Namen des Parameters an, dessen Argument abgeschlossen wird. Der angegebene Parametername darf kein Aufzählungswert sein, z. B. der ForegroundColor-Parameter des Write-Host Cmdlets.

Weitere Informationen zu Enumerationen finden Sie unter about_Enum.

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ScriptBlock

Gibt die Befehle an, die ausgeführt werden sollen, um den Abschluss der Registerkarte auszuführen. Der von Ihnen bereitgestellte Skriptblock sollte die Werte zurückgeben, die die Eingabe abschließen. Der Skriptblock muss die Registrierung der Werte mithilfe der Pipeline (ForEach-Object, Where-Objectusw.) oder einer anderen geeigneten Methode aufheben. Wenn Sie ein Array von Werten zurückgeben, wird das gesamte Array von PowerShell als ein Tabstopp-Abschlusswert behandelt.

Der Skriptblock muss die folgenden Parameter in der unten angegebenen Reihenfolge akzeptieren. Die Namen der Parameter sind nicht wichtig, da PowerShell die Werte nach Position übergibt.

$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 unter Ast Class.
$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.

Wenn Sie den nativen Parameter angeben, muss der Skriptblock die folgenden Parameter in der angegebenen Reihenfolge verwenden. Die Namen der Parameter sind nicht wichtig, da PowerShell die Werte nach Position übergibt.

$wordToComplete(Position 0) – 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 1) – Dieser Parameter wird für die aktuelle Eingabezeile auf die abstrakte Syntaxstruktur (AST) festgelegt. Weitere Informationen finden Sie unter Ast Class.
$cursorPosition(Position 2) – Dieser Parameter wird auf die Position des Cursors festgelegt, wenn der Benutzer die TAB-TASTE gedrückt hat.

Sie können auch ein ArgumentCompleter als Parameterattribute bereitstellen. Weitere Informationen finden Sie unter about_Functions_Advanced_Parameters.

Type:	ScriptBlock
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben