Register-ArgumentCompleter

Odwołanie

Moduł:: Microsoft.PowerShell.Core

Rejestruje niestandardowy moduł uzupełniania argumentów.

Składnia

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

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

Opis

Polecenie Register-ArgumentCompleter cmdlet rejestruje niestandardowy moduł uzupełniania argumentów. Moduł uzupełniania argumentów umożliwia zapewnienie dynamicznego uzupełniania kart w czasie wykonywania dla dowolnego określonego polecenia.

Przykłady

Przykład 1. Rejestrowanie niestandardowego modułu uzupełniania argumentów

Poniższy przykład rejestruje kompletny moduł argumentu dla parametru Set-TimeZone Id polecenia cmdlet.

$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

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane, gdy użytkownik naciska kartę. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock .

W bloku skryptu dostępne wartości identyfikatora są pobierane przy użyciu Get-TimeZone polecenia cmdlet . Właściwość Id dla każdej strefy czasowej jest potokowana do Where-Object polecenia cmdlet . Polecenie Where-Object cmdlet filtruje wszystkie identyfikatory, które nie zaczynają się od wartości podanej przez $wordToCompleteelement , która reprezentuje tekst wpisany przez użytkownika przed naciśnięciem klawisza Tab. Filtrowane identyfikatory są przesyłane potokami do ForEach-Object polecenia cmdlet, które otacza każdą wartość cudzysłowami, jeśli wartość zawiera spacje.

Drugie polecenie rejestruje completer argumentów, przekazując scriptblock, identyfikator ParametrNamei CommandNameSet-TimeZone.

Przykład 2. Dodawanie szczegółów do wartości uzupełniania karty

Poniższy przykład zastępuje uzupełnianie tabulacji parametru Stop-Service Name polecenia cmdlet i zwraca tylko uruchomione usługi.

$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

W bloku skryptu pierwsze polecenie pobiera wszystkie uruchomione usługi przy użyciu Where-Object polecenia cmdlet . Usługi są przesyłane potokami do ForEach-Object polecenia cmdlet. Polecenie ForEach-Object cmdlet tworzy nowy obiekt System.Management.Automation.CompletionResult i wypełnia go nazwą bieżącej usługi (reprezentowaną przez zmienną potoku $_.Name).

Obiekt CompletionResult umożliwia podanie dodatkowych szczegółów dla każdej zwróconej wartości:

completionText (Ciąg) — tekst, który ma być używany jako wynik automatycznego uzupełniania. Jest to wartość wysłana do polecenia .
listItemText (ciąg) — tekst, który ma być wyświetlany na liście, na przykład gdy użytkownik naciska klawisze Ctrl+Spacja. Jest on używany tylko do wyświetlania i nie jest przekazywany do polecenia po wybraniu.
resultType (CompletionResultType) — typ wyniku ukończenia.
toolTip (ciąg) — tekst etykietki narzędzia ze szczegółami, które mają być wyświetlane na temat obiektu. Jest to widoczne, gdy użytkownik wybierze element po naciśnięciu klawisza Ctrl+Spacja.

Ostatnie polecenie pokazuje, że zatrzymane usługi mogą być nadal przekazywane ręcznie do Stop-Service polecenia cmdlet. Ukończenie karty jest jedynym aspektem, którego dotyczy problem.

Przykład 3. Rejestrowanie niestandardowego modułu uzupełniania argumentów natywnych

Możesz użyć parametru Natywny, aby zapewnić uzupełnianie tabulatorem dla natywnego polecenia. W poniższym przykładzie dodano uzupełnianie tabulacji dla interfejsu dotnet wiersza polecenia (CLI).

Uwaga

Polecenie dotnet complete jest dostępne tylko w wersji 2.0 i nowszej interfejsu wiersza polecenia 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

W bloku skryptu dotnet complete polecenie służy do wykonywania uzupełniania karty. Wyniki są przesyłane potokiem do ForEach-Object polecenia cmdlet, które używa nowej metody statycznej klasy System.Management.Automation.CompletionResult w celu utworzenia nowego obiektu CompletionResult dla każdej wartości.

Parametry

-CommandName

Określa nazwę poleceń jako tablicę.

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

-Native

Wskazuje, że argument completer jest przeznaczony dla natywnego polecenia, w którym program PowerShell nie może uzupełnić nazw parametrów.

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

-ParameterName

Określa nazwę parametru, którego argument jest ukończony. Określona nazwa parametru nie może być wyliczona wartością, taką jak parametr Write-Host ForegroundColor polecenia cmdlet.

Aby uzyskać więcej informacji na temat wyliczenia, zobacz about_Enum.

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

-ScriptBlock

Określa polecenia do uruchomienia w celu wykonania ukończenia karty. Podany blok skryptu powinien zwracać wartości, które zakończą wprowadzanie danych wejściowych. Blok skryptu musi wyrejestrować wartości przy użyciu potoku (ForEach-Object, Where-Objectitp.) lub innej odpowiedniej metody. Zwracanie tablicy wartości powoduje, że program PowerShell traktuje całą tablicę jako jedną wartość uzupełniania tabulacji.

Blok skryptu musi zaakceptować następujące parametry w kolejności określonej poniżej. Nazwy parametrów nie są ważne, ponieważ program PowerShell przekazuje wartości według pozycji.

$commandName (Pozycja 0) — ten parametr jest ustawiony na nazwę polecenia, dla którego blok skryptu udostępnia uzupełnianie kart.
$parameterName (Pozycja 1) — ten parametr jest ustawiony na parametr, którego wartość wymaga ukończenia karty.
$wordToComplete (Pozycja 2) — ten parametr jest ustawiony na wartość podaną przez użytkownika przed naciśnięciem klawisza Tab. Blok skryptu powinien używać tej wartości do określania wartości uzupełniania tabulacji.
$commandAst (Pozycja 3) — ten parametr jest ustawiony na abstrakcyjne drzewo składni (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz Ast Class (Klasa Ast).
$fakeBoundParameters (Pozycja 4) — ten parametr jest ustawiony na tabelę skrótową zawierającą $PSBoundParameters polecenie cmdlet przed naciśnięciem klawisza Tab przez użytkownika. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

Po określeniu parametru Natywny blok skryptu musi przyjąć następujące parametry w określonej kolejności. Nazwy parametrów nie są ważne, ponieważ program PowerShell przekazuje wartości według pozycji.

$wordToComplete (Pozycja 0) — ten parametr jest ustawiony na wartość podaną przez użytkownika przed naciśnięciem klawisza Tab. Blok skryptu powinien używać tej wartości do określania wartości uzupełniania tabulacji.
$commandAst (Pozycja 1) — ten parametr jest ustawiony na abstrakcyjne drzewo składni (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz Ast Class (Klasa Ast).
$cursorPosition (Pozycja 2) — ten parametr jest ustawiony na położenie kursora po naciśnięciu klawisza Tab przez użytkownika.

Możesz również podać argumentCompleter jako atrybut parametru. Aby uzyskać więcej informacji, zobacz about_Functions_Advanced_Parameters.

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

Dane wejściowe

None

Nie można potokować obiektów do tego polecenia cmdlet.

Dane wyjściowe