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 parametru ParameterName nebo Nativní, příkaz se spustí, jako byste zadali parametr Native. To brání dokončení argumentu v práci s parametry příkazu PowerShellu. Vždy zadejte parametr ParameterName, 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 ID parametru Set-TimeZone rutiny.

$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řebírá požadované parametry, které se předávají, když uživatel stiskne Tabulátor. Další informace najdete 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 poskytovanou $wordToComplete, která představuje text, který uživatel zadal předtím, než stiskne tabulátoru . Filtrované ID se předávají do rutiny ForEach-Object, 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 skriptublock, ParameterNameID a 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 Name rutiny Stop-Service 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řebírá požadované parametry, které se předávají, když uživatel stiskne Tabulátor. Další informace najdete 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í do rutiny ForEach-Object. Rutina ForEach-Object vytvoří nový objekt System.Management.Automation.CompletionResult a naplní ho názvem aktuální služby (reprezentovanou proměnnou kanálu $_.Name).

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

  • completionText (String) – text, který se použije jako výsledek automatického dokončování. Toto je hodnota odeslaná do příkazu.
  • listItemText (Řetězec) – 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 je viditelné, když uživatel vybere položku po stisknutí klávesy Ctrl+mezerník.

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

K zadání dokončování tabulátoru nativního příkazu můžete použít parametr Native. Následující příklad přidá dokončování tabulátoru pro rozhraní příkazového řádku (CLI) dotnet.

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řebírá požadované parametry, které se předávají, když uživatel stiskne Tabulátor. Další informace najdete v popisu parametru ScriptBlock.

V bloku skriptu provede příkaz dotnet complete dokončení tabulátoru. Výsledky se předávají do rutiny ForEach-Object, která používá novou statickou metodu třídy System.Management.Automation.CompletionResult 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 parametrů ParameterName nebo Native, příkaz se chová, jako kdybyste zadali parametr Native. Při registraci dokončování argumentů pro příkazy PowerShellu vždy zadejte parametr ParameterName.

Pokud tento parametr nezadáte, PowerShell zaregistruje dokončení argumentu pro zadaný 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 naleznete 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 parametru ParameterName nebo Nativní, bude se příkaz chovat, jako byste zadali parametr Native.

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-Object, Where-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 System.Management.Automation.CompletionResult objekty pro každou hodnotu, aby se zlepšilo uživatelské prostředí. Vrácení CompletionResult objektů umožňuje definovat popisy a vlastní položky seznamu zobrazené, když uživatelé stisknou klávesu Ctrl+mezerník, aby se zobrazil seznam 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 (Position 0, String) – Tento parametr je nastaven na název příkazu, pro který blok skriptu poskytuje dokončování tabulátoru.
  • $parameterName (Position 1, String) – Tento parametr je nastaven na parametr, jehož hodnota vyžaduje dokončení tabulátoru.
  • $wordToComplete (Position 2, String) – tento parametr je nastaven na hodnotu, kterou uživatel zadal, než stiskne tabulátoru. Blok skriptu by měl tuto hodnotu použít k určení hodnot dokončení tabulátoru.
  • $commandAst (Position 3, CommandAst) – Tento parametr je nastavený na abstraktní strom syntaxe (AST) pro aktuální vstupní řádek. Další informace naleznete v tématu Třídy CommandAst.
  • $fakeBoundParameters (Position 4 IDictionary) – tento parametr je nastavený na hashtable obsahující $PSBoundParameters rutiny, než uživatel stiskl tabulátoru. Další informace naleznete v tématu about_Automatic_Variables.

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

  • $wordToComplete (Position 0, String) – tento parametr je nastaven na hodnotu, kterou uživatel zadal předtím, než stiskne tabulátoru. 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 abstraktní strom syntaxe (AST) pro aktuální vstupní řádek. Další informace naleznete v tématu Třídy CommandAst.
  • $cursorPosition (Pozice 2, Int32) – tento parametr je nastaven na pozici kurzoru, když uživatel stiskl tabulátoru.

Můžete také zadat ArgumentCompleter jako atribut parametru. Další informace naleznete 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.