Freigeben über

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.

Wenn Sie diesen Befehl mit dem Parameter "CommandName " und ohne parameter "ParameterName " oder "Native " aufrufen, wird der Befehl ausgeführt, als ob Sie den Native-Parameter angegeben haben. Dadurch wird verhindert, dass der Argumentvervollständigenr für PowerShell-Befehlsparameter funktioniert. Geben Sie immer den Parameter "ParameterName " an, wenn Sie einen Argument completer für PowerShell-Befehle registrieren möchten.

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.

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

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

Mit dem ersten Befehl wird ein Skriptblock erstellt, der die erforderlichen Parameter akzeptiert, 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, um Werte zu verarbeiten, die Leerzeichen enthalten.

Mit dem zweiten Befehl wird das Argument completer registriert, indem der Scriptblock, die ParameterName-ID und der CommandName Set-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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

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

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 dem Namen des aktuellen Diensts (dargestellt durch die Pipelinevariable $_.Name).

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. PowerShell verwendet dies nur für die Anzeige. Er 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 zum Objekt. Dies ist sichtbar, wenn der Benutzer ein Element nach dem Drücken der STRG-LEERTASTE+ auswählt.

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(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

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

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

Parameter

-CommandName

Gibt den Namen eines oder mehrerer Befehle an, für die das Argument completer registriert werden soll. Dieser Parameter ist für systemeigene Befehle obligatorisch.

Wenn Sie diesen Parameter ohne parametername oder native Parameter angeben, verhält sich der Befehl so, als hätten Sie den Native-Parameter angegeben. Geben Sie beim Registrieren von Argumentvervollständigen für PowerShell-Befehle immer den Parameter ParameterName an.

Wenn Sie diesen Parameter nicht angeben, registriert PowerShell den Argument completer für den angegebenen Parametername für alle PowerShell-Befehle.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Native

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

Typ:SwitchParameter
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ParameterName

Gibt den Namen des Parameters an, auf den das Argument completer angewendet wird. Der Typ für angegebene Parameter kann keine Enumeration sein, z. B. der ForegroundColor-Parameter des Write-Host Cmdlets.

Weitere Informationen zu Enumerationen finden Sie unter about_Enum.

Geben Sie beim Registrieren eines Argumentvervollständigens für PowerShell-Befehle immer diesen Parameter an. Wenn Sie den Parameter "CommandName " ohne parameter "ParameterName " oder "Native " angeben, verhält sich der Befehl so, als ob Sie den nativen Parameter angegeben haben.

Typ:String
Position:Named
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 kann auch System.Management.Automation.CompletionResult-Objekte für jeden Wert zurückgeben, um die Benutzererfahrung zu verbessern. Durch das Zurückgeben von CompletionResult-Objekten können Sie QuickInfos und benutzerdefinierte Listeneinträge definieren, die angezeigt werden, wenn Benutzer STRG-LEERTASTE+ drücken, um die Liste der verfügbaren Fertigstellungen anzuzeigen.

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, String) – Dieser Parameter wird auf den Namen des Befehls festgelegt, für den der Skriptblock den Tabstoppabschluss bereitstellt.
  • $parameterName (Position 1, String) – Dieser Parameter wird auf den Parameter festgelegt, dessen Wert den Tabstoppabschluss erfordert.
  • $wordToComplete(Position 2, String) – 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, CommandAst) – Dieser Parameter wird für die aktuelle Eingabezeile auf die abstrakte Syntaxstruktur (Abstract Syntax Tree, AST) festgelegt. Weitere Informationen finden Sie unter CommandAst-Klasse.
  • $fakeBoundParameters(Position 4 IDictionary) – 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, String) – 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, CommandAst) – Dieser Parameter wird für die aktuelle Eingabezeile auf die abstrakte Syntaxstruktur (Abstract Syntax Tree, AST) festgelegt. Weitere Informationen finden Sie unter CommandAst-Klasse.
  • $cursorPosition(Position 2, Int32) – 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.

Typ:ScriptBlock
Position:Named
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

None

Dieses Cmdlet gibt keine Ausgabe zurück.