Register-ArgumentCompleter

Reference

Modul:: Microsoft.PowerShell.Core

Zaregistruje vlastní dokončování argumentů.

Syntax

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

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

Description

Rutina Register-ArgumentCompleter zaregistruje vlastní dokončování argumentů. Dokončování argumentů umožňuje zadat dynamické dokončování tabulátoru za běhu pro libovolný zadaný příkaz.

Příklady

Příklad 1: Registrace vlastního dokončování argumentů

Následující příklad zaregistruje completer argumentu pro parametr ID rutiny Set-TimeZone .

$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

První příkaz vytvoří blok skriptu, který vezme požadované parametry, které se předávají, když uživatel stiskne klávesu Tab. Další informace naleznete v popisu parametru ScriptBlock .

V bloku skriptu se pomocí rutiny Get-TimeZone načtou dostupné hodnoty ID. Vlastnost ID pro každé časové pásmo se předá rutině Where-Object . Rutina Where-Object vyfiltruje všechna ID, která nezačínají hodnotou, kterou $wordToCompleteposkytuje , což představuje text, který uživatel zadal předtím, než stiskl klávesu Tab. Filtrovaná ID se předávají do ForEach-Object rutiny, která ohraničuje každou hodnotu v uvozovkách, pokud hodnota obsahuje mezery.

Druhý příkaz zaregistruje completer argumentu předáním scriptblocku, ID ParametrNamea CommandNameSet-TimeZone.

Příklad 2: Přidání podrobností do hodnot dokončení tabulátoru

Následující příklad přepíše dokončování tabulátoru pro parametr Stop-Service Name rutiny a vrátí pouze spuštěné služby.

$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

V rámci bloku skriptu první příkaz načte všechny spuštěné služby pomocí rutiny Where-Object . Služby se předávají rutině ForEach-Object . Rutina ForEach-Object vytvoří nový objekt System.Management.Automation.CompletionResult a naplní ho názvem aktuální služby (reprezentovanou proměnnou $_.Namekanálu).

Objekt CompletionResult umožňuje zadat další podrobnosti pro každou vrácenou hodnotu:

completionText (String) – text, který se má použít jako výsledek automatického dokončování. Toto je hodnota odeslaná do příkazu.
listItemText (String) – text, který se má zobrazit v seznamu, například když uživatel stiskne klávesu Ctrl+Mezerník. Používá se jenom pro zobrazení a při výběru se do příkazu nepředá.
resultType (CompletionResultType) – typ výsledku dokončení.
toolTip (String) – text popisu s podrobnostmi, které se mají zobrazit o objektu. To se zobrazí, když uživatel vybere položku po stisknutí klávesy Ctrl+Mezerník.

Poslední příkaz ukazuje, že zastavené služby lze rutině Stop-Service předat ručně. Dokončení tabulátoru je jediným ovlivněným aspektem.

Příklad 3: Registrace vlastního nativního argumentu completer

Pomocí nativního parametru můžete zadat dokončování tabulátoru pro nativní příkaz. Následující příklad přidá dokončování tabulátoru pro rozhraní příkazového dotnet řádku (CLI).

Poznámka:

Příkaz dotnet complete je k dispozici pouze ve verzi 2.0 a vyšší v rozhraní příkazového řádku dotnet.

$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

V bloku dotnet complete skriptu se příkaz použije k provedení dokončování tabulátoru. Výsledky se předávají rutině ForEach-Object , která používá novou statickou metodu System.Management.Automation.CompletionResult třídy k vytvoření nového objektu CompletionResult pro každou hodnotu.

Parametry

-CommandName

Určuje název příkazů jako pole.

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

-Native

Označuje, že argument completer je pro nativní příkaz, kde PowerShell nemůže dokončit názvy parametrů.

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

-ParameterName

Určuje název parametru, jehož argument je dokončen. Zadaný název parametru nemůže být výčtovou hodnotou, například parametr ForegroundColor rutiny Write-Host .

Další informace o výčtech najdete v tématu about_Enum.

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

-ScriptBlock

Určuje příkazy, které se mají spustit, aby se provedlo dokončování tabulátoru. Zadaný blok skriptu by měl vrátit hodnoty, které dokončí vstup. Blok skriptu musí zrušit registraci hodnot pomocí kanálu (ForEach-ObjectWhere-Objectatd.) nebo jiné vhodné metody. Vrácení pole hodnot způsobí, že PowerShell považuje celé pole za jednu hodnotu dokončení tabulátoru.

Blok skriptu musí přijmout následující parametry v pořadí uvedeném níže. Názvy parametrů nejsou důležité, protože PowerShell předává hodnoty podle pozice.

$commandName (Pozice 0) – Tento parametr je nastaven na název příkazu, pro který blok skriptu poskytuje dokončování tabulátoru.
$parameterName (Pozice 1) – Tento parametr je nastaven na parametr, jehož hodnota vyžaduje dokončení tabulátoru.
$wordToComplete (Pozice 2) – Tento parametr je nastaven na hodnotu, kterou uživatel zadal před stisknutím klávesy Tab. Blok skriptu by měl tuto hodnotu použít k určení hodnot dokončení tabulátoru.
$commandAst (Pozice 3) – Tento parametr je nastavený na abstraktní strom syntaxe (AST) pro aktuální vstupní řádek. Další informace najdete v tématu Třída Ast.
$fakeBoundParameters (Pozice 4) – Tento parametr je nastavený na hashtable obsahující rutinu $PSBoundParameters před stisknutím klávesy Tab uživatele. Další informace najdete v tématu about_Automatic_Variables.

Pokud zadáte nativní parametr, blok skriptu musí mít v zadaném pořadí následující parametry. Názvy parametrů nejsou důležité, protože PowerShell předává hodnoty podle pozice.

$wordToComplete (Pozice 0) – Tento parametr je nastaven na hodnotu, kterou uživatel zadal předtím, než stiskne klávesu Tab. Blok skriptu by měl tuto hodnotu použít k určení hodnot dokončení tabulátoru.
$commandAst (Pozice 1) – Tento parametr je nastavený na strom abstraktní syntaxe (AST) pro aktuální vstupní řádek. Další informace najdete v tématu Třída Ast.
$cursorPosition (Pozice 2) – Tento parametr je nastaven na pozici kurzoru, když uživatel stiskl klávesu Tab.

ArgumentCompleter můžete také zadat jako atribut parametru. Další informace najdete v tématu about_Functions_Advanced_Parameters.

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

Vstupy

None

Do této rutiny nemůžete roušit objekty.

Výstupy