Register-ArgumentCompleter

Modul:: Microsoft.PowerShell.Core Module

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

Syntax

NativeSet

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

PowerShellSet

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

Description

Cmdlet Register-ArgumentCompleter zaregistruje vlastní doplňovač 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. Tomu brání automatické doplňování argumentů pro parametry příkazů PowerShell. Vždy specifikujte parametr ParameterName, pokud chcete zaregistrovat dovršovač argumentů pro příkazy v PowerShellu.

Příklady

Příklad 1: Registrace vlastního doplňovače 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ří skriptblock, 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 rámci skriptublock se pomocí rutiny načtou Get-TimeZone 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, což představuje text, který uživatel zadal, když stiskne tabulátor. Filtrované ID jsou předány 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 scriptblocku, ParameterNameId a CommandNameSet-TimeZone.

Příklad 2: Přidání podrobností do hodnot automatického doplňování

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

V rámci skriptublock načte první příkaz všechny spuštěné služby pomocí rutiny Where-Object . Služby se předávají do cmdletu 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í. Když je vybráno, není to předáno příkazu.
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 kompleteru argumentů

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í příkazů pomocí tabulátoru pro dotnet rozhraní příkazového řádku (CLI).

Poznámka:

Příkaz dotnet complete je k dispozici pouze ve verzi 2.0 a vyšší příkazového nástroje 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

V rámci skriptublock provede dotnet complete příkaz 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čovače 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.

Vlastnosti parametru

Typ:	String[]
Default value:	None
Podporuje zástupné znaky:	False
DontShow:	False

Sady parametrů

NativeSet

Position:	Named
Povinné:	True
Hodnota z kanálu:	False
Hodnota z kanálu podle názvu vlastnosti:	False
Hodnota ze zbývajících argumentů:	False

PowerShellSet

Position:	Named
Povinné:	False
Hodnota z kanálu:	False
Hodnota z kanálu podle názvu vlastnosti:	False
Hodnota ze zbývajících argumentů:	False

-Native

Označuje, že dokončovač argumentů je určen pro nativní příkaz, kde PowerShell nemůže automaticky doplnit názvy parametrů.

Vlastnosti parametru

Typ:	SwitchParameter
Default value:	None
Podporuje zástupné znaky:	False
DontShow:	False

Sady parametrů

NativeSet

Position:	Named
Povinné:	False
Hodnota z kanálu:	False
Hodnota z kanálu podle názvu vlastnosti:	False
Hodnota ze zbývajících argumentů:	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 příkazu 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 parametru ParameterName nebo Nativní, bude se příkaz chovat, jako byste zadali parametr Native.

Vlastnosti parametru

Typ:	String
Default value:	None
Podporuje zástupné znaky:	False
DontShow:	False

Sady parametrů

PowerShellSet

Position:	Named
Povinné:	True
Hodnota z kanálu:	False
Hodnota z kanálu podle názvu vlastnosti:	False
Hodnota ze zbývajících argumentů:	False

-ScriptBlock

Určuje příkazy, které se mají spustit, aby se provedlo dokončování tabulátoru. Zadaný skriptový blok by měl vrátit hodnoty, které dokončí vstup. Skriptblock 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.

Skriptblock může také vrátit Objekty System.Management.Automation.CompletionResult pro každou hodnotu, aby se zlepšilo uživatelské prostředí. Vrácení CompletionResult objektů vám umožňuje definovat vyskakovací nápovědy a vlastní položky seznamu, které se zobrazí, když uživatelé stisknou klávesy Ctrl+Space pro zobrazení seznamu dostupných dokončení.

Skriptblock 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ý skriptblock 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 (Pozice 2, Řetězec) – Tento parametr je nastaven na hodnotu, kterou uživatel zadal před stisknutím klávesy Tab. Skriptblock 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řída CommandAst.
(Position 4 IDictionary) – tento parametr je nastavený na hashtable obsahující rutiny, než uživatel stiskltabulátoru . Další informace naleznete v tématu about_Automatic_Variables.

Když zadáte nativní parametr, skriptblock musí 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 (Pozice 0, Řetězec) – Tento parametr je nastaven na hodnotu, kterou uživatel zadal před stisknutím klávesy Tab. Skriptblock 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řída CommandAst.
$cursorPosition (Pozice 2, Int32) – tento parametr je nastaven na pozici kurzoru, když uživatel stiskl klávesu Tab.

Můžete také zadat ArgumentCompleter jako atribut parametru. Další informace naleznete v části about_Functions_Advanced_Parameters.

Vlastnosti parametru

Typ:	ScriptBlock
Default value:	None
Podporuje zástupné znaky:	False
DontShow:	False

Sady parametrů

(All)

Position:	Named
Povinné:	True
Hodnota z kanálu:	False
Hodnota z kanálu podle názvu vlastnosti:	False
Hodnota ze zbývajících argumentů:	False

CommonParameters

Tato rutina podporuje běžné parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction a -WarningVariable. Další informace najdete v about_CommonParameters.

Vstupy

None

Do tohoto cmdletu nemůžete předávat objekty.

Výstupy

None

Tento cmdlet nevrátí žádný výstup.

o_Funkcích_Dokončení_Argumentu

Váš názor

Byla tato stránka užitečná?

Sdílet prostřednictvím

Register-ArgumentCompleter

Syntax

NativeSet

PowerShellSet

Description

Příklady

Příklad 1: Registrace vlastního doplňovače argumentů

Příklad 2: Přidání podrobností do hodnot automatického doplňování

Příklad 3: Registrace vlastního nativního kompleteru argumentů

Parametry

-CommandName

Vlastnosti parametru

Sady parametrů

-Native

Vlastnosti parametru

Sady parametrů

-ParameterName

Vlastnosti parametru

Sady parametrů

-ScriptBlock

Vlastnosti parametru

Sady parametrů

CommonParameters

Vstupy

None

Výstupy

None

Související odkazy

Váš názor