Rückgabewerte aus Skriptblöcken

In vielen Programmier- und Skriptsprachen müssen Rückgabewerte einer Funktion explizit angegeben werden, z.B. mit dem Schlüsselwort Return. In Powershell ist das nicht notwendig – alle Ausgaben, die die Funktion generiert, werden aus dem Skriptblock in die sogenannte Standardausgabe geschrieben, und können von hier aus in einer Variablen aufgefangen oder ein die Pipeline weitergeleitet werden.

function Write-FromScriptblock
{
   'Dies ist eine Ausgabe aus dem Skriptblock'
}

 Rufen Sie die Funktion auf, so wird der String "Dies ist eine Ausgabe aus dem Skriptblock" in die Standardausgabe geschrieben.

Write-FromScriptblock
> Dies ist eine Ausgabe aus dem Skriptblock

 Wollen Sie die Ausgabe der Funktion weiterverarbeiten, weisen Sie sie einer Variablen zu:

$Textausgabe = Write-FromScriptblock

Genauso können Sie die Ausgabe natürlich auch an die Pipeline übergeben:

$Textausgabe | Set-Clipboard

Powershell unterstützt das Schlüsselwort Return ebenfalls, in den meisten Fällen ist es aber überflüssig, da jede Ausgabe aus dem Skriptblock außerhalb des Skriptblocks durch eine Variablenzuweisung wieder aufgefangen werden kann. Ein expliziter Return ist also nicht notwendig.

Return hat allerdings noch eine Besonderheit, denn es beendet die Verarbeitung des Skriptblocks. Jeglicher Code, der in einem Skriptblock hinter einem Return steht, wird nicht mehr aufgerufen.

function Write-ReturnFromScriptblock
{
   Return 'Dies ist eine Ausgabe aus dem Skriptblock' 
   'Dieser Text wird nie ausgegegen'
}

Write-ReturnFromScriptblock

Werden aus einer Funktion mehrere Rückgabewerte geliefert, speichert Powershell diese in einem Array:

Function Write-ReturnArrayFromScriptblock
{
Param(
   [int]$Wert1, [int]$Wert2
)
   'Summe: ' + ( $Wert1 + $Wert2 ) 
   'Produkt: ' + ( $Wert1 * $Wert2 )
}

$Ergebnis = Write-ReturnArrayFromScriptblock -Wert1 10 -Wert2 20
$Ergebnis.gettype().Fullname
> System.Object[]
$Ergebnis
> Summe: 30
> Produkt: 200

Um zu testen, ob es sich bei dem Rückgabewert um ein Array handelt, kann man den Operator -is verwenden:

$ergebnis = Write-ReturnArrayFromScriptblock
$ergebnis –is [Array]

Wenn Sie mehrere Arrays aus einem Skriptblock zurückgeben, werden diese zu einem einzigen Array zusammengefasst:

function Return-Value
{
   $arr1 = 1,2,3,4
   $arr2 = 5,6,7
   $arr1
   $arr2
}

$Rueckgabe = Return-Value

$Rueckgabe enthält also nicht zwei Arrays, sondern nur eins. Um die beiden Arrays in der Rückgabe beizubehalten, müssen Sie die Arrays komma-separiert ausgeben:

function Return-Value
{
   $arr1 = 1,2,3,4
   $arr2 = 5,6,7
   $arr1,$arr2
}
$Rueckgabe = Return-Value

Ausgabekanäle

Wenn Sie Rückgaben aus einer Funktion in die Konsole ausgeben wollen, ohne dass diese in der Standardausgabe landen, haben Sie eine Reihe von unterschiedlichen Cmdlets zur Verfügung: 

Nur Write-Output schreibt dabei in die Standardausgabe (Kanal 1). Dadurch ist es möglich, z.B. in der Pipeline eine Fehlerausgabe zu erzeugen, ohne dass diese hinterher in der Ausgabevariable aufgefangen wird oder sogar die Verarbeitung der Pipeline unterbricht.

Das kann man sehr gut sehen, wenn man Get-Childitem auf den Windows-Ordner ausführt:

$Folder = Get-ChildItem -Path C:\Windows\System32 -Recurse -Directory

Direkt in den Fehlerdatenstrom können Sie mit dem Cmdlet Write-Error schreiben:

Write-Error -Exception 'Ein böser Benutzer hat die Tastatur verschmutzt'
> Ein böser Benutzer hat die Tastatur verschmutzt
> + CategoryInfo : NotSpecified: (:) [Write-Error], Exception
> + FullyQualifiedErrorId : System.Exception

Jedes der Write-Cmdlets schreibt in einen anderen Kanal. Stellen Sie sich die einzelnen Kanäle einfach wie eine mehrspurige Autobahn vor, in der jedes Objekte immer auf seiner Spur bleibt. Einige Kanäle werden am Ende der Verarbeitung direkt in die Konsole (das Powershell-Fenster) ausgegeben, manche werden unterdrückt, wenn sie nicht in eine sichtbare Ausgabe gezwungen werden. Man kann einen Kanal auch ausleiten. Das geschieht durch den Umleitungsoperator >.

Get-ChildItem -Path C:\Windows\System32 -Recurse -Directory 2> c:\Temp\Error.log

Die Fehlerausgabe wird jetzt nicht mehr in die Konsole ausgegeben, sondern in die Datei Error.log. Die Zahl zwei ist der Kanal für Fehlermeldungen. Achten Sie darauf, dass er ohne Leerzeichen direkt vor dem Umleitungsoperator stehen muss.

Es ist auch möglich, einen "Spurwechsel" zu erzwingen:

$files = Get-ChildItem -Path C:\Windows\System32 -Recurse -Directory 2>&1

In diesem Fall wird der Ausgabestrom 2 in den Ausgabestrom 1 umgeleitet ("addiert", deshalb das &). Die Fehlermeldungen werden jetzt auch in die Standardausgabe geschrieben und landen damit ebenfalls in der Variablen $files.

Manche Datenströme werden standardmäßig nicht in die Konsole weitergeleitet und sind daher nicht sichtbar, wie z.B. die Ausgabe von Write-Verbose.

Write-Verbose -Message 'Ein Blumenkohl im Ohr ist auch ein schöner Flor'

Sie müssen in der Konsole erst die Ausgabe von ausführlichen Meldungen aktivieren. Der Powershell-Host steuert dabei über die Standardvariable $VerbosePreference, ob ausführliche Meldungen angezeigt werden oder nicht. Setzen Sie die Variable vom Standardwert "SilentlyContinue" auf den Wert "Continue", werden alle ausführlichen Meldungen ausgegeben. Achten Sie darauf, dass Continue als String in Anführungszeichen angegeben ist. Lassen Sie die Anführungszeichen weg, gibt es keinen Fehler, aber der Standardwert wird nicht umgestellt.

$VerbosePreference="Continue"
Write-Verbose -Message 'Ein Blumenkohl im Ohr ist auch ein schöner Flor'
> Ein Blumenkohl im Ohr ist auch ein schöner Flor

Um alle Ausgaben von Write-Host aus einer Funktion oder einem Cmdlet unabhängig vom Status der VerbosePreference-Variable anzuzeigen, können Sie den Parameter -Verbose verwenden, der an jedem Cmdlet und jeder erweiterten Funktion verfügbar ist.

function Out-Verbose
{
[Cmdletbinding()] 
param()
   Out-Verbose -Message 'Ein Blumenkohl in Ohr ist auch ein schöner Flor'
}

Out-Verbose -Verbose
> Ein Blumenkohl in Ohr ist auch ein schöner Flor

Die Funktion Out-Verbose verwendet das Cmdlet Write-Verbose, um eine Ausführliche (Verbose) Information auszugeben. Die Ausgabe wird aber nur dann in die Ausgabe geschrieben, wenn sie explizit mit dem Parameter Verbose angefordert wird (oder die Standardvariable $VerbosePreference global auf "Continue gesetzt ist"). Alle Funktionen bekommen diesen Parameter automatisch aktiviert, allerdings muss man dafür eine erweiterte Funktion (Advanced Function) erstellen. Die einfachste Möglichkeit, eine Advanced Functions zu bekommen ist, einen Parameter mit einem Parameter-Attribut zu definieren. Werden keine Parameter benötigt, kann man einen leeren Parameter-Block anlegen und das Attribut [Cmdletbinding()] über den Parameter-Block schreiben. 

In der Powershell-Konsole wird über eine Reihe von Einstellungsvariablen gesteuert, welche Ausgabeströme angezeigt werden, und welche nicht:

Tabelle 1 - Preference-Variablen steuern das Ausgabeverhalten

Die möglichen Einstellungen sind durch Actionpreferences festgelegt. Die Actionpreference stellt die Standardkonfiguration für ein Kommando dar, wenn beim Aufruf kein anderes Verhalten durch einen der Standard-Parameter festgelegt wird. Die möglichen Werte für Actionpreference und deren Bedeutung finden Sie in der folgenden Tabelle:

Tabelle 2 - ActionPreference-Einstellungen 

Mehr Informationen zu den Actionpreferences finden Sie in der Powershell-Hilfe für Standardparameter:

get-help about_commonparameters

Grundsätzlich können Sie Write-Verbose verwenden, um Ausgaben nur dann anzuzeigen, wenn der Benutzer sie mit dem Parameter -Verbose explizit anfordert. Write-Warning und Write-Error verwenden Sie, um Warnungen und Fehler auszugeben, die die Weiterverarbeitung des Skriptes nicht verhindern, aber dem Benutzer sichtbar gemacht werden sollen, wie z.B. ein Zugriffsfehler auf einen Ordner. Im Gegensatz zu ausführlichen Meldungen werden Warnungen und Fehler standardmäßig angezeigt.

Write-Debug verwenden Sie, wenn Sie Ausgaben erzeugen wollen, die Sie zum Debugging (also zur Fehlerbehandlung) aus dem Skript ausgeben möchten. Wird ein Skriptblock mit dem Standardparameter -Debug aufgerufen, werden aber nicht nur die Debug-Meldungen ausgegeben, sondern es wird auch nach jedem Befehl zur Bestätigung aufgefordert.

Mehr zur Fehlerausgabe mit Write-Errorfinden Sie auch im Abschnitt Debugging und Fehlerbehandlung ab S. 90.

function Out-Verbose
{
[Cmdletbinding()] 
param()
   Out-Verbose -Message 'Ein Blumenkohl in Ohr ist auch ein schöner Flor'
}

Out-Verbose -Verbose
> Ein Blumenkohl in Ohr ist auch ein schöner Flor