Udostępnij za pośrednictwem

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.

Po wywołaniu tego polecenia za pomocą parametru CommandName i bez parametrów ParameterName lub Native polecenie jest uruchamiane tak, jakby określono parametr Native. Zapobiega to pracy elementu completer argumentu dla parametrów poleceń programu PowerShell. Zawsze określ parametr ParameterName , jeśli chcesz zarejestrować moduł uzupełniania argumentów dla poleceń programu PowerShell.

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.

$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

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane po naciśnięciu Tab przez użytkownika. 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 Tab. Filtrowane identyfikatory są przesyłane potokami do ForEach-Object polecenia cmdlet, które otacza każdą wartość w cudzysłowach w celu obsługi wartości zawierających spacje.

Drugie polecenie rejestruje moduł completer argumentów, przekazując blok scriptblock, identyfikator ParametrName i CommandName Set-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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane po naciśnięciu Tab przez użytkownika. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock .

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 Ctrl+Spacja. Program PowerShell używa go tylko do wyświetlania. Po wybraniu polecenia nie jest przekazywany do polecenia.
  • resultType (CompletionResultType) — typ wyniku ukończenia.
  • toolTip (ciąg) — tekst etykietki narzędzia ze szczegółami wyświetlanymi na temat obiektu. Jest to widoczne, gdy użytkownik wybierze element po naciśnięciu Ctrl+Spacja.

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

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

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane po naciśnięciu Tab przez użytkownika. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock .

W bloku skryptu dotnet complete polecenie wykonuje uzupełnianie 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 obiektu CompletionResult dla każdej wartości.

Parametry

-CommandName

Określa nazwę co najmniej jednego polecenia do zarejestrowania modułu uzupełniania argumentów. Ten parametr jest obowiązkowy dla poleceń natywnych.

Po określeniu tego parametru bez parametrów ParameterName lub Native polecenie zachowuje się tak, jakby określono parametr Native. Podczas rejestrowania modułów uzupełniania argumentów dla poleceń programu PowerShell należy zawsze określić parametr ParameterName .

Jeśli nie określisz tego parametru, program PowerShell zarejestruje moduł uzupełniania argumentów dla określonej nazwy parametru we wszystkich poleceniach programu PowerShell.

Typ:String[]
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Native

Wskazuje, że argument completer jest przeznaczony dla natywnego polecenia, w którym program PowerShell nie może ukończyć nazw parametrów.

Typ:SwitchParameter
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-ParameterName

Określa nazwę parametru, do których ma zastosowanie completer argumentu. Typ określonych parametrów nie może być wyliczeniem, takim jak parametr Write-Host ForegroundColor polecenia cmdlet.

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

Podczas rejestrowania modułu uzupełniania argumentów dla poleceń programu PowerShell zawsze określ ten parametr. Po określeniu parametru CommandName bez parametrów ParameterName lub Native polecenie zachowuje się tak, jakby określono parametr Natywny.

Typ:String
Position:Named
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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 może również zwracać obiekty System.Management.Automation.CompletionResult dla każdej wartości w celu ulepszenia środowiska użytkownika. Zwracanie obiektów CompletionResult umożliwia definiowanie etykietek narzędzi i niestandardowych wpisów listy wyświetlanych, gdy użytkownicy naciskają Ctrl+Spacja, aby wyświetlić listę dostępnych uzupełnień.

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 (Położenie 0, Ciąg) — ten parametr jest ustawiony na nazwę polecenia, dla którego blok skryptu udostępnia uzupełnianie kart.
  • $parameterName (Pozycja 1, Ciąg) — ten parametr jest ustawiony na parametr, którego wartość wymaga ukończenia karty.
  • $wordToComplete (Położenie 2, Ciąg) — ten parametr jest ustawiony na wartość podaną przez użytkownika przed naciśnięciem Tab. Blok skryptu powinien używać tej wartości do określania wartości uzupełniania tabulacji.
  • $commandAst (Położenie 3, CommandAst) — ten parametr jest ustawiony na abstrakcyjne drzewo składni (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz CommandAst Class (Klasa CommandAst).
  • $fakeBoundParameters (Położenie 4 IDictionary) — ten parametr jest ustawiony na tabelę skrótu zawierającą $PSBoundParameters wartość dla polecenia cmdlet, zanim użytkownik naciśnie kartę. 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 (Położenie 0, Ciąg) — ten parametr jest ustawiony na wartość podaną przez użytkownika przed naciśnięciem Tab. Blok skryptu powinien używać tej wartości do określania wartości uzupełniania tabulacji.
  • $commandAst (Pozycja 1, CommandAst) — ten parametr jest ustawiony na abstrakcyjne drzewo składni (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz CommandAst Class (Klasa CommandAst).
  • $cursorPosition (Położenie 2, Int32) — ten parametr jest ustawiony na położenie kursora po naciśnięciu Tab przez użytkownika.

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

Typ:ScriptBlock
Position:Named
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

Dane wejściowe

None

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

Dane wyjściowe

None

To polecenie cmdlet nie zwraca żadnych danych wyjściowych.