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 cmdlet Register-ArgumentCompleter 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 parameter ID des Cmdlets Set-TimeZone 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

Der erste Befehl erstellt einen Skriptblock, der die erforderlichen Parameter verwendet, die übergeben werden, wenn der Benutzer TAB-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 cmdlets Get-TimeZone abgerufen. Die ID--Eigenschaft für jede Zeitzone wird an das cmdlet Where-Object weitergeleitet. Das cmdlet Where-Object filtert alle IDs aus, die nicht mit dem von $wordToCompletebereitgestellten Wert beginnen, der den Text darstellt, den der Benutzer eingegeben hat, bevor er TAB-gedrückt hat. Die gefilterten IDs werden an das Cmdlet ForEach-Object weitergeleitet, das jeden Wert in Anführungszeichen einschließt, wenn der Wert Leerzeichen enthält.

Der zweite Befehl registriert das Argument completer, indem der Scriptblock, die ParameterNameId und die CommandName-Set-TimeZoneübergeben.

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

Im folgenden Beispiel wird der Tabstoppabschluss für den Parameter Name des Cmdlets Stop-Service ü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 Cmdlets Where-Object ab. Die Dienste werden an das Cmdlet ForEach-Object weitergeleitet. Das cmdlet ForEach-Object 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 jedem zurückgegebenen Wert zusätzliche Details bereitstellen:

completionText (Zeichenfolge) – Der text, der als Ergebnis der automatischen Vervollständigung verwendet werden soll. Dies ist der Wert, der an den Befehl gesendet wird.
listItemText- (Zeichenfolge) – Der text, der in einer Liste angezeigt werden soll, z. B. wenn der Benutzer STRG+LEERTASTEdrü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 auswählt, nachdem STRG+LEERTASTEgedrückt wurde.

Der letzte Befehl zeigt, dass beendete Dienste weiterhin manuell an das Cmdlet Stop-Service ü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 Parameter Native verwenden, um den Tab-Abschluss für einen systemeigenen Befehl bereitzustellen. Im folgenden Beispiel wird der dotnet Befehlszeilenschnittstelle (CLI) die Tabstoppvervollständigung hinzugefügt.

Anmerkung

Der Befehl dotnet complete 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 befehl dotnet complete verwendet, um den Abschluss der Registerkarte auszuführen. Die Ergebnisse werden an das cmdlet ForEach-Object 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.

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, dessen Argument abgeschlossen wird. Der angegebene Parametername darf kein Aufzählungswert sein, z. B. der parameter ForegroundColor des Cmdlets Write-Host.

Weitere Informationen zu Enumerationen finden Sie unter about_Enum.

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 Ein Array von Werten zurückgegeben wird, behandelt PowerShell das gesamte Array als einen Tabstoppabschlusswert.

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 den Tabstoppabschluss erfordert.
$wordToComplete (Position 2) – Dieser Parameter wird auf den Wert festgelegt, den der Benutzer angegeben hat, bevor er TAB-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 die $PSBoundParameters für das Cmdlet enthält, bevor der Benutzer TAB-gedrückt hat. Weitere Informationen finden Sie unter about_Automatic_Variables.

Wenn Sie den Parameter Native 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 TAB-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 TAB-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

Objekte können nicht an dieses Cmdlet weitergeleitet werden.

Ausgaben