Wenn PowerShell-Neulinge mit dem Schreiben von Skripts beginnen, konzentrieren sie sich normalerweise auf den Code. Schließlich ist es der Code, der die Dinge geschehen lässt! Ausführbarer Code ist natürlich wichtig, aber was passiert, wenn Sie so viel Code schreiben, dass Sie vergessen, was er bewirkt? In diesem Fall können PowerShell-Kommentare helfen.

Wenn Sie in einem Team arbeiten, verstehen die Mitarbeiter den Code, den Sie schreiben? PowerShell-Kommentare können helfen.

Das Schreiben von beschreibenden und informativen PowerShell-Kommentaren in Skripten hilft uns Menschen, die Absicht des Codes und das Ergebnis zu verstehen, und beschreibt vielleicht Randfälle, die einmal aufgetreten sind.

In diesem Artikel lernen Sie die verschiedenen Arten von Kommentaren in PowerShell kennen, welche Sie verwenden können und wie Sie sie effektiv in Ihren Skripts einsetzen.

Haben Sie schon einmal Code geschrieben und mussten ihn Wochen oder Monate später überprüfen? Wahrscheinlich. Haben Sie ihn so viel später verstanden? Vielleicht nicht. Wenn Sie nur ein paar nützliche Kommentare in Ihrem Code hinterlassen hätten!

Die meisten Programmiersprachen haben ein Konzept der Kommentierung. PowerShell ist da keine Ausnahme. In PowerShell ist Ihr Freund das #. Alles, was nach dem Hashtag (#) in derselben Zeile folgt, wird von PowerShell als interpretierter Code ignoriert.

Der Beispielcode unten ist ein Auszug aus einem Skript, das… nun, Sie können sich auf den PowerShell-Skriptkommentar in der ersten Zeile beziehen, um zu wissen, was es tut. Wenn Sie ein PowerShell-Experte sind, können Sie wahrscheinlich sagen, was dieses Snippet ohne den Kommentar tut.

# 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}

Aber was ist, wenn Sie auf einen knappen Befehl wie diesen unten stoßen?

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

Das Hinzufügen von Kommentaren erweist Ihnen oder jedem, der Ihren Code irgendwann liest, einen großen Dienst. Wie Sie unten sehen können, macht das Hinzufügen eines Kommentars über dem Terse-Befehl einen großen Unterschied beim Verständnis des Codes.

#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

Im vorherigen Abschnitt haben Sie gelernt, dass ein Kommentar mit einem #-Zeichen beginnt. Es hält Sie nicht davon ab, mehrere Zeilen mit Kommentaren zu erstellen. Tatsächlich war vor PowerShell 2.0 die einzige Möglichkeit, mehrzeilige Kommentare zu erstellen, die Erstellung mehrerer Zeilen einzeiliger Kommentare.

Es ist gut, Kommentare kurz und prägnant zu halten, aber einige Szenarien erfordern die Verwendung eines mehrzeiligen PowerShell-Kommentars, der auch als PowerShell-Kommentarblock bezeichnet werden kann.

Ein Kommentarblock in PowerShell beginnt mit <# und endet mit #>. Im Folgenden finden Sie einige Beispiele, wann ein Kommentarblock anwendbar ist.

Aufteilung eines langen Kommentars in mehrere Zeilen

Es ist manchmal unvermeidlich, einen langen Kommentar in einem Skript zu haben. Diese langen Kommentare können weit über den aktuellen Rahmen der Anzeige hinausgehen. Wenn das passiert, müssen Sie weiter horizontal scrollen, um die gesamte Kommentarzeile zu lesen.

Anstatt eines langen einzeiligen Kommentars wie:

# 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.

Warum machen Sie nicht einen mehrzeiligen Kommentar daraus, der leichter zu lesen ist, wie dieser hier:

<# 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. #>

Beschreibenden Text hinzufügen

Haben Sie jemals ein Skript heruntergeladen oder geschrieben und es unter einem zufälligen oder nicht beschreibenden Namen gespeichert? Ich weiß, dass ich es getan habe!

Wenn Sie das Skript öffnen, um herauszufinden, um was es sich handelt, wäre es sicher schön, wenn darin nützliche Details aufgeführt sind, z. B. wofür das Skript gedacht ist, wer es erstellt hat und wann es erstellt wurde.

Ein Blockkommentar in PowerShell ist nützlich, um beschreibenden Text in Ihre Skripts einzufügen. Auf diese Weise ist der Zweck des Skripts bereits angegeben, und es ist auch eine gute Möglichkeit, Warnungen oder Dinge einzufügen, auf die Sie bei der Verwendung des Skripts achten sollten.

Unten sehen Sie ein Beispiel für einen Blockkommentar, der beschreibt, worum es sich bei dem Skript handelt, wann es zuletzt aktualisiert wurde, und der auch eine Warnung zeigt, was Sie bei der Ausführung des Skripts nicht tun sollten.

<# 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#>

Anforderungen und Schritte dokumentieren

Wenn Ihr Skript eine bestimmte Art der Ausführung hat oder besondere Anforderungen an die Ausführung stellt, helfen Blockkommentare bei der Dokumentation innerhalb Ihres Skripts oder Ihrer Funktion.

Nachfolgend ein Beispiel für die Dokumentation einer Anforderung und von Schritten mit Hilfe von Blockkommentaren.

<#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.#>

Auskommentieren von bestehendem Code

Kommentare dienen nicht nur dazu, Kommentare hinzuzufügen. Sie können auch bestehende Codezeilen in einzeilige oder Blockkommentare verwandeln.

Vielleicht finden Sie sich beim Testen oder Debuggen von Skripten wieder. Wenn Code auskommentiert wird, überspringt PowerShell die Ausführung dieses Codes während der Laufzeit.

Angenommen, Sie haben ein Skript, das eine Liste von Benutzern in Active Directory abruft, und diese Liste wird mithilfe der foreach-Schleife verarbeitet, um den Abteilungsnamen jedes Benutzers mit dem Cmdlet Set-AdUser festzulegen.

<#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'}

Wenn Sie jedoch die foreach-Schleife testen möchten, ohne die Set-AdUser-Zeile auszuführen, müssen Sie diese Zeile einfach auskommentieren:

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

Jetzt kann das Skript sicher getestet werden, ohne den Abteilungsnamen jedes Benutzers zu ändern.

TIP: In Visual Studio Code können Sie eine Zeile oder mehrere Zeilen auskommentieren, indem Sie das Tastaturkürzel „STRG + /“ drücken.

Nun, wenn Sie mehrere Zeilen auskommentieren wollen, haben Sie die Wahl, entweder ein # an den Anfang jeder Zeile zu setzen, oder Sie können mehrere Zeilen innerhalb des <# #>-Blocks einschließen, wie im Beispiel unten gezeigt. Wie Sie sehen, wurde die gesamte foreach-Schleife in einen Blockkommentar umgewandelt.

$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'} #>

TIP: In Visual Studio Code können Sie einen Kommentarblock auch erstellen, indem Sie eine Zeile oder mehrere Codezeilen markieren und das Tastaturkürzel „ALT +SHIFT + A“ drücken.

Kommentar-basierte Hilfe

Wenn Sie Ihre Skripte oder Funktionen professioneller aussehen lassen wollen, können Sie dies erreichen, indem Sie eine kommentarbasierte Hilfe hinzufügen. Eine kommentarbasierte Hilfe ist eine Sammlung von Schlüsselwörtern und Texten, die in einem Blockkommentar eingeschlossen sind.

Besuchen Sie die Seite – Über kommentarbasierte Hilfe – um mehr über das Schlüsselwort und die Syntax der kommentarbasierten Hilfe zu erfahren.

Der Beispielcode unten demonstriert ein Skript mit dem Namen Get-WhatTimeIsItNow.ps1, das eine kommentarbasierte Hilfe enthält.

<#.SYNOPSISShort description of the script.DESCRIPTIONLong description of the script.EXAMPLEPS C:\> Get-WhatTimeIsItNow.ps1Explanation of what the example does.INPUTSInputs (if any).OUTPUTSOutput (if any).NOTESGeneral notes#>Get-Date -Format t

Kommentarbasiert ermöglicht Get-Help Unterstützung für Ihre Skripte. Das bedeutet, dass PowerShell beim Ausführen von Get-Help <script/function> den in Ihrem Skript enthaltenen „Hilfe“-Text zurückgibt, wie in der folgenden Abbildung gezeigt.

TIP: In Visual Studio Code können Sie einen standardmäßigen kommentarbasierten Hilfeblock einfügen, indem Sie im Editorbereich comment-help eingeben.

Best Practices

Hier sind einige der so genannten Best Practices für die Erstellung effektiver Kommentare. Es handelt sich dabei keineswegs um harte Vorgaben, sondern um Empfehlungen, die von vielen bereits praktiziert werden und an denen Sie sich orientieren können.

Beim Schreiben von Code könnten Sie versucht sein, in Ihren Kommentaren einen Verweis auf eine Zeilennummer hinzuzufügen. Sie mögen Recht haben, wenn Sie denken, dass das Hinzufügen von Zeilennummernverweisen Ihren Code um so leichter verständlich macht. Das heißt, wenn Sie sicher sind, dass Ihr Code nie geändert wird.

Stellen Sie sich vor, eine neue Codezeile wird in Ihr Skript eingefügt. Das würde bedeuten, dass alle Zeilennummern-Referenzen in Ihren Kommentaren bereits verschoben wurden. Und um die Zeilennummerierung korrekt zu halten, müssen Sie die Kommentare bearbeiten, um sie nach und nach zu aktualisieren.

Wir Menschen sind es gewohnt, von oben nach unten zu lesen. Wenn der Kommentar, den Sie hinzufügen, für die nachfolgenden Codezeilen wichtig ist, dann ist es nur logisch, die Kommentare davor einzufügen.

Nach allem, wenn Sie im Skript Kommentare über das Skript einfügen, ist es dann nicht sinnvoller, die Kommentare vor dem Code zu haben und nicht danach?

Gleich dem vorherigen Beispiel ist es nicht besser, den Kommentar nach dem Code zu platzieren, auch wenn er in der gleichen Zeile steht, als den Kommentar unter dem Code.

Das Hinzufügen von Kommentaren am Ende des Codes kann zu Bearbeitungsfehlern führen, da man sich nicht auf die Änderung des Codes konzentrieren kann, sondern auch darauf achten muss, dass der Kommentar mit der Änderung des Codes mitgeht.

Das Offensichtliche nicht aussprechen

Manchmal ist der Code einfach zu simpel und die Absicht bereits zu offensichtlich, als dass es eine Verschwendung wäre, einen Kommentar hinzuzufügen. In der Regel kann in dieser Situation ein Kommentar sogar länger sein als der Code, auf den er sich bezieht.

Wenn Sie der Meinung sind, dass der Code selbsterklärend ist, können Sie in Erwägung ziehen, das Hinzufügen eines Kommentars zu überspringen.

Zusammenfassung

In diesem Artikel haben Sie gelernt, wie wichtig es ist, Kommentare zu Ihren PowerShell-Skripts oder -Funktionen hinzuzufügen. Außerdem haben Sie die verschiedenen Arten von Kommentaren kennengelernt und erfahren, wie ein richtig gestalteter und platzierter Kommentar die Lesbarkeit Ihres Codes deutlich erhöhen kann.

Es gibt keine festen Regeln für die Verwendung von Kommentaren in der PowerShell, aber es gibt getestete und bewährte Empfehlungen, wie sie verwendet werden können. Letztendlich bleibt es Ihnen überlassen, wie Sie Kommentare in Ihren Skripten einsetzen wollen, um sich von Anfang bis Ende an die entscheidenden Dinge zu erinnern.

Weiteres Lesen