Register-ArgumentCompleter

Moduł:: Microsoft.PowerShell.Core Module

Rejestruje niestandardowy moduł uzupełniania argumentów.

Składnia

NativeSet

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

PowerShellSet

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

Opis

Polecenie cmdlet Register-ArgumentCompleter 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.

Wywołając to polecenie za pomocą parametru CommandName i bez parametru ParameterName lub Native parametrów, 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, gdy 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 completer argumentu dla parametru identyfikatora 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, gdy użytkownik naciska kartę. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock .

W ramach skryptblock 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 polecenia cmdlet Where-Object. Polecenie cmdlet Where-Object filtruje wszystkie identyfikatory, które nie zaczynają się od wartości podanej przez $wordToComplete, która reprezentuje tekst wpisany przez użytkownika przed naciśnięciem tab. Filtrowane identyfikatory są przesyłane potokami do polecenia cmdlet ForEach-Object, które otacza każdą wartość w cudzysłowach w celu obsługi wartości zawierających spacje.

Drugie polecenie rejestruje completer argumentów, przekazując skryptblock, Nazwa parametruid i CommandNameSet-TimeZone.

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

Poniższy przykład zastępuje uzupełnianie kart dla parametru nazwa 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

W ramach skryptblock pierwsze polecenie pobiera wszystkie uruchomione usługi przy użyciu Where-Object polecenia cmdlet . Usługi są przesyłane potokami do polecenia cmdlet ForEach-Object. Polecenie cmdlet ForEach-Object 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+spacji. 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+spacji.

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

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

Uwaga / Notatka

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

W ramach skryptblock dotnet complete polecenie wykonuje uzupełnianie karty. Wyniki są przesyłane potokiem do polecenia cmdlet ForEach-Object, które używa nowej metody statycznejSystem.Management.Automation.CompletionResult, aby utworzyć obiekt 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 parametru ParameterName lub parametrów Native polecenie zachowuje się tak, jakby określono parametr Native. Podczas rejestrowania modułów uzupełniania argumentów dla poleceń programu PowerShell zawsze określ parametr ParameterName.

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

Właściwości parametrów

Typ:	String[]
Wartość domyślna:	None
Wspiera dzikie karty:	False
DontShow:	False

Zbiory parametrów

NativeSet

Pozycja:	Named
Obowiązkowy:	True
Wartość z pipeline:	False
Wartość z pipeline według nazwy właściwości:	False
Wartość pozostałych argumentów:	False

PowerShellSet

Pozycja:	Named
Obowiązkowy:	False
Wartość z pipeline:	False
Wartość z pipeline według nazwy właściwości:	False
Wartość pozostałych argumentów:	False

-Native

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

Właściwości parametrów

Typ:	SwitchParameter
Wartość domyślna:	None
Wspiera dzikie karty:	False
DontShow:	False

Zbiory parametrów

NativeSet

Pozycja:	Named
Obowiązkowy:	False
Wartość z pipeline:	False
Wartość z pipeline według nazwy właściwości:	False
Wartość pozostałych argumentów:	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 ForegroundColor parametr polecenia cmdlet Write-Host.

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 parametru ParameterName lub parametrów Native polecenie zachowuje się tak, jakby określono parametr Native.

Właściwości parametrów

Typ:	String
Wartość domyślna:	None
Wspiera dzikie karty:	False
DontShow:	False

Zbiory parametrów

PowerShellSet

Pozycja:	Named
Obowiązkowy:	True
Wartość z pipeline:	False
Wartość z pipeline według nazwy właściwości:	False
Wartość pozostałych argumentów:	False

-ScriptBlock

Określa polecenia do uruchomienia w celu wykonania ukończenia karty. Podany skryptblock 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 tabulatora.

Blok scriptblock może również zwracać obiekty System.Management.Automation.CompletionResult dla każdej wartości w celu ulepszenia środowiska użytkownika. Zwracanie CompletionResult obiektów umożliwia zdefiniowanie 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 podanej poniżej kolejności. Nazwy parametrów nie są ważne, ponieważ program PowerShell przekazuje wartości według pozycji.

$commandName (Pozycja 0, Ciąg) — ten parametr jest ustawiony na nazwę polecenia, dla którego skryptblock udostępnia uzupełnianie tabulacji.
$parameterName (pozycja 1, ciąg) — ten parametr jest ustawiony na parametr, którego wartość wymaga ukończenia karty.
$wordToComplete (Pozycja 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 (pozycja 3, CommandAst) — ten parametr jest ustawiony na drzewo składni abstrakcyjnej (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz CommandAst Class.
$fakeBoundParameters (pozycja 4 IDictionary) — ten parametr jest ustawiony na tabelę skrótu zawierającą $PSBoundParameters dla polecenia cmdlet, zanim użytkownik nacisnął Tab. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

Po określeniu parametru Natywny blok skrypt 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, 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 drzewo składni abstrakcyjnej (AST) dla bieżącego wiersza wejściowego. Aby uzyskać więcej informacji, zobacz CommandAst Class.
$cursorPosition (pozycja 2, Int32) — ten parametr jest ustawiany na położenie kursora, gdy użytkownik naciśnie kartę .

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

Właściwości parametrów

Typ:	ScriptBlock
Wartość domyślna:	None
Wspiera dzikie karty:	False
DontShow:	False

Zbiory parametrów

(All)

Pozycja:	Named
Obowiązkowy:	True
Wartość z pipeline:	False
Wartość z pipeline według nazwy właściwości:	False
Wartość pozostałych argumentów:	False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Wejścia

None

Nie można przekazywać obiektów do tego cmdletu.

Wyjść

None

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

dotyczące_Uzupełniania_Argumentów_Funkcji

Sprzężenie zwrotne

Czy ta strona była pomocna?

Udostępnij przez

Register-ArgumentCompleter

Składnia

NativeSet

PowerShellSet

Opis

Przykłady

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

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

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

Parametry

-CommandName

Właściwości parametrów

Zbiory parametrów

-Native

Właściwości parametrów

Zbiory parametrów

-ParameterName

Właściwości parametrów

Zbiory parametrów

-ScriptBlock

Właściwości parametrów

Zbiory parametrów

CommonParameters

Wejścia

None

Wyjść

None

Powiązane linki

Sprzężenie zwrotne