Jak używać ArgumentCompleter i Register-ArgumentCompleter w programie PowerShell

W poniższych wierszach zobaczymy spokojnie i na jasnych przykładach, jak używać Register-ArgumentCompleter, atrybuty ArgumentCompletion, ArgumentCompletions i ValidateSet oraz klasy niestandardowe aby uzyskać bardzo zaawansowane środowisko autouzupełniania w programie PowerShell. Zobaczysz zarówno proste przypadki, jak i znacznie bardziej zaawansowane scenariusze, w tym jak zintegrować je z Twoim Profil programu PowerShell jak utrzymać go zawsze aktywnym i jak go używać również z poleceniami natywnymi, takimi jak dotnet lub interfejsów CLI innych firm.

Czym jest Register-ArgumentCompleter i jaki problem rozwiązuje?

Polecenie cmdlet Register-ArgumentCompleter służy do zarejestruj niestandardowy moduł uzupełniania argumentówInnymi słowy, informujesz program PowerShell, co ma sugerować użytkownikowi po naciśnięciu klawisza zakładka podczas wypełniania wartości parametru lub polecenia natywnego.

Ten moduł uzupełniający działa na czas wykonaniaDzięki temu możesz dynamicznie obliczać sugestie: poszukaj poleceń cmdlet, takich jak Get-TimeZonefiltruj usługi za pomocą Get-Service, wywołaj CLI jako dotnet completeOdczyt interfejsu REST API, sprawdzanie systemu plików itd. odbywa się za pośrednictwem... Blok skryptów która zwraca możliwe wartości autouzupełniania.

Ważnym szczegółem jest zachowanie parametru CommandName : jeśli użyjesz go bez określenia parametru ParameterName lub Native , program PowerShell potraktuje wywołanie tak, jakbyś dodał parametr -Native . Oznacza to, że funkcja uzupełniania nie będzie działać na parametrach poleceń cmdlet programu PowerShell, a jedynie jako funkcja uzupełniania poleceń natywnych. Dlatego, jeśli celem jest uzupełnienie parametrów polecenia cmdlet lub funkcji programu PowerShell, zawsze musisz określić parametr ParameterName.

Podstawowa składnia Register-ArgumentCompleter

Zestaw parametrów dla poleceń natywnych (NativeSet)

Aby zarejestrować moduł uzupełniania argumentów dla polecenia natywnego, należy użyć następującej składni, gdzie kluczem jest modyfikator -Native :

Typowa składnia: Register-ArgumentCompleter -CommandName <String[]> -ScriptBlock <ScriptBlock> -Native

W tym przypadku parametr CommandName jest obowiązkowy , ponieważ program PowerShell musi wiedzieć, z którym poleceniem natywnym skojarzyć funkcję uzupełniania. ScriptBlock otrzyma inny zestaw parametrów niż funkcje uzupełniania poleceń cmdlet programu PowerShell, jak zobaczymy później, i zostanie zaprojektowany tak, aby interpretować cały wiersz i pozycję kursora.

Zestaw parametrów polecenia cmdlet programu PowerShell (PowerShellSet)

Jeśli chcesz dodać funkcję autouzupełniania do jednego lub większej liczby parametrów poleceń cmdlet lub funkcji programu PowerShell, najczęstsza składnia jest następująca:

Typowa składnia: Register-ArgumentCompleter -ParameterName <String> -ScriptBlock <ScriptBlock> >]

W tym przypadku parametr ParameterName jest wymagany i definiuje, do którego parametru zostanie zastosowane uzupełnienie. Parametr CommandName jest opcjonalny : można ograniczyć uzupełnienie do jednego lub kilku konkretnych poleceń. Jeśli zostanie pominięty, program PowerShell zarejestruje to uzupełnienie dla danej nazwy parametru we wszystkich poleceniach, które je zawierają.

Kluczowe parametry Register-ArgumentCompleter

Parametr -NazwaPolecenia

Parametr `-CommandName` określa, dla którego polecenia lub poleceń zostanie zarejestrowany moduł uzupełniający. Akceptuje on tablicę ciągów znaków , dzięki czemu można powiązać ten sam `ScriptBlock` z wieloma poleceniami cmdlet lub narzędziami natywnymi jednocześnie.

W przypadku użycia w zestawie parametrów NativeSet jest on obowiązkowy , ponieważ natywnych funkcji uzupełniania nie można zarejestrować generycznie bez wskazania konkretnego pliku binarnego lub polecenia. W zestawie PowerShellSet jest on opcjonalny, ale, jak wspomniano wcześniej, użycie go bez parametru ParameterName lub Native spowoduje, że PowerShell zinterpretuje to jako utworzenie natywnego funkcji uzupełniania.

Parametr - Natywny

Modyfikator -Rodzinny informuje program PowerShell, że należy zastosować narzędzie do uzupełniania polecenia natywneTo znaczy, zewnętrzne pliki wykonywalne, w których PowerShell nie kontroluje ani nie może uzupełniać nazw parametrów. Rozważmy dotnet, winget, aws lub dowolnego innego interfejsu wiersza poleceń opartego na .NET, Python lub podobne.

W tym trybie ScriptBlock otrzymuje mniej parametrów i w innym celu: tekst, który został napisany, AST polecenia i pozycja kursoraStamtąd zazwyczaj scenariusz Wywołuje sam interfejs CLI, aby zwrócić sugestie, tak jak ma to miejsce w przypadku dotnet complete.

Parametr -NazwaParametru

Parametr -ParameterName Określa nazwę parametru, do którego zostanie zastosowane uzupełnianie argumentów. Istnieje jedno ważne ograniczenie: typ tego parametru. To nie może być listaNa przykład, jeśli parametr używa typu takiego jak Kolor pierwszego planu de Write-HostNie można użyć Register-ArgumentCompleter, aby tego dokonać.

Rejestrując funkcje uzupełniania poleceń cmdlet lub funkcji programu PowerShell, zdecydowanie zaleca się zawsze używanie parametru ParameterName . Jeśli zapomnisz i użyjesz tylko parametru CommandName, przypadkowo zarejestrujesz natywny moduł uzupełniania i nie zobaczysz sugestii dotyczących interesującego Cię parametru.

Parametr -ScriptBlock

Sercem każdego dopełniacza jest Blok skryptówTen blok skryptu definiuje logikę generującą wartości do zasugerowania po naciśnięciu przez użytkownika zakładkaNajważniejsze jest to, że ScriptBlock musi zwróć elementy przez potokNa przykład z ForEach-Object o Where-Objectzamiast zwracać pojedynczą tablicę, ponieważ jeśli zostanie zwrócona niepowiązana tablica, program PowerShell zinterpretuje ją jako pojedyncza wartość autouzupełniania.

Ponadto ScriptBlock może bezpośrednio zwracać ciągi znaków lub obiekty System.Management.Automation.CompletionResult , co zapewnia znacznie większą elastyczność, ponieważ pozwala zdefiniować tekst do uzupełnienia, tekst do wyświetlenia na liście, typ wyniku oraz opis lub podpowiedź.

Parametry ScriptBlock dla modułów uzupełniających programu PowerShell

W przypadku normalnych (nie natywnych) wypełniaczy ScriptBlock musi zaakceptować pięć parametrów w tej kolejności, niezależnie od ich nazw:

• $commandName: ciąg zawierający nazwę polecenia, dla którego obliczane jest zakończenie.
• $parameterName: ciąg zawierający nazwę uzupełnianego parametru.
• $wordToComplete: ciąg zawierający to, co użytkownik wpisał tuż przed naciśnięciem zakładka.
• $commandAst: Obiekt CommandAst, który reprezentuje abstrakcyjne drzewo składniowe obecnej linii.
• $fakeBoundParameters: typ słownika Słownik który replikuje zawartość $PSBoundParameters w momencie naciśnięcia zakładka.

Parametr $wordToComplete Często stosuje się go do filtrowania wartości za pomocą operatorów takich jak: -liketak, aby sugerowane były tylko elementy zaczynające się od tego, co użytkownik już wpisał. Tymczasem, $fakeBoundParameters Umożliwia tworzenie wypełniaczy zależnych od innych parametrów, co zobaczymy na przykładzie owoców i warzyw.

Parametry ScriptBlock dla natywnych wypełniaczy

Podczas używania opcji -Native , ScriptBlock otrzymuje trzy parametry, również według pozycji:

• $wordToComplete (pozycja 0): tekst, który użytkownik wpisał przed naciśnięciem klawisza zakładka.
• $commandAst (pozycja 1): drzewo składniowe całego polecenia, a nie tylko bieżącego argumentu.
• Pozycja kursora (pozycja 2): indeks pozycji kursora w wierszu.

Ten format bardzo dobrze pasuje do interfejsów CLI, które udostępniają własny system autouzupełniania. Typowy przypadek to dotnet complete, który odbiera wiersz i pozycję kursora i zwraca sugestie w postaci zwykłego tekstu, które są następnie przekształcane w Wynik ukończenia.

Praktyczne przykłady z Register-ArgumentCompleter

Przykład 1: Dynamiczne wypełnianie stref czasowych

Wyobraź sobie, że chcesz maksymalnie ułatwić korzystanie z polecenia cmdlet. Set-TimeZone umożliwiając użytkownikowi uzupełnienie parametru Id za pomocą klawisza Tab. Możesz utworzyć blok skryptów, który pobiera wszystkie strefy czasowe za pomocą Get-TimeZone -ListAvailableFiltruj według tego, co wpisał użytkownik, i ujmuj każdą wartość w cudzysłów, jeśli występują spacje:

Przykładowy skrypt 1: $script = {<br> param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)<br> (Get-TimeZone -ListAvailable).Id |<br> Where-Object { $_ -like "$wordToComplete*" } |<br> ForEach-Object { "'$_'" }<br>}<br>Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $script

Dzięki temu, kiedy piszesz Set-TimeZone -Id i zacznij pisać, gdy naciśniesz zakładka będziesz miał jeden Lista przefiltrowanych identyfikatorów stref czasowych Na podstawie tego, co napisałeś. Pojedyncze cudzysłowy zostały dodane, aby uniknąć problemów z identyfikatorami zawierającymi spacje.

Przykład 2: Wzbogacone sugestie z CompletionResult

W drugim scenariuszu chcesz, aby podczas korzystania Stop-Service -Name tylko się pojawiają usługi w tokui chcesz również wyświetlić dodatkowe informacje na liście sugestii, gdy użytkownik naciśnie Ctrl+Espacio.

Przykładowy skrypt 2 (CompletionResult): $script = {<br> param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)<br> $services = Get-Service | Where-Object {<br> $_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"<br> }<br> $services | ForEach-Object {<br> New-Object -TypeName System.Management.Automation.CompletionResult -ArgumentList @(<br> $_.Name, # completionText<br> $_.Name, # listItemText<br> 'ParameterValue', # resultType<br> $_.Name # toolTip<br> )<br> }<br>}<br>Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $script

Zwróć uwagę na te pola: W każdym obiekcie CompletionResult możesz kontrolować te kluczowe pola, aby uzyskać bardziej dopracowane wrażenia:

• tekstuukończenia: tekst, który jest faktycznie wstawiany do polecenia po wybraniu sugestii.
• listItemText: tekst wyświetlany na liście propozycji; może różnić się od wstawionego ciągu znaków.
• typ wyniku: typ wyniku (na przykład, ParameterValue).
• podpowiedź: opis, który pojawia się po wybraniu elementu na liście ukończonych elementów, szczególnie przydatny w przypadku Ctrl+Espacio.

Przykład 3: Natywny moduł uzupełniania dla interfejsu wiersza poleceń dotnet

Można również użyć Register-ArgumentCompleter w celu rozszerzenia funkcji autouzupełniania. natywne narzędziaKlasycznym przykładem jest dotnet, który zawiera podpolecenie dotnet complete aby zwrócić ukończone elementy na podstawie bieżącego wiersza.

Przykładowy skrypt natywny: $scriptblock = {<br> param($wordToComplete, $commandAst, $cursorPosition)<br> dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {<br> ::new(<br> $_, # completionText<br> $_, # listItemText<br> 'ParameterValue', # resultType<br> $_ # toolTip<br> )<br> }<br>}<br>Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

W tym przykładzie samo polecenie dotnet complete To ten, który wykonuje obliczenia sugestii. ScriptBlock po prostu przekształca dane wyjściowe w obiekty CompletionResult. W ten sposób osiągasz Bardzo płynna integracja między programem PowerShell a zewnętrznym interfejsem CLI, z zakładkami, które znają wszystkie natywne opcje dotnet.

Inne sposoby implementacji uzupełniaczy argumentów

ValidateSet: stałe wartości ze ścisłą walidacją

Atrybut ValidateSet oferuje prosty sposób ograniczenia parametru lub zmiennej do zamkniętego zestawu wartości, umożliwiając jednocześnie uzupełnianie za pomocą klawisza Tab bez konieczności pisania niestandardowego ScriptBlock.

Wyobraź sobie parametr „Owoc ”, który akceptuje tylko wartości „Jabłko”, „Banan” lub „Gruszka”. Możesz go zdefiniować w ten sposób:

Przykładowa definicja: param (<br> <br> <br> ]$Fruit<br>)

Jeśli użytkownik wprowadzi wartość, która nie znajduje się w zestawie, program PowerShell zgłosi błąd walidacji . To samo dotyczy zwykłych zmiennych, a nie tylko parametrów, na przykład:

Deklaracja zmiennej: <br>$Flavor = 'Strawberry'

Za każdym razem, gdy coś jest przypisane $FlavorSkrypt sprawdzi, czy wartość należy do zestawu. Jeśli w dowolnym momencie skryptu wykonasz:

param(<br> <br> $Message<br>)<br>$Message = 'bye'

PowerShell zwróci MetadataError wskazujący , że zmienna nie byłaby już prawidłowa, gdyby zastosowano tę wartość, co pomaga zachować ścisłe kontrakty w skryptach.

Dynamiczny zestaw ValidateSet z klasami

Oprócz zestawów statycznych, PowerShell umożliwia generowanie wartości z Walidacja zestawu dynamicznie przy użyciu klas które implementują interfejs System.Management.Automation.IValidateSetValuesGeneratorW tym modelu klasa udostępnia metodę GetValidValues() która zwraca możliwe opcje.

Typowym przykładem jest klasa SoundNames , która przeszukuje różne foldery systemowe w poszukiwaniu plików dźwiękowych i zwraca ich nazwy bazowe jako prawidłowe wartości:

Przykładowa klasa (SoundNames): class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {<br> ] GetValidValues() {<br> $SoundPaths = '/System/Library/Sounds/', '/Library/Sounds', '~/Library/Sounds'<br> $SoundNames = foreach ($SoundPath in $SoundPaths) {<br> if (Test-Path $SoundPath) {<br> (Get-ChildItem $SoundPath).BaseName<br> }<br> }<br> return ] $SoundNames<br> }<br>}

Później implementujesz klasę jako dynamiczny ValidateSet na parametrze lub zmiennej:

Korzystanie z dynamicznego ValidateSet: param (<br> )]<br> $Sound<br>)

W ten sposób uzyskujesz uzupełnianie za pomocą zakładek, które odzwierciedla rzeczywisty stan systemu plików przy każdym uruchomieniu skryptu.

Uzupełnienia argumentów: sugestie bez sprawdzania wartości

Atrybut ArgumentCompletions pozwala dodać listę sugerowanych wartości do parametru, ale w przeciwieństwie do ValidateSet, nie przeprowadza ścisłej walidacji . Oznacza to , że użytkownik może wybrać jedną z sugestii lub wpisać cokolwiek innego, nawet jeśli nie znajduje się ono na liście.

Jego składnia jest bardzo prosta. Na przykład, możesz zdefiniować funkcję z parametrem Typ , który sugeruje „Owoce” i „Warzywa”, a także parametry Owoce i Warzywa z listami możliwych wartości:

Definicja funkcji: function Test-ArgumentCompletions {<br> <br> param (<br> <br> <br> $Type,<br;<br> <br> <br> $Fruit,<br;<br> <br> <br> $Vegetable<br> )<br>}

Atrybut ten jest idealny, gdy chcesz pomóc użytkownikowi za pomocą przykładów typowych wartości, ale nie chcesz mu zabraniać wprowadzania innych wartości ze względu na wymagania biznesowe lub zgodność ze szczególnymi przypadkami.

ArgumentCompleter: uzupełniacze atrybutów parametrów na poziomie

Atrybut Uzupełniacz argumentów Służy do dołączania bloku skryptów do parametru o tym samym podpisie co zarejestrowane komplety Register-ArgumentCompleterale bez konieczności wywoływania tego polecenia cmdlet. To elegancki sposób na hermetyzację złożona logika autouzupełniania bezpośrednio w definicji funkcji.

Podstawowy przykład: Przykładem zastosowania może być:

Przykład atrybutu: function MyArgumentCompleter {<br> param (<br> <br> <br> $ParamName<br> )<br>}

Podobnie jak w przypadku Register-ArgumentCompleter, ScriptBlock powinien zwracać wartości za pośrednictwem potoku i może wykorzystywać zarówno $wordToComplete , jak i $fakeBoundParameters , a nawet analizować kod AST , aby uwzględnić pełny kontekst polecenia.

Zaawansowany przykład zależności ArgumentCompleter od innego parametru

Bardzo przydatnym wzorcem jest tworzenie kompletnych elementów zależnych od wartości innych parametrów. Wyobraź sobie funkcję z parametrem typu , który może być „Owoce” lub „Warzywa”, oraz parametrem wartości , którego zestaw sugestii zmienia się w zależności od wybranego typu.

Implementacja silnika: function MyArgumentCompleter {<br> param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)<br><br> $possibleValues = @{<br> Fruits = @('Apple','Orange','Banana')<br> Vegetables = @('Onion','Carrot','Lettuce')<br> }<br><br>> if ($fakeBoundParameters.ContainsKey('Type')) {<br> $possibleValues |<br> Where-Object { $_ -like "$wordToComplete*" }<br> } else {<br> $possibleValues.Values | ForEach-Object { $_ }<br> }<br>}

Zużycie wypełniacza: function Test-ArgumentCompleter {<br> <br> param (<br> <br> <br> $Type,<br;<br> <br> <br> $Value<br> )<br>}

W tym scenariuszu, jeśli napiszesz na przykład Test-ArgumentCompleter -Type Fruits -Value A i naciskasz Tab, dzięki użyciu -lubić i ze słownika $fakeBoundParametersWypełniacz zwróci tylko wartości owoców zaczynające się na literę „A”, czyli AppleTo bardzo potężna technika budowania przyjazne dla użytkownika interfejsy wiersza poleceń nawet gdy mamy do czynienia z nietrywialnymi danymi.

Uzupełnianie argumentów oparte na klasach (od wersji PowerShell 7.2)

Od wersji PowerShell 7.2 dodano funkcję umożliwiającą definiowanie wielokrotnego użytku wypełniaczy opartych na klasach , co znacznie ułatwia tworzenie parametryzowalnych i generycznych wypełniaczy.

Pomysł polega na dziedziczeniu po ArgumentCompleterAttribute i implementacji interfejsu IArgumentCompleterFactory . Klasa pochodna może mieć konfigurowalne właściwości (np. zakresy liczbowe, głębokość katalogów, daty, gałęzie Gita itp.), które są używane do zbudowania właściwego modułu uzupełniania.

Kod klasy (przykład): using namespace System.Collections<br>using namespace System.Collections.Generic<br>using namespace System.Management.Automation<br>using namespace System.Management.Automation.Language<br><br>class NumberCompleter : IArgumentCompleter {<br> $From<br> $To<br> $Step<br><br> NumberCompleter( $from, $to, $step) {<br> if ($from -gt $to) {<br> throw ::new("from")<br> }<br> $this.From = $from<br> $this.To = $to<br> $this.Step = $step -lt 1 ? 1 : $step<br> }<br><br> ] CompleteArgument(<br> $CommandName,<br> $parameterName,<br> $wordToComplete,<br> $commandAst,<br;> $fakeBoundParameters<br> ) {<br> $resultList = ]::new()<br> $Local:to = $this.To<br> $Local:step = $this.Step<br><br> for ($i = $this.From; $i -lt $to; $i += $step) {<br> $resultList.Add(::new($i.ToString()))<br> }<br><br> return $resultList<br> }<br>}<br><br>class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {<br> $From<br> $To<br> $Step<br><br> NumberCompletionsAttribute( $from, $to, $step) {<br> $this.From = $from<br> $this.To = $to<br> $this.Step = $step<br> }<br><br> Create() {<br> return ::new($this.From, $this.To, $this.Step)<br> }<br>}

Użycie atrybutu: function Add {<br> param(<br> <br> $X,<br;<br> <br> $Y<br> )<br> $X + $Y<br>}

Podczas pisania funkcji i rozpoczynania uzupełniania parametrów, klawisz Tab zasugeruje wartości liczbowe od 0 do 100 w krokach co 5 , bez konieczności powtarzania logiki autouzupełniania w każdej funkcji. Tę samą technikę można zastosować do ścieżek katalogów, obliczonych dat, commitów Gita dla danej gałęzi i ogólnie w każdym scenariuszu, w którym potrzebne są wielokrotnego użytku i konfigurowalne wypełniacze.

Automatyczne uzupełnianie w stylu Linuksa w programie PowerShell przy użyciu PSReadLine i Register-ArgumentCompleter

Jeśli pochodzisz ze świata GNU/Linux, prawdopodobnie jesteś przyzwyczajony do zaawansowanego autouzupełniania oferowanego przez powłoki takie jak zsh , z interaktywnym menu i bardzo inteligentnymi sugestiami. PowerShell, choć inny, pozwala również zbliżyć się do tego doświadczenia, łącząc PSReadLine i Register-ArgumentCompleter.

Z jednej strony z Set-PSReadlineKeyHandler Możesz zmienić sposób działania klawisza Tab. Bardzo przydatną sztuczką jest skonfigurowanie klawisza Tab tak, aby wyświetlał nawigowalne menu opcji zamiast po prostu ukończyć następny element:

Polecenie PSReadLine: Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete

Jeśli wstawisz tę linię do swojego plik profilu z programu PowerShell, na przykład edytując go za pomocą notepad $profileDzięki temu każda nowa sesja programu PowerShell będzie rozpoczynać się z tą funkcją Tab, co znacznie ułatwi przeglądanie dostępnych opcji. Może się jednak zdarzyć, że będziesz musiał... dostosuj zasady wykonywania w systemie, aby profil działał bez nadmiernych ograniczeń.

Z drugiej strony połączenie tej funkcji PSReadLine z wypełniaczami zarejestrowanymi przez Register-ArgumentCompleter (na przykład dla winget, dotnet lub własnych modułów), można uzyskać niemalże płynność funkcji autouzupełniania LinuxWiele zespołów udostępnia w swoich repozytoriach kompletne bloki skryptów, co pozwala całej organizacji na posiadanie spójne i wysoce produktywne środowisko wiersza poleceń.