Comments en helpfile

Het is niet een goede gewoonte, maar een vereiste om je script van het juiste commentaar te voorzien. Zo weten jijzelf en ook anderen hoe jouw script in elkaar steekt. Uiteraard weet je dat zelf op het moment dat je het script aan het schrijven bent, maar geheid dat je het over enkele weken of maanden bent vergeten. Dan ben je dankbaar voor het feit dat je ooit de tijd genomen hebt om dit op een degelijke manier te doen.

Een commentaarregel laat je in PowerShell voorafgaan door een #, dus:

# De variabele $Username wordt gevuld met de huidige gebruikersnaam
$Username = Get-Content Env: USERNAME

Als je meer commentaarregels onder elkaar in een blok wilt zetten, kan dat ook. Gebruik hiervoor het zogenaamde comment-block. Deze ziet er als volgt uit:

<#

Hier staat commentaar regel 1

en hier staat regel 2

en dit commentaarblok wordt afgesloten met regel 3

#>

Het mooie van PowerShell is dat je jouw toegevoegde commentaar meteen kunt gebruiken als tekst voor de helpfile van het eigen script. Dit noemen we comment-based help. Deze comments komen dus in het comment-block (tussen <# en #> te staan). Een aantal voorbeelden die je zou kunnen gebruiken:

.SYNOPSIS een korte beschrijving van het script.

.DESCRIPTION een gedetailleerdere beschrijving van het script. .PARAMETER <Parameter-Name> Als je parameters gebruikt, dan be noem je ze hier per stuk, daarbij geef je ook de default-waarde

aan.

.EXAMPLE Voorbeelden die je wilt geven bij gebruik van het script: deze voorbeelden hoef je niet te nummeren.

.NOTES eventueel aanvullende informatie over het script of de func tie.

.LINK eventueel een link waar bijvoorbeeld meer info te vinden is.

Let op! De comment-based help moet aan het begin van het script staan.

Als je een en ander op die manier netjes documenteert (van comments voorziet) en je vraagt vervolgens de helpfile van het eigen script op, dan krijg je deze ook keurig te zien.

Zie onderstaand voorbeeld: Get-Help .\loginscript.ps1 -full (daar mee krijg je alle info te zien!).

<afbeelding van script in bijlage A>


TIP Voor meer informatie over comment-based help geef je binnen PowerShell het commando:

Get-Help About_Comment_Based_Help


Opdracht 1

Maak een passende comment based helpfile voor je login script uit opdracht 1 van het onder deel "Een logfile maken"