2.5.12

Ha készítünk függvényeket és szkripteket, akkor nem árt magyarázatokkal ellátni a „forráskódot”, hogy ha a függvényünket, szkriptünket akár mi, akár mások is megérthessék, ha használni, megérteni vagy továbbfejleszteni szeretnék. Ha pedig nem PowerShellhez értők kezébe adjuk, akkor őket is jó lenne ellátni valamilyen útmutatással a használatot illetően. Nem biztos, hogy ők értenek annyira a forráskód elemzéséhez, hogy abból mindent megértsenek, viszont nagy valószínűséggel rávehetők, hogy a PowerShell beépített súgóját kezelő Get-Help cmdletet használják. A két szempontot a PowerShell fejlesztői egyesítették, hogy ne kelljen a kettővel nekünk külön-külön, más helyen és más technológiával bajlódnunk. A megoldás az un. „comment based help”, azaz a megjegyzések formájában beágyazott súgó.

Ez azt jelenti, hogy speciális megjegyzéseket helyezhetünk el a függvényünkbe vagy szkriptünkbe, amelyeket a Get-Help ugyanúgy jelenít meg, mint a „gyári” súgótémákat. Nézzünk erre egy példát a Pithagoras függvény segítségével:

function Pithagoras

{

.SYNOPSIS

Kiszámolja a derégszögű háromszög átfogóját a befogókból.

.DESCRIPTION

Ez a függvény Pithagoras a^2+b^2=c^2 tétele alapján kiszámolja a

derékszögű háromszög átfogóját a befogókból.

.NOTES

Version: 0.1.0

Version history:

0.1.0 26-Oct-2011 - Tibor Soos <soostibor@citromail.hu>

First version

.INPUTS

Nincs, csővezetéken nem fogad paramétereket.

.OUTPUTS

System.Double. Kimenet a c átfogó hossza.

.EXAMPLE

C:\PS> Pithagoras 3 4

.EXAMPLE

C:\PS> Pithagoras 4

5,65685424949238

Ebben a példában az egyenlő oldalú derékszögű háromszög átfogóját

számolta ki.

.LINK

További információ Pithagorasz tételéről:

http://hu.wikipedia.org/wiki/Pitagorasz-t%C3%A9tel

.LINK

about_Arithmetic_Operators

param

(

[Parameter(

Mandatory = $true,

Position = 0,

HelpMessage = "Ez kötelezően kitöltendő"

)]

[double]

# A derékszögű háromszög egyik befogója

$a,

[Parameter(

Mandatory = $false,

Position = 1

)]

[double]

# A derékszögű háromszög másik befogója

$b = $a

)

[math]::Sqrt($a*$a+$b*$b)

}

Látható, hogy a függvény definíciójának elejére egy speciális megjegyzésblokk (<#...#>) került. Ezen belül ponttal kezdődő címkék a súgón belüli részek kulcsszavai, utánuk meg az adott részhez tartozó leírás van. Vannak olyan részek, amelyek csak egyszer fordulhatnak elő, mint például a .SYNOPSIS vagy a .DESCRIPTION, de vannak olyanok is, amelyekből több is lehet, mint például az .EXAMPLE.

Nézzük meg, hogy mit ad a függvény definiálása után a teljes változatú Get-Help:

[55] PS C:\> get-help Pithagoras -full

NAME

Pithagoras

SYNOPSIS

Kiszámolja a derégszögű háromszög átfogóját a befogókból.

SYNTAX

Pithagoras [-a] <Double> [[-b] <Double>] [<CommonParameters>]

DESCRIPTION

Ez a függvény Pithagoras a^2+b^2=c^2 tétele alapján kiszámolja a

derékszögű háromszög átfogóját a befogókból.

PARAMETERS

-a <Double>

A derékszögű háromszög egyik befogója

Required? true

Position? 1

Default value

Accept pipeline input? false

Accept wildcard characters?

-b <Double>

A derékszögű háromszög másik befogója

Required? false

Position? 2

Default value

Accept pipeline input? false

Accept wildcard characters?

This cmdlet supports the common parameters: Verbose, Debug,

ErrorAction, ErrorVariable, WarningAction, WarningVariable,

OutBuffer and OutVariable. For more information, type,

"get-help about_commonparameters".

INPUTS

Nincs, csővezetéken nem fogad paramétereket.

OUTPUTS

System.Double. Kimenet a c átfogó hossza.

-------------------------- EXAMPLE 1 --------------------------

C:\PS>Pithagoras 3 4

-------------------------- EXAMPLE 2 --------------------------

C:\PS>Pithagoras 4

5,65685424949238

Ebben a példában az egyenlő oldalú derékszögű háromszög átfogóját

számolta ki.

RELATED LINKS

További információ Pithagorasz tételéről:

http://hu.wikipedia.org/wiki/Pitagorasz-t%C3%A9tel

about_Arithmetic_Operators

Látszik, hogy vannak olyan részek, amelyeket nem én definiáltam, hanem a PowerShell automatikusan rakja össze a függvénydefiníció alapján. Ilyenek például a NAME, SYNTAX, PARAMETERS, REMARKS. Apropó PARAMETERS! A függvénydefinícióban látható, hogy a paraméterdefiníciós részbe elhelyezett megjegyzéseket is kiemeli a Get-Help, és ennél a szekciónál megjeleníti.

Erre a súgót tartalmazó megjegyzésblokkra van néhány szigorú szabály és alternatív lehetőség. Ez a blokk függvények esetében három különböző helyen lehet, de egy függvény esetében el kell döntenünk, hogy melyiket választjuk. Lehet a súgóblokk a függvény definíciós részének elején, közvetlenül a function kulcsszót követő sorban, lehet a függvénydefiníciós rész végén, a lezáró kapcsos zárójel előtt, vagy a függvénydefiníció előtt, azaz a function kulcsszót közvetlenül megelőző részben. Szerintem a legjobb az a hely, amit én használtam, azaz a függvény eleje, de végül is ez ízlés dolga.

Súgót lehet készíteni XML formátumban is, erre példát találhatunk a „gyári” súgótémák között a PowerShell telepítési könyvtárában. Ezt itt nem ismertetem, ezt hagyjuk meg a profi fejlesztőknek.

A szkripteket ugyanilyen módon láthatjuk el súgóval. Tegyük fel, hogy az előbb látott Pithagoras függvényt sok más matematikával kapcsolatos függvénnyel együtt egy szkriptfájlba mentjük el matek.ps1 néven, és ennek is generálok egy megjegyzés-alapú súgót:

Itt is lehet a fájl elejére vagy végére tenni a súgóblokkot. Az elejénél vigyázni kell, mert ha a szkriptem egy függvénydefinícióval kezdődik, mint a fenti példában is, akkor a PowerShell értelmezője ezt a blokkot a függvényhez sorolja. Ezt meg tudjuk akadályozni, ha a súgóblokk és a function kulcsszó sora közé legalább két üres sort teszünk.

[56] PS C:\> Get-Help .\munka\matek.ps1

NAME

C:\munka\matek.ps1

SYNOPSIS

Ebben a szkriptben a matematikai függvényeim vannak.

SYNTAX

C:\munka\matek.ps1 [<CommonParameters>]

DESCRIPTION

Függvények:

Pithagoras

Súgó készítése