Wanneer een nieuwkomer in PowerShell begint met het schrijven van scripts, richten ze zich meestal op de code. Immers, de code is wat dingen laat gebeuren! Uitvoerbare code is natuurlijk belangrijk, maar wat gebeurt er als je zoveel code schrijft dat je vergeet wat het doet? Dan kan PowerShell-commentaar van pas komen.

Als je in een team zit, begrijpen ze dan de code die je schrijft? PowerShell-commentaar kan helpen.

Het schrijven van beschrijvend en informatief PowerShell-commentaar in scripts helpt ons mensen om de bedoeling van de code te begrijpen, het resultaat, en beschrijft misschien randgevallen die ooit zijn opgetreden.

In dit artikel leert u meer over de verschillende soorten commentaar in PowerShell, welke u kunt gebruiken en hoe u ze effectief in uw scripts kunt gebruiken.

Heb je ooit code geschreven en moest je die weken of maanden later nog eens bekijken? Waarschijnlijk. Begreep u het later ook zo goed? Misschien niet. Had u maar nuttig commentaar in uw code achtergelaten!

De meeste programmeertalen kennen het concept van commentaar. PowerShell is daarop geen uitzondering. In PowerShell is je vriend #. Alles wat volgt op de hashtag (#) in dezelfde regel wordt door PowerShell genegeerd als geïnterpreteerde code.

De voorbeeldcode hieronder is een fragment van een script dat… nou ja, u kunt het PowerShell-scriptcommentaar op de eerste regel raadplegen om te weten wat het doet. Als je een PowerShell expert bent, kun je waarschijnlijk aanwijzen wat dit fragment doet zonder het commentaar.

# Get all files with TXT extension, show the name of each file and then delete them.Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName}

Maar, hoe zit het als je een kort commando tegenkomt zoals deze hieronder?

"{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

Het toevoegen van commentaar zal jou of iedereen die uiteindelijk je code zal lezen een grote dienst bewijzen. Zoals je hieronder kunt zien, maakt het toevoegen van een commentaar boven het terse commando veel verschil in het begrijpen van de code.

#Check whether the object has a property named "count". Then, return true or false."{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

In de vorige sectie heb je geleerd dat een commentaar begint met een # teken. Er is geen beletsel om meerdere regels met commentaar te maken. In feite was vóór PowerShell 2.0 de enige manier om commentaar van meerdere regels te maken, het maken van commentaar van meerdere regels van één regel.

Het is goed om commentaar kort en bondig te houden, maar sommige scenario’s vragen om het gebruik van een PowerShell-meerregelig commentaar, dat ook kan worden aangeduid als een PowerShell-commentaarblok.

Een commentaarblok in PowerShell begint met <# en eindigt met #>. Hieronder vindt u enkele voorbeelden van wanneer een commentaarblok van toepassing is.

Een lang commentaar opsplitsen in meerdere regels

Het is soms onvermijdelijk om een lang commentaar in een script te hebben. Deze lange commentaren kunnen veel verder gaan dan het huidige frame van het scherm. Als dat gebeurt, moet u horizontaal blijven scrollen om de hele commentaarregel te kunnen lezen.

Voorbeeld, in plaats van een lange commentaarregel zoals:

# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.

Waarom maak je er geen meerregelig commentaar van dat gemakkelijker te lezen is zoals dit hieronder:

<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>

Beschrijvende tekst toevoegen

Heb je ooit een script gedownload of geschreven, en opgeslagen onder een willekeurige of niet-beschrijvende naam? Ik in ieder geval wel!

Als je het script opent om uit te zoeken wat het is, zou het fijn zijn als er nuttige details in staan, zoals waar het script voor dient, wie het heeft gemaakt en wanneer het is gemaakt.

Een blokcommentaar in PowerShell is handig om beschrijvende tekst aan je scripts toe te voegen. Op deze manier is het doel van het script al gegeven en het is ook een goede manier om waarschuwingen of dingen om op te letten bij het gebruik van het script op te nemen.

Hieronder staat een voorbeeld van een block comment die beschrijft wat het script is, wanneer het voor het laatst is bijgewerkt en ook een waarschuwing laat zien wat niet te doen als je het script uitvoert.

<# Using this script will export the email addresses of all mailboxes in the Exchange organization.WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.Last update: Feb 16, 2020#>

Documenteren van vereisten en stappen

Als je script een specifieke manier heeft om uit te voeren, of speciale vereisten heeft om uit te voeren, zou blokcommentaar helpen bij het documenteren ervan binnen je script of functie.

Hieronder staat een voorbeeld van het documenteren van een vereiste en stappen met behulp van blokcommentaar.

<#This function requires an encrypted credential XML file that will be usedto authenticate with Office 365.If you don't have this yet, follow these steps.1. Open PowerShell2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'3. Make sure to save the XML file inside the same folder as the script.NOTE: The credential XML file will only work on the same computer and the same accountused to generate it.#>

Bestaande code becommentariëren

Commentaren worden niet alleen gebruikt om commentaar toe te voegen. U kunt ook bestaande regels code veranderen in commentaar van één regel of blok.

Misschien bent u bezig met het testen of debuggen van scripts.

U hebt bijvoorbeeld een script dat een lijst met gebruikers in Active Directory ophaalt, en die lijst wordt verwerkt met de foreach-lus om de afdelingsnaam van elke gebruiker in te stellen met het cmdlet Set-AdUser.

<#This script will get all AD users matching the filterand each user's department name will be changed to 'Finance'.#>$adUsers = Get-ADUser -Filter *foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

Maar als u de foreach-lus wilt testen zonder de Set-AdUser regel uit te voeren, dan hoeft u die regel alleen maar als volgt te becommentariëren:

foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

Nu kan het script veilig worden getest zonder dat de afdelingsnaam van elke gebruiker daadwerkelijk wordt gewijzigd.

TIP: In Visual Studio Code kunt u een regel of meerdere regels uitcommentariëren door op de sneltoets “CTRL + /” te drukken.