Register-ArgumentCompleter

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

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

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.

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 akzeptiert, die übergeben werden, wenn der Benutzer die Tabulatortaste 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 Where-Object Cmdlet filtert alle IDs heraus, die nicht mit dem von bereitgestellten Wert $wordToCompletebeginnen, der den Text darstellt, den der Benutzer eingegeben hat, bevor er die Tabulatortaste gedrückt hat. Die gefilterten IDs werden an das Cmdlet weitergeleitet, das ForEach-Object jeden Wert in Anführungszeichen einschließt, falls der Wert Leerzeichen enthält.

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

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

Der erste Befehl erstellt einen Skriptblock, der die erforderlichen Parameter akzeptiert, die übergeben werden, wenn der Benutzer die Tabulatortaste drückt. Weitere Informationen finden Sie in der Beschreibung des ScriptBlock-Parameters .

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.
• toolTip (Zeichenfolge) - Der Text für den Tooltip mit Details, die über das 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 Stop-Service Cmdlet übergeben werden können. Der Abschluss der Registerkarte ist der einzige Aspekt, der betroffen ist.

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.

$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

Der erste Befehl erstellt einen Skriptblock, der die erforderlichen Parameter akzeptiert, die übergeben werden, wenn der Benutzer die Tabulatortaste drückt. Weitere Informationen finden Sie in der Beschreibung des ScriptBlock-Parameters .

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

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Dieses Cmdlet gibt keine Ausgabe zurück.