Sdílet prostřednictvím

Register-ArgumentCompleter

  • Reference
Modul:
Microsoft.PowerShell.Core

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

Syntaxe

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.

Když tento příkaz zavoláte pomocí parametru CommandName a bez parametrů ParameterName nebo Native , spustí se příkaz tak, jako byste zadali nativní parametr. To brání dokončení argumentu v práci s parametry příkazu PowerShellu. Parametr ParameterName vždy zadejte, pokud chcete pro příkazy PowerShellu zaregistrovat completer argumentu.

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 .

$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

První příkaz vytvoří blok skriptu, který převezme 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á uzavře každou hodnotu do uvozovek pro zpracování hodnot obsahujících mezery.

Druhý příkaz zaregistruje completer argumentu předáním scriptblocku, ID ParametrName a CommandName Set-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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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

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

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. PowerShell to používá jenom pro zobrazení. Příkaz se při výběru nepředá.
  • resultType (CompletionResultType) – typ výsledku dokončení.
  • toolTip (String) – text popisu s podrobnostmi o objektu. To se zobrazí, když uživatel vybere položku po stisknutí klávesy Ctrl+Mezerník.

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

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

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

V bloku dotnet complete skriptu provede příkaz dokončení 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í objektu CompletionResult pro každou hodnotu.

Parametry

-CommandName

Určuje název jednoho nebo více příkazů pro registraci dokončení argumentu. Tento parametr je povinný pro nativní příkazy.

Když tento parametr zadáte bez parametru ParameterName nebo Native , příkaz se chová, jako byste zadali nativní parametr. Při registraci dokončování argumentů pro příkazy PowerShellu vždy zadejte parametr ParameterName .

Pokud tento parametr nezadáte, PowerShell zaregistruje argument completer pro zadaný parametr ParameterName ve všech příkazech PowerShellu.

Typ:String[]
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-Native

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

Typ:SwitchParameter
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-ParameterName

Určuje název parametru, na který se argument completer vztahuje. Typ zadaných parametrů nemůže být výčtem, například parametr ForegroundColor rutiny Write-Host .

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

Při registraci dokončování argumentů pro příkazy PowerShellu vždy zadejte tento parametr. Když zadáte parametr CommandName bez parametrů ParameterName nebo Native, příkaz se chová, jako byste zadali nativní parametr.

Typ:String
Position:Named
Default value:None
Vyžadováno:True
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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 může také vrátit objekty System.Management.Automation.CompletionResult pro každou hodnotu, aby se zlepšilo uživatelské prostředí. Vrácení objektů CompletionResult umožňuje definovat popisy a vlastní položky seznamu zobrazené, když uživatelé stisknou klávesu Ctrl+Mezerník k zobrazení seznamu dostupných dokončení.

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, String) – Tento parametr je nastaven na název příkazu, pro který blok skriptu poskytuje dokončování tabulátoru.
  • $parameterName (Pozice 1, String) – Tento parametr je nastaven na parametr, jehož hodnota vyžaduje dokončení tabulátoru.
  • $wordToComplete (Pozice 2, String) – 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, CommandAst) – Tento parametr je nastaven na strom abstraktní syntaxe (AST) pro aktuální vstupní řádek. Další informace naleznete v tématu CommandAst – třída.
  • $fakeBoundParameters (Pozice 4 IDictionary) – 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, String) – 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 1, CommandAst) – Tento parametr je nastaven na strom abstraktní syntaxe (AST) pro aktuální vstupní řádek. Další informace naleznete v tématu CommandAst – třída.
  • $cursorPosition (Pozice 2, Int32) – 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.

Typ:ScriptBlock
Position:Named
Default value:None
Vyžadováno:True
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

Vstupy

None

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

Výstupy

None

Tato rutina nevrátí žádný výstup.