Kako uporabljati ArgumentCompleter in Register-ArgumentCompleter v PowerShellu

V naslednjih vrsticah bomo mirno in z jasnimi primeri videli, kako uporabljati Register-ArgumentCompleter, atributi ArgumentCompletion, ArgumentCompletions in ValidateSet ter razredi po meri za doseganje zelo napredne izkušnje samodokončanja v PowerShellu. Videli boste tako preproste primere kot veliko bolj dovršene scenarije, vključno s tem, kako ga integrirati v svoj Profil PowerShella kako ga vedno ohranjati aktivnega in kako ga uporabljati tudi z izvornimi ukazi, kot so dotnet ali CLI-jev tretjih oseb.

Kaj je Register-ArgumentCompleter in kateri problem rešuje?

Cmdlet Register-ArgumentCompleter služi za registrirajte dopolnjevalec argumentov po meriZ drugimi besedami, poveste PowerShellu, kaj naj predlaga, ko uporabnik pritisne tipko Tab pri vnašanju vrednosti parametra ali izvornega ukaza.

Ta dokončevalec deluje naprej čas izvedbeTorej lahko predloge izračunate dinamično: poiščite ukaze »cmdlets«, kot je Get-TimeZonefiltriranje storitev z Get-Service, pokličite CLI kot dotnet completeBranje REST API-ja, preverjanje datotečnega sistema itd. se izvaja prek ... Skriptni blok ki vrne možne vrednosti samodokončanja.

Pomembna podrobnost je, kako se parameter obnaša Ime ukazače ga uporabite brez navedbe Ime parametra ni MaterniPowerShell obravnava klic, kot da bi ga dodali -DomačinTo pomeni, da dopolnjevalec ne bo deloval s parametri ukaza »cmdlet« PowerShell, temveč le kot dopolnjevalec za izvorne ukaze. Če je torej vaš cilj dokončati parametre za ukaz »cmdlet« ali funkcijo PowerShell, morate vedno navedite ime parametra.

Osnovna sintaksa funkcije Register-ArgumentCompleter

Nabor parametrov za izvorne ukaze (NativeSet)

Za registracijo dopolnjevalnika argumentov za izvorni ukaz se uporabi naslednja sintaksa, kjer je ključ v modifikatorju -Domačin:

Tipična sintaksa: Register-ArgumentCompleter -CommandName <String[]> -ScriptBlock <ScriptBlock> -Native

V tem primeru Ime ukaza je obveznoker mora PowerShell vedeti, s katerim izvornim ukazom naj poveže dopolnjevalec. Skriptni blok Prejel bo drugačen nabor parametrov kot dopolnjevalniki ukazov PowerShell, kot bomo videli kasneje, in bo usmerjen v interpretacijo celotne vrstice in položaja kazalca.

Nabor parametrov ukaza »cmdlet« PowerShell (PowerShellSet)

Če želite dodati samodejno dokončanje enemu ali več parametrom ukazov »cmdlet« ali funkcij PowerShell, je najpogostejša sintaksa:

Tipična sintaksa: Register-ArgumentCompleter -ParameterName <String> -ScriptBlock <ScriptBlock> >]

tukaj ImeParametra je obvezno in določa, na kateri parameter se bo dokončanje uporabilo. Parameter ImeUkaza je neobveznoDokončevalnik lahko omejite na enega ali več določenih ukazov, če pa ga izpustite, bo PowerShell registriral ta dokončevalnik za to ime parametra v vseh ukazih, ki ga vsebujejo.

Ključni parametri Register-ArgumentCompleter

Parameter -CommandName

Parameter -ImeUkaza Označuje, za kateri ukaz ali ukaze bo izvajalec registriran. Sprejme enega. niz nizovZato lahko isti ScriptBlock hkrati povežete z več ukazi »cmdlet« ali izvornimi orodji.

Pri uporabi v naboru parametrov NativeSetJe obveznoker izvornih dopolnjevalcev ni mogoče generično registrirati brez kazala na določeno binarno datoteko ali ukaz. V naboru PowerShellSet To je neobvezno, vendar, kot smo že omenili, če ga uporabljate brez Ime parametra ni MaterniPowerShell bo interpretiral, da ustvarjate izvorni dopolnjevalec.

Parameter -Izvorno

Modifikator -Domačin pove PowerShellu, da je treba dopolnjevalnik uporabiti za izvorni ukaziTo pomeni zunanje izvedljive datoteke, kjer PowerShell ne nadzoruje niti ne more dopolniti imen parametrov. Poglejmo si dotnet, winget, aws ali kateri koli drug CLI, ki temelji na .NET-u, Python ali podobno.

V tem načinu ScriptBlock prejme manj parametrov in za drugačen namen: napisano besedilo, AST ukaza in položaj kurzorjaOd tam običajno script Za vračanje predlogov pokliče sam CLI, kot se to zgodi z dotnet complete.

Parameter -ParameterName

Parameter -ImeParametra Določa ime parametra, za katerega se bo uporabilo dopolnjevanje argumentov. Obstaja ena pomembna omejitev: vrsta tega parametra. Ne more biti seznamNa primer, če parameter uporablja tip, kot je Barva ospredja de Write-HostZa dokončanje ne morete uporabiti Register-ArgumentCompleter.

Pri registraciji dokončevalcev za ukaze »cmdlet« ali funkcije PowerShell je zelo priporočljivo, da vedno uporabi ime parametraČe pozabite in uporabite samo CommandName, boste nenamerno registrirali izvorni dopolnjevalec in ne boste videli predlogov za parameter, ki vas zanima.

Parameter -ScriptBlock

Srce vsakega, ki dopolnjuje Skriptni blokTa skriptni blok definira logiko, ki generira vrednosti, ki jih uporabnik predlaga, ko pritisne TabNajpomembneje je, da mora ScriptBlock vrnite elemente skozi cevovodNa primer, z ForEach-Object o Where-Object, namesto da bi vrnil eno samo tabelo, ker če se vrne necevovodna tabela, jo bo PowerShell interpretiral kot ena sama vrednost samodokončanja.

Poleg tega lahko ScriptBlock neposredno vrne nize ali objekti tipa System.Management.Automation.CompletionResultTo ponuja veliko večjo prilagodljivost, saj vam omogoča, da določite besedilo, ki se izpolni, besedilo, ki se prikaže na seznamu, vrsto rezultata in opis ali opisno polje.

Parametri ScriptBlock za dokončevalnike PowerShell

V običajnih (ne-izvornih) polnilih bi moral ScriptBlock sprejemati pet parametrov v tem vrstnem redu, ne glede na njihova imena:

• $commandName: niz z imenom ukaza, za katerega se izračuna dokončanje.
• $parameterName: niz z imenom parametra, ki se dopolnjuje.
• $wordToCompleteniz, ki vsebuje besedilo, ki ga je uporabnik vnesel tik pred pritiskom na Tab.
• $commandAstObjekt CommandAst, ki predstavlja abstraktno sintaksno drevo trenutne vrstice.
• $fakeBoundParameters: vrsta slovarja IDoctor ki posnema vsebino $PSBoundParameters v trenutku pritiska Tab.

Parameter $wordToComplete Pogosto se uporablja za filtriranje vrednosti z operatorji, kot so -liketako da so predlagani samo elementi, ki se začnejo s tistim, kar je uporabnik že vnesel. Medtem, $fakeBoundParameters Omogoča vam ustvarjanje polnil, ki so odvisna od drugih parametrov, kot bomo videli na primerih sadja in zelenjave.

Parametri ScriptBlock za izvorna polnila

Kdaj se uporablja -DomačinScriptBlock prejme tri parametre, prav tako glede na položaj:

• $wordToComplete (položaj 0): besedilo, ki ga je uporabnik vnesel pred tipko Tab.
• $commandAst (položaj 1): sintaksno drevo celotnega ukaza, ne le trenutnega argumenta.
• $cursorPosition (položaj 2): indeks položaja kurzorja v vrstici.

Ta oblika se zelo dobro ujema z vmesniki CLI, ki že imajo svoj sistem samodokončanja. Tipičen primer je dotnet complete, ki prejme položaj vrstice in kazalca ter vrne predloge navadnega besedila, ki se nato pretvorijo v RezultatDokončanja.

Praktični primeri z Register-ArgumentCompleter

Primer 1: Dinamično polnjenje časovnih pasov

Predstavljajte si, da želite uporabo ukaza »cmdlet« čim bolj poenostaviti. Set-TimeZone kar uporabniku omogoča dokončanje parametra Id s tipko Tab. Skriptni blok, ki pridobi vse časovne pasove, lahko ustvarite z Get-TimeZone -ListAvailableFiltriraj po tem, kar je uporabnik vnesel, in vsako vrednost v primeru presledkov zapiši v narekovaje:

Primer skripta 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

S tem, ko pišeš Set-TimeZone -Id in začnite tipkati, ko pritisnete Tab ga boste imeli Seznam filtriranih ID-jev časovnih pasov Glede na to, kar ste napisali. Enojni narekovaji so dodani, da se izognemo težavam z identifikatorji, ki vsebujejo presledke.

Primer 2: Obogateni predlogi s CompletionResult

V drugem scenariju želite, da pri uporabi Stop-Service -Name pojavljajo se samo storitve, ki so v tekuin želite prikazati dodatne informacije na seznamu predlogov, ko uporabnik pritisne Ctrl+Vesolje.

Primer skripta 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

Bodite pozorni na ta polja: V vsakem objektu CompletionResult lahko za bolj dodelano izkušnjo nadzorujete ta ključna polja:

• dokončanjeBesedilo: besedilo, ki se dejansko vstavi v ukaz, ko izberete predlog.
• seznamItemBesedilo: besedilo, prikazano na seznamu predlogov; se lahko razlikuje od vstavljenega niza.
• Vrsta rezultata: vrsta rezultata (na primer, ParameterValue).
• Namig: opis, ki se prikaže, ko izberete element na dokončanem seznamu, še posebej uporaben z Ctrl+Vesolje.

Primer 3: Izvorni dopolnjevalec za dotnet CLI

Za razširitev samodokončanja lahko uporabite tudi Register-ArgumentCompleter. domača orodjaKlasični primer je dotnet, ki vključuje podukaz dotnet complete za vrnitev dokončanih elementov na podlagi trenutne vrstice.

Primer izvorne skripte: $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

V tem primeru sam ukaz dotnet complete To je tisti, ki izvede izračun predlogov. ScriptBlock preprosto pretvori izhod v objekte CompletionResult. Na ta način dosežete Zelo brezhibna integracija med PowerShellom in zunanjim CLI-jem, z zavihki, ki poznajo vse izvorne možnosti dotnet.

Drugi načini implementacije dopolnjevalcev argumentov

ValidateSet: fiksne vrednosti s strogo validacijo

Atribut ValidateSet Ponuja preprost način za omejitev parametra ali spremenljivke na zaprt nabor vrednosti in hkrati omogoča dokončanje s tabulatorjem, ne da bi bilo treba napisati prilagojen ScriptBlock.

Predstavljajte si parameter sadje ki sprejema samo "jabolko", "banano" ali "hruško". Lahko bi ga definirali takole:

Primer definicije: param (<br> <br> <br> ]$Fruit<br>)

Če uporabnik vnese vrednost, ki ni v naboru, bo PowerShell vrgel napako napaka pri preverjanjuEnako velja za trenutne spremenljivke, ne le za parametre, na primer:

Deklaracija spremenljivke: <br>$Flavor = 'Strawberry'

Vsakič, ko je nekaj dodeljeno $FlavorSkript bo preveril, ali vrednost pripada množici. Če kadar koli v skriptu to storite:

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

PowerShell bo vrnil napako tipa Napaka metapodatkov, kar pomeni, da spremenljivka ne bi bila več veljavna, če bi se uporabila ta vrednost, kar pomaga ohranjati stroge pogodbe v vaših skriptih.

Dinamični ValidateSet z razredi

Poleg statičnih množic PowerShell omogoča generiranje vrednosti iz Dinamično preverjanje veljavnosti z uporabo razredov ki implementirajo vmesnik System.Management.Automation.IValidateSetValuesGeneratorV tem modelu razred razkrije metodo GetValidValues() ki vrne možne možnosti.

Tipičen primer je razred Zvočna imena, ki pregleda več sistemskih map za zvočne datoteke in vrne njihova osnovna imena kot veljavne vrednosti:

Primer razreda (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>}

Kasneje razred implementirate kot Dinamični nabor za preverjanje veljavnosti v parametru ali spremenljivki:

Uporaba dinamičnega ValidateSet: param (<br> )]<br> $Sound<br>)

Tako dosežete popoln videz z zavihki, ki odražajo dejansko stanje datotečnega sistema vsakič, ko se skript izvede.

Dopolnjevanje argumentov: predlogi brez preverjanja vrednosti

Atribut Dopolnjevanje argumentov Omogoča vam, da parametru dodate seznam predlaganih vrednosti, vendar za razliko od ValidateSet, Stroga validacija se ne izvajaTo pomeni, da lahko uporabnik izbere enega od predlogov ali napiše karkoli drugega, tudi če ni na seznamu.

Njegova sintaksa je zelo preprosta. Funkcijo lahko na primer definirate z enim parametrom. tip kar predlaga "Sadje" in "Zelenjava" ter parametre sadje y Zelenjava s seznami možnih vrednosti:

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

Ta lastnost je popolna, kadar želite uporabnika vodite s primeri običajnih vrednosti, vendar mu zaradi poslovnih zahtev ali združljivosti s posebnimi primeri ne želite preprečiti vnosa drugih, drugačnih.

ArgumentCompleter: dopolnjevalniki na ravni atributov parametrov

Atribut Dopolnjevalec argumentov Uporablja se za pripenjanje ScriptBlock parametru z enakim podpisom kot dopolnjevalci, registrirani z Register-ArgumentCompletervendar brez potrebe po klicanju tega ukaza »cmdlet«. To je eleganten način za enkapsulacijo kompleksna logika samodokončanja neposredno v definiciji funkcije.

Osnovni primer: Primer uporabe bi lahko bil:

Primer atributa: function MyArgumentCompleter {<br> param (<br> <br> <br> $ParamName<br> )<br>}

Tako kot pri Register-ArgumentCompleter mora ScriptBlock vrniti vrednosti prek cevovoda in lahko izkoristi oboje. $wordToComplete kot $fakeBoundParameters ali celo analizirati AST upoštevati celoten kontekst ukaza.

Napreden primer funkcije ArgumentCompleter, ki je odvisna od drugega parametra

Zelo uporaben vzorec vključuje ustvarjanje celotnih funkcij, ki so odvisne od vrednosti drugih parametrov. Predstavljajte si funkcijo s parametrom tip ki je lahko "Sadje" ali "Zelenjava" in parameter Vrednost katerih nabor predlogov se spreminja glede na izbrano vrsto.

Izvedba motorja: 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>}

Poraba polnila: function Test-ArgumentCompleter {<br> <br> param (<br> <br> <br> $Type,<br;<br> <br> <br> $Value<br> )<br>}

V tem primeru, če napišete npr. Test-ArgumentCompleter -Type Fruits -Value A in pritisnete Tab, zahvaljujoč uporabi -Všeč in iz slovarja $fakeBoundParametersPolnilo bo vrnilo samo vrednosti sadja, ki se začnejo z "A", torej AppleTo je zelo močna tehnika za gradnjo uporabniku prijazni vmesniki ukazne vrstice tudi ko se soočimo z netrivialnimi podatki.

Dopolnjevalniki argumentov na osnovi razredov (začenši s PowerShellom 7.2)

Od različice PowerShell 7.2 naprej je bila dodana funkcija, ki omogoča definiranje polnila za večkratno uporabo, ki temeljijo na razreduTo močno olajša ustvarjanje parametriziranih in generičnih polnil.

Ideja je izhajati iz Atribut Dokončevalnika Argumenta in implementirajte vmesnik TovarnaDokončevalnikaArgumentovIzpeljani razred ima lahko nastavljive lastnosti (npr. številske obsege, globino imenika, datume, veje Git itd.), ki se uporabljajo za izgradnjo dejanskega dopolnjevalnika.

Koda razreda (primer): 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>}

Uporaba atributov: function Add {<br> param(<br> <br> $X,<br;<br> <br> $Y<br> )<br> $X + $Y<br>}

Ko pišete funkcijo in začnete vnašati parametre, vam bo Tab predlagal Številske vrednosti med 0 in 100 v korakih po 5brez ponavljanja logike samodokončanja v vsaki funkciji. Isto tehniko je mogoče uporabiti za poti imenikov, izračunane datume, Gitove potrditve za dano vejo in na splošno za kateri koli scenarij, kjer potrebujete polnila za večkratno uporabo in prilagodljiva.

Samodokončanje v slogu Linuxa v PowerShellu z uporabo PSReadLine in Register-ArgumentCompleter

Če prihajate iz sveta GNU/Linuxa, ste verjetno vajeni napredne izkušnje samodokončanja, ki jo ponujajo lupine, kot je zshz interaktivnimi meniji in zelo inteligentnimi predlogi. PowerShell, čeprav drugačen, vam omogoča, da se precej približate tej izkušnji z združevanjem PSReadLine in Register-ArgumentCompleter.

Po eni strani, z Set-PSReadlineKeyHandler Obnašanje tipke Tab lahko spremenite. Zelo priročen trik je, da tipko Tab konfigurirate tako, da prikaže navigacijski meni z možnostmi namesto da preprosto dokončate naslednji element:

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

Če vstavite to vrstico v svoj datoteka profila iz PowerShella, na primer z urejanjem z notepad $profileTo bo zagotovilo, da se bo vsaka nova seja PowerShell začela s tem vedenjem Tab, zaradi česar bo raziskovanje razpoložljivih možnosti veliko bolj prijetno. Vendar boste morda morali ... prilagodite politiko izvajanja v vašem sistemu, tako da profil deluje brez pretiranih omejitev.

Po drugi strani pa kombinacija te funkcije PSReadLine s polnili, registriranimi prek Dokončevalnik registra argumentov (na primer za winget, dotnet ali lastne module), se lahko precej približate pretočnosti samodokončanja LinuxŠtevilne ekipe si v svojih repozitorijih delijo dokončnejše ScriptBlocke, kar omogoča celotni organizaciji, da ima koherentno in visoko produktivno okolje ukazne vrstice.