Fehlerbehandlung in PowerShell-Adminskripten: Terminating Errors, $ErrorActionPreference und $LASTEXITCODE

Ziel

Ein PowerShell-Adminskript soll bei relevanten Fehlern abbrechen und ein korrektes Ergebnis melden, statt nach einem Fehler weiterzulaufen und mit 0 zu enden.

Voraussetzungen

Windows PowerShell 5.1 oder PowerShell 7.x; um Exit-Codes nativer Befehle als Fehler zu behandeln, ist PowerShell 7.4 oder neuer nötig (7.3 nur mit aktiviertem experimentellem Feature PSNativeCommandErrorActionPreference).

Schritte

1. Die drei Fehlerarten unterscheiden. Ein Terminating Error beendet die aktuelle Pipeline bzw. den aktuellen Scope sofort und lässt sich mit try/catch abfangen. Ein Non-terminating Error (zum Beispiel durch Write-Error in einem Cmdlet) wird in den Fehlerstrom geschrieben, die Ausführung läuft aber weiter, sofern nicht $ErrorActionPreference des Aufrufers oder der eigene -ErrorAction des Cmdlets etwas anderes vorgibt. Eine native ausführbare Datei (git.exe, robocopy.exe, ...), die einen Exit-Code ungleich 0 zurückgibt, löst standardmässig keines von beiden aus: PowerShell macht daraus nicht automatisch einen Fehler.
2. Am Anfang des Skripts $ErrorActionPreference = 'Stop' setzen, damit Non-terminating Errors auf Cmdlet-Ebene zu Terminating Errors werden und abfangbar sind. about_Preference_Variables beschreibt diese Variable als Einstellung, die "determines how PowerShell responds to a non-terminating error". Auf die Exit-Codes nativer Programme wirkt sie sich nicht aus.
3. Soll ein einzelner Aufruf scheitern dürfen, ohne das ganze Skript abzubrechen, lokal mit -ErrorAction Stop (zum Abfangen) oder -ErrorAction SilentlyContinue/Continue (zum Ignorieren) übersteuern, statt die globale Einstellung zu ändern. -ErrorAction betrifft nur die Non-terminating Errors des jeweiligen Befehls; einen Terminating Error kann es nicht unterdrücken.
4. Riskante Abschnitte in try { ... } catch { ... } finally { ... } kapseln. Im catch-Block $_.Exception.Message und $_.CategoryInfo auswerten; finally dient für Aufräumarbeiten, die in jedem Fall laufen müssen (Sitzung schliessen, temporäre Datei löschen).
5. Nach jedem Aufruf einer nativen ausführbaren Datei $LASTEXITCODE ausdrücklich prüfen (about_Automatic_Variables beschreibt sie als Exit-Code des zuletzt ausgeführten nativen Programms oder PowerShell-Skripts). Ein Wert ungleich 0 löst keine Ausnahme aus und wird von try/catch nicht erfasst, solange er nicht geprüft wird.
6. Ab PowerShell 7.4 (Standardwert $false) mit $PSNativeCommandUseErrorActionPreference = $true dafür sorgen, dass native Befehle mit Exit-Code ungleich 0 Fehler auslösen, die $ErrorActionPreference berücksichtigen, analog zum bestehenden Verhalten bei Cmdlet-Fehlern. Für Tools wie robocopy, die Codes ungleich 0 für etwas anderes als einen Fehlschlag verwenden, die Einstellung lokal in einem Skriptblock deaktivieren (& { $PSNativeCommandUseErrorActionPreference = $false; robocopy ... }).
7. Ganz am Ende des Skripts das tatsächliche Ergebnis mit exit $LASTEXITCODE oder einem bestimmten numerischen exit-Code weiterreichen, damit ein externer Aufrufer Erfolg oder Misserfolg korrekt erkennt.

Erwartetes Ergebnis

Ein Cmdlet-Fehler, eine ausgelöste Ausnahme und ein fehlgeschlagener nativer Befehl werden abgefangen oder ausdrücklich geprüft. Der Exit-Code des Skripts spiegelt wider, was tatsächlich passiert ist, statt immer 0 zu lauten.

Grenzen und Prüfbasis

$PSNativeCommandUseErrorActionPreference ist ab PowerShell 7.4 regulär verfügbar, war in 7.3 experimentell und hat in Windows PowerShell 5.1 keine Wirkung. $ErrorActionPreference = 'Stop' in einem Skript beeinflusst die Sitzung des Aufrufers nicht, es sei denn, das Skript läuft im Scope des Aufrufers (Dot-Sourcing). Funktionen aus einem Skriptmodul sehen die Preference-Variablen des aufrufenden Skripts nicht; daher -ErrorAction Stop ausdrücklich an sie übergeben. In Windows PowerShell 5.1 (sowie 7.0/7.1) kann das Umleiten von stderr eines nativen Befehls mit 2>&1 bei der Einstellung Stop eine harmlose stderr-Zeile in einen Terminating Error verwandeln; ab 7.2 wird umgeleitetes stderr nicht mehr als Error Record behandelt.