• English
Shop

| | Data Center 0

PowerShell: Rückgabewerte von Funktionen, Kommentare und Hilfe – Part 16

Solange eine Funktion Befehle enthält, welche eine Bildschirmausgabe tätigen (und das tun fast alle Befehle), ist eine dedizierte Rückgabe von Werten aus einer Funktion nicht notwendig:

?
1
2
3
4
5
6
7
8
1.  PS X:\Temp> function Get-Density([Int32]$Mass, [Int32]$Volume)
2.  >> {$Mass/$Volume}
3.  >>
4.  Get-Density 40 100
0,4
5.  $a = Get-Density 33 50
6.  $a
0,66

 

Eine direkte Zuweisung einer Funktion zu einer Variablen speichert dort die Ausgabe der Funktion (ausgenommen sind hier Ausgaben, welche direkt auf den Bildschirm schreiben, wie Write-Host, Out-Host, etc.). In vielen Fällen ist das völlig ausreichend. Was aber, wenn in bestimmten Fällen die Funktion an einer früheren Stelle verlassen werden muss und trotzdem etwas zurück liefern soll? Dafür hält die PowerShell die Return Anweisung bereit:

?
1
2
3
4
5
6
7
8
1.  Function Get-Density ([Int32]$Mass, [Int32]$Volume)
2.  >> {
3.  >> if*  ($Volume -le 0) {return "Infinity"}
4.  >> $Mass/$Volume
5.  >> }
6.  >>
7.  Get-Density
Infinity

 

Da die beiden Parameter nicht explizit initialisiert wurden, hat das die PowerShell übernommen und zwar mit dem Wert $Null. In Zeile drei wird überprüft, ob $Volume größer als Null ist, damit die Dichte einen endlichen Wert ergibt. Ist das nicht der Fall wird die gesamte Funktion über die Return Anweisung verlassen. Der Aufruf ohne Argumente (also für $Volume=0) demonstriert dieses Verhalten.

Einer Funktion kann beliebig viele Return Anweisungen enthalten, wenn jeweils ein früherer Ausstieg und gleichzeitig die Rückgabe eines Wertes notwendig sind.

*Die in diesem Beispiel verwendete If-Abfrage wird weiter unten detaillierter behandelt.

 

4.3    Kommentare und Hilfe (Comment-Based Help)

Im Kapitel 3.6 wurde bereits das Cmdlet Get-Help kurz vorgestellt. Die Hilfeinhalte liefern die einzelnen Cmdlets selbst, sie werden von Get-Help nur abgerufen und angezeigt. Die flexible, parametergesteuerte Ausgabe erlaubt es, sich auf das Wesentliche zu konzentrieren und vor allem, das Format der Hilfeausgabe ist immer gleich. Wäre es nicht schön, so etwas würde auch mit selbstgeschriebenen Funktionen und Skripten gehen? Und genau das geht! Es erfordert zwar eine besondere Syntax, aber der Nutzen ist entsprechend groß.
Um in einem Skript oder in einer Funktion die Comment-Based Help zu implementieren wird entweder ein Kommentarblock benötigt oder jedes der sogenannten Comment-Based Keywords muss hinter einem Kommentarzeichen stehen. Als einzelnes Kommentarzeichen wird die Raute [#] zum Auskommentieren einzelner Zeilen verwendet. Mehrere Kommentarzeilen können in Kommentarblöcke eingeschlossen werden:

<#
…
#>

Die Help Keywords beginnen immer mit einem Punkt und stehen alleine in einer Kommentarzeile. Sie leiten Hilfesektionen ein, welche mit dem nächsten Keyword oder mit einer Leerzeile beendet werden. Folgende Tabelle listet die wichtigsten Keywords auf:

 

Help Keyword Beschreibung
.SYNOPSIS Eine kurze Beschreibung der Funktion oder des Skriptes
.DESCRIPTION Detaillierte Beschreibung der Funktion oder des Skriptes
.PARAMETER Die Beschreibung, der in der Funktion oder im Skript verwendeten Parameter. Es wird pro Parameter eine Sektion erzeugt, das Keyword wird von dem Parameternamen (ohne $) gefolgt. Die Reihenfolge der Parameterbeschreibungen in der Hilfe ist beliebig. Zur Anzeige mit Get-Help wird die Reihenfolge der Definition der Parameter verwendet.
.EXAMPLE Ein oder mehrere Beispiele für die Verwendung der Funktion oder des Skriptes. Hier kann auch ein Beispiel für die Ausgabe aufgeführt werden.
.NOTES Platz für zusätzliche Informationen über die Funktion oder das Skript
.LINK Falls vorhanden, ein Link zu weiter führenden Themen
.INPUT Beschreibung der Eingabe für die Funktion oder das Skript. Hier kann beispielsweise vermerkt werden, ob Eingaben von der Pipeline verarbeitet werden können
.OUTPUT Ein Hinweis auf die Art der Ausgabe

Tabelle 4 -2: Keywords für Comment-Based Help.

Alle Keywords sind optional. Die Anzeige der Hilfeinhalte ist abhängig von den Argumenten, welche an Get-Help übergeben werden. Im einfachsten Fall wird (wie auch bei Cmdlets) nur die Kurzform der Hilfe angezeigt. Mit dem Switch „-Full“ kann die vollständige Hilfe angezeigt werden und mit „-Examples“ nur die Beispiele aus der Sektion „.EXAMPLE“. Im Kapitel 9.1.1 ist ein Beispiel eines Skriptes aufgeführt, welches die Command-Based Help implementiert.

 

Es wurde oft bei der sepago über Funktions- oder Skriptköpfe diskutiert. Sie beinhalten Versionsinformationen, Angaben zum Ersteller, Erstellungsdatum, Changehistory, etc. Es empfiehlt sich bei PowerShell Skripten und Funktionen die Sektion „.NOTES“ dafür zu verwenden, siehe auch das Beispiel Get-Lottery.ps1 im Anhang.

 

Zurück zu Part 15.3 – Parametersets

Weiter zu Part 17.1 – Sprachkonstrukte (If/ElseIF/Else Anweisung)

Eine Übersicht aller Artikel dieser Windows PowerShell Blogserie findet ihr hier.