Den PowerShell WhatIf-Parameter beherrschen

„Ich teste meine Skripte nicht immer, aber wenn ich es tue, mache ich es in der Produktion.“

Lüg nicht. Du hast es schon einmal gemacht. Wir alle haben das irgendwann getan. Es muss jedoch nicht riskant sein, PowerShell-Skripte in der Produktion auszuführen. Denken Sie einfach daran, den eingebauten PowerShell-WhatIf-Parameter zu verwenden!

Wäre es nicht schön zu wissen, was dieser PowerShell-Befehl tun würde, bevor er Änderungen an Ihrer Umgebung vornimmt? Stellen Sie sich vor, Sie könnten Ihren Befehl fragen: „Was würdest du tun, wenn du ausgeführt würdest?“ Sie können den WhatIf-Parameter verwenden.

Alle kompilierten PowerShell-Cmdlets enthalten einen Parameter namens WhatIf. Dieser Parameter hilft Ihnen zu bewerten, ob ein Befehl wie erwartet funktioniert oder ob er einen nuklearen Schmelzpunkt auslöst.

Der praktische WhatIf-Parameter ist nicht nur bei allen eingebauten Cmdlets verfügbar, sondern auch für Ihre Skripte und erweiterten Funktionen! Wenn Ihr Code Dinge in Ihrer Umgebung ändern wird, haben Sie den Vorteil eines Fehlerschutzmechanismus, den Sie implementieren können, wenn Sie möchten.

Voraussetzungen

In diesem Artikel werde ich eine Schritt-für-Schritt-Anleitung geben. Wenn Sie während dieser Reise mitmachen möchten, sollten Sie ein paar Dinge vorbereitet haben.

• A Windows computer capable of running Powershell v5.1. (Windows 10 and above recommended)
• A script editor like Notepad++, the Windows PowerShell ISE or Visual Studio Code.

Beachten Sie, dass ich in diesem Artikel Visual Studio Code 1.38 (August 2019) auf einem Windows 10-Computer verwende.

Der WhatIf-PowerShell-Parameter: Definiert

In aller Kürze ist der WhatIf-Parameter ein integrierter Switch-Parameter, der bei allen erweiterten Funktionen und Cmdlets verfügbar ist (indem das PowerShell-Schlüsselwort CmdletBinding zu Skripten und Funktionen hinzugefügt wird). Wenn er verwendet wird, gibt der Befehl den erwarteten Effekt des Befehls in der Konsole aus, führt den Befehl jedoch nicht tatsächlich aus.

Alle Cmdlets und erweiterten Funktionen haben den WhatIf-Parameter zur Verfügung. In diesem Artikel werden wir diesen Parameter anhand der Cmdlets Get-Service, Stop-Service und New-Item demonstrieren.

Überprüfung der Unterstützung von Powershell WhatIf

Wenn Sie nicht sicher sind, ob ein bestimmter Befehl WhatIf unterstützt, gibt es zwei schnelle Möglichkeiten zur Überprüfung.

Verwendung von Get-Command

Sie können den Befehl Get-Command verwenden, um die Befehls-Metadaten anzuzeigen, indem Sie den Parameter Syntax wie unten gezeigt verwenden. Wenn Sie einen Verweis auf -WhatIf sehen, wird WhatIf unterstützt.

Verwendung der Tabulatortaste

Sie können auch die Unterstützung des WhatIf-Parameters mit der Tabulatortaste überprüfen. Geben Sie einfach den Befehl ein, den Sie überprüfen möchten, gefolgt von einem Leerzeichen, einem Bindestrich, ‚Wh‘ und der Tabulatortaste.

Wenn WhatIf angezeigt wird, wissen Sie, dass der Befehl den WhatIf-Parameter hat.

Verwendung des PowerShell WhatIf-Parameters mit Cmdlets

Es gibt viele verschiedene Möglichkeiten, den WhatIf-Parameter zu nutzen. In diesem Abschnitt erfahren Sie, wie Sie den WhatIf-Parameter sofort mit den integrierten cmdlets verwenden können.

Erstellen einer Datei

Wie alle cmdlets verfügt auch das New-Item-cmdlet über einen WhatIf-Parameter. In diesem Beispiel verwenden Sie das New-Item-cmdlet, um eine Datei mit dem Namen newfile1.txt im selben Arbeitsverzeichnis zu erstellen.

Wenn Sie den folgenden Befehl ausführen würden, würde er die Datei mit dem Namen newfile.txt erstellen.

Aber was ist, wenn dieser Befehl eine Datei erstellt, die möglicherweise ein Problem verursacht, wenn sie nicht erfolgreich erstellt wurde? Kein Problem. Sie können den WhatIf-Parameter am Ende hinzufügen.

Anhalten eines Dienstes

Sie können den WhatIf-Parameter auch mit dem Stop-Service-cmdlet verwenden. In diesem Beispiel erhalten Sie eine Liste der ersten fünf Dienste und stoppen sie mit dem Stop-Service-Befehl. Aber das tun Sie nicht.

Stattdessen sehen Sie nur eine Ausgabemeldung in der PowerShell-Konsole, die Ihnen mitteilt, welche Dienste das Stop-Service-cmdlet gestoppt hätte.

Globales Ändern des Powershell WhatIf-Verhaltens

Zu diesem Zeitpunkt sollten Sie wissen, dass die Verwendung des WhatIf-Parameters bei einem cmdlet oder einer erweiterten Funktion die Operation nur simuliert. Sie haben das WhatIf-Verhalten auf Befehlsebene beeinflusst.

Das Verhalten von WhatIf kann auch auf einer höheren Ebene festgelegt werden, die alle Befehle betrifft, indem die automatische Variable $WhatIfPreference manipuliert wird.

Die Variable $WhatIfPreference ist boolesch. Sie kann nur True oder False sein. Standardmäßig ist sie auf False eingestellt, was bedeutet, dass die Unterstützung von WhatIf für alle Befehle deaktiviert ist, es sei denn, es wird auf Befehlsebene überschrieben. Wenn sie auf True gesetzt ist, befinden sich alle Befehle, die es unterstützen, ob explizit mit dem WhatIf-Parameter oder nicht, im „WhatIf-Modus“.

Sie können dies testen, indem Sie den Wert von $WhatIfPreference auf True ändern, über $WhatIfPreference = $true. Sie können unten sehen, dass New-Item ohne den WhatIf-Parameter nun so funktioniert, als ob der Parameter übergeben wurde.

Wenn Sie $WhatIfPreference auf True geändert haben, vergessen Sie nicht, es über $WhatIfPreference = $false wieder auf False zurückzusetzen.

In diesem Abschnitt haben Sie gelernt, wie Sie die Unterstützung von WhatIf bei vorhandenen Cmdlets verwenden können. In der nächsten Aktion lernen Sie, wie Sie die Unterstützung von WhatIf in Ihren eigenen Skripten und Funktionen implementieren können.

Implementierung der Powershell WhatIf-Unterstützung in Funktionen

Bevor Sie versuchen, WhatIf-Unterstützung in Ihren Skripten zu implementieren, ist es wichtig zu wissen, dass es eine falsche und eine richtige Methode gibt. In den nächsten Abschnitten werden Sie sehen, was diese sind.

Es falsch machen: Das Rad nicht neu erfinden

Es ist nicht ungewöhnlich, dass Skriptentwickler das Rad neu erfinden und ihre eigene WhatIf-Unterstützung mit einigen if/then-Logiken implementieren. Unten sehen Sie ein Beispiel.

Beachten Sie, dass der Entwickler seinen eigenen WhatIf-Schalterparameter definiert hat. Anschließend verwenden sie den Wert dieses Parameters, um mit einer if/then-Konstruktion die Logik zu steuern, wenn der WhatIf-Parameter verwendet wird oder nicht.

Function Remove-LogFile {
    param (
        [Parameter(Mandatory)]
        [string]$name,

        [switch]$WhatIf
    )
    
    if ($WhatIf.IsPresent) { # WhatIf-Schalter ist aktiviert.
        Write-Host "WhatIf: I will remove the log file ""$name""" -ForegroundColor Yellow
    } else {
        # WhatIf-Schalter ist deaktiviert.
        Write-Host "Delete log file ""$name""" -ForegroundColor Green
    }
}

Wenn die obige Funktion mit dem WhatIf-Parameter wie folgt ausgeführt wird, scheint sie ihre Aufgabe erfüllt zu haben. Die Funktion hat tatsächlich nichts entfernt und eine Nachricht an die Konsole zurückgegeben.

Wenn es funktioniert, was ist dann falsch an dieser Methode? Sie vernachlässigen die integrierten Funktionen einer erweiterten Funktion. Sie müssen diese Funktionalität in jede Funktion einbauen, die Sie erstellen, anstatt sich nur darauf zu konzentrieren, was der Befehl tut, wenn er deaktiviert ist.

Stattdessen sollte man das Rad nicht neu erfinden und das Schlagwort SupportsShouldProcess in Kombination mit $PSCmdlet.ShouldProcess() verwenden. Das kommt gleich.

Richtig machen: Verwendung von SupportsShouldProcess

Alle Funktionen, die das Schlüsselwort [CmdletBinding()] verwenden, machen sie „fortgeschritten“. Dieses Schlüsselwort fügt der Funktion verschiedene Fähigkeiten hinzu, einschließlich der Unterstützung für WhatIf.

Alle fortgeschrittenen Funktionen unterstützen die WhatIf-Funktionalität, aber es liegt an Ihnen, sie zu nutzen. Dazu müssen Sie das Schlüsselwort SupportsShouldProcess zwischen den Klammern von [CmdletBinding()] wie unten gezeigt verwenden.

[CmdletBinding(SupportsShouldProcess)]

Die Funktion ermöglicht es Ihnen nun, die Methode ShouldProcess() auf der Funktion $PSCmdlet aufzurufen, um festzustellen, ob der WhatIf-Parameter an die Funktion übergeben wurde oder nicht. Wenn der WhatIf-Parameter verwendet wird, gibt ShouldProcess() False zurück. Andernfalls gibt sie immer True zurück.

Function Remove-LogFile {
     [cmdletbinding(SupportsShouldProcess)]
     param (
         [Parameter(Mandatory)]
         [string]$name
     )
     if ($PSCmdlet.ShouldProcess($name)) {
         ## Der -WhatIf-Parameter wurde NICHT verwendet. Die Funktion sollte normal verarbeitet werden.
         Write-Host ("Delete log file " + $name) -ForegroundColor Green
     } else {
         ## Der -WhatIf-Parameter wurde verwendet. Die Funktion sollte NICHT verarbeitet werden.
     }
 }

Jetzt können Sie unten sehen, wenn Remove-LogFile mit dem WhatIf-Parameter ausgeführt wird; es zeigt das gleiche Verhalten wie eingebaute Cmdlets.

Zusammenfassung

In diesem Artikel haben Sie über den PowerShell WhatIf-Parameter gelernt. Sie sollten jetzt verstehen, wie er funktioniert und welche Vorteile er mit sich bringt.

Sie sollten auch wissen, dass Sie beim nächsten Mal, wenn Sie eine Ausfallsicherung für Ihre PowerShell-Funktionen benötigen, das Rad nicht neu erfinden sollten. Nutzen Sie stattdessen die vorhandene PowerShell-Unterstützung für WhatIf!

Weitere Informationen

• Wie man bessere Skripte mit PowerShell-Modulen schreibt
• Über die CmdletBindingAttribute-Funktion SupportsShouldProcess
• Über Präferenzvariablen