Powershell spikri kirjutamine

Powershelli spikri kasutamisest sai mõnda aega tagasi kirjutatud. Nüüd vaataks, kuidas selle spikri sisu loomise ja muutmisega on.

Powershelli spikri süsteem kasutab info hoidmiseks XML-vormingut, mis on isegi dokumenteeritud. Ent sellega ümberkäimine on suhteliselt ebamugav ning see peab olema samas masinas, kus spikrit lugeda tahetakse. Seetõttu on selle muutmine natuke ebamugav.

Teiseks on skriptidele spikri kirjutamisel võimalik kasutada XML-vormingu asemel hoopis skripti sisse käivat kommentaaripõhist spikrit. Muidugi saab kommentaaripõhisest spikrist alati viidata ka välisele (XML-põhisele) spikrile.

Kolmandaks on spikris niinimetatud about-teemad, mida hoitakse tavaliste tekstifailide kujul.

Powershell 3.0 lisas spikrisüsteemile veel Online-spikri ja spikri uuendamise toe. Aga see teeb elu veelgi ebamugavamaks, kuna nüüd tuleb hallata nelja erinevat vormingut:

  1. tekstifailid
  2. XML-vormingus spikker
  3. veebisait online-spikriga
  4. veebisait, kust saab uuendatud spikrit alla laadida (ja sellega koos alla laetava spikri fail).

Õnneks on selle peale mõeldud. Powershelli moodul platyPS pakub võimalust tuua kõik ülalmainitud spikri allikad kokku ühtsesse süsteemi ning muuta spikri sisu ühest allikast kättesaadavaks kõigis ülaltoodud vormingutes.

platyPS pakub võimalust hoida spikri sisu Markdown-vormingus, mis on inimloetav ja lihtsasti muudetav mistahes tekstiredaktoriga. Paljud veebisaidid oskavad Markdown-vormingut automaatselt näidata HTMLi kujul. Seega on Online-spikker sellega valmis.

Järgmine samm on XML-vorming. platyPS sisaldab käsku
New-ExternalHelp, millega saab Markdown-spikri teemad teisendada XML-vormingusse. Ja ühtlasi pakkida ka uuendatava spikri failiks, mida saab veebisaiti üles laadida.

Kui Sa leiad, et Markdown on koodist eraldi ning jääb seetõttu tähelepanuta, siis oskab platyPS teisendada kommentaaripõhise spikri Markdown-vormingusse. Nii et siis tuleb lihtsalt aeg-ajalt värskendada oma Markdown spikri teemasid ja need seejärel kättesaadavaks teha. Kommentaarid ise on alati koodiga koos ja seega kohe kättesaadavad koodi kasutajale.

Powershell 6 plaanib kogu spikrisüsteemi viia XML-vormingult üle Markdown vormingusse. Juba praegu on Powershell 6.1-s lisatud käsk ConvertFrom-Markdown, mis loeb Markdown-vormingut ja muudab selle Powershelli käsurealt kasutatavaks.

Suuremates projektides tekib vajadus hoida dokumentatsioon (ja spikker) koodist lahus, kuna dokumenteerimisega võivad tegeleda teised inimesed. Ka sellisel juhul on Markdown-vorming hea. Ilus näide selle kohta on Microsofti dokumentatsiooni sait docs.microsoft.com. Kogu selle sisu on tegelikult Github’is üleval ja kaastööks kättesaadav.

Advertisements

PowerShell Help

Kui tekib sageli vajadus konsulteerida PowerShelli spikriga, siis muutub ruttu tüütavaks spikri väljakutsumine käsurealt.  Kui seda pidevalt vaja on, siis tuleks lahti hoida kahte konsooliakent: ühe peal tööd teha ja teise peal spikrit lugeda.

Teine võimalus oleks kasutada Powershell ISE abi.  Piisab sellest, kui aknas viia tekstikursor käsu peale ja vajutada klahvi <F1>, ning kohe avaneb spikker eraldi aknas.  Tegelikult saab sama teha ka käsurealt:

#Requires -Version 3

Get-Help Get-Help -ShowWindow

Käsk Get-Help oskab avada ka veebipõhist spikrit.  Selleks pole vaja muud, kui küsida abi järgmisel viisil:

#Requires -Version 2

Get-Help Get-Help -Online

Selle peale avaneb veebilehitseja spikri veebiversiooniga tingimusel, et spikker sisaldab sektsioonis Related Links esimese viitena veebiaadressi või on lisatud eraldi.  Seda kontrollib järgnev käsk:

(Get-Help Get-Help).relatedLinks.navigationLink

Või kui spikker puudub, siis võib veebilink olla lisatud käsu enda külge.  Ning loomulikult saab sedasi veebilinki lisada ka oma skriptidesse:

#Requires -Version 3

function New-Calendar {
[CmdletBinding(SupportsShouldProcess=$true,
HelpURI="http://go.microsoft.com/fwlink/?LinkID=01122")]
...
}

(Get-Command New-Calendar).HelpUri
Get-Help New-Calendar -Online

Täpsemalt saab lugeda dokumentatsioonist.

Sellisel viisil ei saa avada spikri about-teemasid.  Põhjus on selles, et about-teemad on tavalised tekstifailid ja seal ei ole eraldi veebiaadressi ega ka sektsioone, millest veebilinki otsida.

Powershell 3-l on veel ka sisse ehitatud käsk Show-Command, aga see võimaldab juba graafilises liideses käsurea parameetreid sisestada/kasutada.  Samas visualiseerib see käsurea parameetreid ning võimaldab käsu võimalustega rohkem tutvuda.

Powershell 3 ja värskema puhul tasub veel ka seda teada, et neil on vaikimisi spikker kaasa panemata jäänud.  Seda peamiselt selle pärast, et spikri võib käsuga Update-Help õigel hetkel alla tõmmata/uuendada.  Ja siis saab juba täiesti värsket spikrit kasutada.  Tuleb vaid mäletada, et suurem osa Windowsiga kaasa tulnud moodulitest on Windowsi kaustas ja seetõttu peab Update-Help käima süsteemiülema õigustes.

Ning juhul, kui Sa ikka veel kasutada Powershell 2.0 versiooni, siis tuleb leppida  PowerShell (2.0) .CHM spikriga või kasutada PowerShelli kommuuni poolt kirjutatud rakendusi:

  • PowerShell SE – mitte ainult sprikri näitaja. Autor ise ütleb, et: PowerShell ISE Editing Control + PowerShell Help Reader + Cool stuff = PowerShell SE. Õnnetuseks otsustas arendaja parematele jahimaadele minna.
  • Windows PowerShell Cmdlet Help Viewer – WPF rakendus, mis loeb Powershelli spikri .XML faile ja näitab neid loetavas vormingus.
  • Sapien Powershell Help Viewer – tasuta utiliit, mis loeb/interpreteerib Powershelli .XML spikrifaile ja about-dokumente.