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. Mit einem Argument completer können Sie zur Laufzeit für jeden von Ihnen angegebenen Befehl eine dynamische Registerkartenvollständigung bereitstellen.

Beispiele

Beispiel 1: Registrieren eines benutzerdefinierten Argument-Completers

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 übernimmt, die übergeben werden, wenn der Benutzer die TAB-TASTE drückt. Weitere Informationen finden Sie in der Beschreibung des ScriptBlock-Parameters .

Innerhalb des Skriptblocks werden die verfügbaren Werte für 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 heraus, die nicht mit dem von $wordToCompletebereitgestellten Wert beginnen, der den Text darstellt, den der Benutzer eingegeben hat, bevor er die Tabulatortaste gedrückt hat. Die gefilterten IDs werden an das For-EachObject Cmdlet weitergeleitet, das jeden Wert in Anführungszeichen einschließt, falls 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 Tabstopp-Vervollständigungswerten

Im folgenden Beispiel wird die Registerkartenabschluss für den Name-Parameter 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 dem Namen des aktuellen Diensts auf (dargestellt durch die Pipelinevariable $_.Name).

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

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-Leerzeichen drückt+. Dies wird nur für die Anzeige verwendet und wird bei Auswahl nicht an den Befehl übergeben.
resultType (CompletionResultType): Der Typ des Abschlussergebnisses.
QuickInfo (String): Der Text für die QuickInfo mit Details, die zum Objekt angezeigt werden sollen. Dies wird angezeigt, wenn der Benutzer ein Element auswählt, nachdem er strg+leer gedrückt hat.

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

Beispiel 3: Registrieren eines benutzerdefinierten Native-Argument-Completers

Sie können den nativen Parameter verwenden, um die Registerkartenvervollständigung für einen nativen Befehl bereitzustellen. Im folgenden Beispiel wird die Tabulatorvervollständigung für die dotnet Befehlszeilenschnittstelle (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 die Vervollständigung der Registerkarte durchzufü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 das Argument completer für einen systemeigenen Befehl gilt, bei dem PowerShell Parameternamen nicht vervollständigen 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 aufgezählter Wert sein, z. B. der ForegroundColor-Parameter des Write-Host Cmdlets.

Weitere Informationen zu Aufzählungen 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 die Registerkartenvervollständigen durchzufü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. Das Zurückgeben eines Arrays von Werten bewirkt, dass PowerShell das gesamte Array als Einen Tab-Vervollständigungswert 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 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 unter Ast-Klasse.
$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.

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

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

Objekte können nicht an dieses Cmdlet weitergereicht werden.

Ausgaben