Patchscripte als Powershell-Scripte erstellen

Dieses Feature steht erst ab Version 3.6.0.0 von mypDeploy zur Verfügung

mypDeploy bietet Ihnen ab Version 3.6.0.0 die Möglichkeit, eigene Scripte zu bestimmten Zeitpunkten während der Patchausführung auszuführen.

Formaler Aufbau

Damit Ihr Patch-Script als Powershell-Script erkannt wird, muss es mit dieser Kommentarzeile beginnen:

# mypDeploy PowerShell Script

Danach können Sie mit beliebigem Powershell-Code fortfahren.

Einstiegs-Funktionen

Folgende Einstiegspunkte werden über einen fix vorgegebenen Funktionsnamen definiert:

  • Function PS-MypdclnEpPreExec (wird ausgeführt, bevor ein Patch ausgeführt wird. Werden mehrere Patches hintereinander ausgeführt wird das Script nur einmal ausgeführt)

  • Function PS-MypdclnEpPostExec (wird ausgeführt, nachdem ein Patch ausgeführt wird. Werden mehrere Patches hintereinander ausgeführt wird das Script nur nach dem letzten Patch ausgeführt)

  • Function PS-MypdclnEpPreReboot (wird unmittelbar vor dem Neustart ausgeführt, falls einer der installierten Patches einen Neustart angefordert hat)

  • Function PS-MypdclnEpPostReboot (wird unmittelbar nach dem Neustart ausgeführt, falls einer der installierten Patches einen Neustart angefordert hatte)

  • Function PS-MypdclnEpGrpInit (kann dem ersten System einer Patchgruppe zugeordnet werden)

  • Function PS-MypdclnEpGrpFinish (kann dem letzten System einer Patchgruppe zugeordnet werden)

  • Function PS-MypdclnEpGrpPreExec (wird ausgeführt, bevor der erste Patch eines Gruppenmitglieds ausgeführt wird. Werden mehrere Patches hintereinander ausgeführt wird das Script nur einmal ausgeführt)

  • Function PS-MypdclnEpGrpPostExec (wird ausgeführt, nachdem der letzte Patch eines Gruppenmitglieds ausgeführt wurde. Wurden mehrere Patches hintereinander ausgeführt wird das Script nur einmal ausgeführt)

  • Function PS-MypdpatEpNewPatch (wird ausgeführt, wenn irgendein Computer einen neuen Patch meldet, der bislang in der mypDeploy-DB unbekannt ist)

Parameter

Über $Args[index] können einige Funktionen auf Daten aus der mypDeploy-Datenbank zugreifen.

  • Function PS-MypdclnEpPreExec
    Args[0] enthält 1, wenn die Patches zur Installation anstehen, 0, wenn die Patches zur Deinstallation anstehen
    Args[1] enthält eine Liste der Namen der zu installierenden/deinstallierenden Patches, bei mehreren Patches werden die Namen mit dem “|”-Zeichen getrennt
    Args[2] enthält 0, wenn das Skript einem Computer zugeordnet ist, ansonsten einen Integer, das wievielte Element der Liste von Args[1] das Script ausgelöst hat, wenn das Script einem Patch zugeordnet ist

  • Function PS-MypdclnEpPostExec
    Args[0] enthält 1, wenn die Patches installiert wurden, 0, wenn Patches deinstalliert wurden
    Args[1] enthält eine Liste der Namen der zu installierenden/deinstallierenden Patches, bei mehreren Patches werden die Namen mit dem “|”-Zeichen getrennt
    Args[2] enthält 0, wenn das Skript einem Computer zugeordnet ist, ansonsten einen Integer, das wievielte Element der Liste von Args[1] das Script ausgelöst hat, wenn das Script einem Patch zugeordnet ist
    Args[3] enthält 1, wenn einer der ausgeführten Patches einen Neustart benötigt, ansonsten 0
    Args[4] enthält 1, wenn sich der Computer in einem Reboot-Zeitfenster befindet und der Reboot sofort durchgeführt werden kann, ansonsten 0
    Args[5] enthält die Anzahl der verbleibenden Sekunden bis zum nächsten Reboot-Zeitfenster, falls Args[4] 0 ist

  • Function PS-MypdclnEpPreReboot hat aktuell keine Funktionsparameter

  • Function PS-MypdclnEpPostReboot hat aktuell keine Funktionsparameter

  • Function PS-MypdclnEpGrpInit
    Args[0] enthält eine Liste der Namen der zu dieser Gruppe gehörenden Rechner; mit dem “|”-Zeichen getrennt
    Args[1] enthält den 1-basierten Index, welcher Computer in Args[0] der aktuell aktive Rechner der Gruppe ist. Da PS-MypdclnEpGrpInit immer als erstes Script einer Gruppe läuft ist der Parameter hier immer 1.
    Args[2] enthält 1, wenn beim Durchlauf der Gruppe auf dem aktuellen Computer ein Fehler aufgetreten ist, ansonsten 0. Da PS-MypdclnEpGrpInit immer als erstes Script einer Gruppe läuft ist der Parameter hier immer 0.
    Args[3] wenn beim Durchlauf der Gruppe auf irgendeinem Computer der Gruppe ein Fehler aufgetreten ist, ansonsten 0. Da PS-MypdclnEpGrpInit immer als erstes Script einer Gruppe läuft ist der Parameter hier immer 0.

  • Function PS-MypdclnEpGrpFinish
    Args[0] enthält eine Liste der Namen der zu dieser Gruppe gehörenden Rechner; mit dem “|”-Zeichen getrennt
    Args[1] enthält den 1-basierten Index, welcher Computer in Args[0] der aktuell aktive Rechner der Gruppe ist. Da PS-MypdclnEpGrpFinish immer als letztes Script einer Gruppe läuft zeigt der Parameter hier immer auf das letzte Element von Args[0].
    Args[2] enthält 1, wenn beim Durchlauf der Gruppe auf dem aktuellen Computer ein Fehler aufgetreten ist, ansonsten 0.
    Args[3] wenn beim Durchlauf der Gruppe auf irgendeinem Computer der Gruppe ein Fehler aufgetreten ist, ansonsten 0.

  • Function PS-MypdclnEpGrpPreExec
    Args[0] enthält eine Liste der Namen der zu dieser Gruppe gehörenden Rechner; mit dem “|”-Zeichen getrennt
    Args[1] enthält den 1-basierten Index, welcher Computer in Args[0] der aktuell aktive Rechner der Gruppe ist.
    Args[2] enthält 1, wenn beim Durchlauf der Gruppe auf dem aktuellen Computer ein Fehler aufgetreten ist, ansonsten 0.
    Args[3] wenn beim Durchlauf der Gruppe auf irgendeinem Computer der Gruppe ein Fehler aufgetreten ist, ansonsten 0.

  • Function PS-MypdclnEpGrpPostExec
    Args[0] enthält eine Liste der Namen der zu dieser Gruppe gehörenden Rechner; mit dem “|”-Zeichen getrennt
    Args[1] enthält den 1-basierten Index, welcher Computer in Args[0] der aktuell aktive Rechner der Gruppe ist.
    Args[2] enthält 1, wenn beim Durchlauf der Gruppe auf dem aktuellen Computer ein Fehler aufgetreten ist, ansonsten 0.
    Args[3] wenn beim Durchlauf der Gruppe auf irgendeinem Computer der Gruppe ein Fehler aufgetreten ist, ansonsten 0.

  • Function PS-MypdpatEpNewPatch
    Args[0] enthält eine Liste der Namen der neu ermittelten Patches, bei mehreren Patches werden die Namen mit dem “|”-Zeichen getrennt

Powershell-Erweiterungen

Wir haben für Sie Cmdlet-Erweiterungen bereitgestellt, die sie in Ihrem Powershell-Script benutzen können, um mypDeploy über Fehler bei der Vorbereitung zu informieren oder Informationen aus der mypDeploy-Datenbank abzufragen. Zur Erfassung und Bereitstellung von Informationen aus der mypDeploy-Datenbank finden Sie hier weitere Informationen.

CSL_ReturnValue

CSL_ReturnValue "Result","Hier könnte meine Fehlermeldung stehen"

Das Cmdlet erwartet zwei Strings als Parameter. “Result” ist fest vorgegeben, danach geben Sie einen beliebigen Text mit der Problem-Beschreibung mit.

Den übergebenen Text wird als Eintrag im mypDeploy-Protokoll des entsprechenden Rechners als Meldung vom Typ “Information” abgelegt. Die Ausführung des Patches wird im nächsten Durchlauf erneut versucht.

CSL_ReturnValue

Diese Cmdlet-Erweiterung steht nur in der Funktion PS-MypdclnEpPreExec zur Verfügung.

CSL_GetCfgValue

CSL_GetCfgValue “Value”

Das Cmdlet erwartet den Namen der Konfigurationsvariablen als Parameter. mypDeploy übergibt nur Werte vom Typ “String”; eine gegebenenfalls erforderliche Typkonvertierung muss innerhalb des Powershell-Scripts vorgenommen werden.

Das Cmdlet kann in allen Einsprungpunkten verwendet werden.

Konfigurationswerte

Diese Funktion ist erst ab mypDeploy Version 3.12.0.0 verfügbar

In den Einsprungpunkten

  • MypdclnEpGrpInit

  • MypdclnEpGrpFinish

  • MypdclnEpGrpPreExec

  • MypdclnEpGrpPostExec

können bei der Ausführung im Rahmen einer Patchgruppe die Konfigurationswerte der Patchgruppe ebenfalls mit CSL_GetCfgValue abgefragt werden. Um sie von den Konfigurationswertes der Skripte zu unterscheiden bekommen die Namen der Patchgruppen-Werte ein "PG-" vorangestellt.

Beispiel: Der Wert der Patchgruppen-Variablen "MyVariable" wird also ermittelt über CSL_GetCfgValue "PG-MyVariable"

Patchgruppen-Konfigurationswerte

Diese Funktion ist erst ab mypDeploy Version 3.20.0.0 verfügbar

Rückmeldung an mypDeploy

Sie steuern innerhalb Ihrer Powershell-Funktion, wie der mypDeployClientService die Ausführung der Patchscripte bewertet.

  • Verlassen Sie Ihre Funktion mit einem ExitCode 0 (oder wenn die Funktion normal beendet wird setzt die PS diesen implizit) verlassen, wird der mypDeployClientService die Scriptausführung als erfolgreich werten und mit der Verarbeitung fortfahren.

  • Setzen Sie in Ihrer Funktion über Exit(), Return() oder Throw'' explizit einen terminierenden Fehler innerhalb der Powershell-Funktion, wird der mypDeployClientService die Scriptausführung als fehlerhaft werten, einen Protokolleintrag erstellen und die Verarbeitung abbrechen. Im Protokolleintrag erhalten Sie entweder den via Throw'' gesetzten Fehlertext oder (wenn Sie die Funktion über Exit/Return verlassen) den Inhalt von $Error[0].
    Beispiel:
    # mypDeploy PowerShell script
    Function PS-MypdclnEpPreExec
    {
    $ErrorActionPreference = "Continue"
    Throw 'Das PreExec-Script endet immer mit einem Fehler'
    }

    erzeugt folgenden Protokolleintrag in mypDeploy:
    Aktion: Ausführungs-Fehler
    Zeit: 4.4.2022, 14:09:22
    Computer: WWVTDEMO02
    Quelle: Client
    Meldung: 14761: Das Pre-/Postpatch-Skript "MypdclnEpPreExec" hat einen Fehler gemeldet: PowerShell Initialisierungs-Fehler (Code 1510): System.Management.Automation.RuntimeException : Das PreExec-Script endet immer mit einem Fehler

Reihenfolge der Ausführung

Patchscripte werden immer in dieser Reihenfolge ausgeführt (sofern vorhanden; fehlende Einsprungspunkte werden einfach ausgelassen; Gruppenscripte werden nur ausgeführt, wenn der aktuelle Computer Mitglied einer Patchgruppe ist)

  • PS-MypdclnEpGrpInit

  • PS-MypdclnEpGrpPreExec

    • PS-MypdclnEpPreExec

    • PS-MypdclnEpPostExec

    • PS-MypdclnEpPreReboot

    • PS-MypdclnEpPostReboot

  • PS-MypdclnEpGrpPostExec

  • PS-MypdclnEpGrpFinish

Die blau markierten Einsprungspunkte werden ggf. mehrfach aufgerufen, wenn in einem Patchlauf mehrere Patches mit unterschiedlichen zugeordneten Scripten installiert werden.

Sonstige Hinweise

Beispiel

Unterhalb Ihres mypDeployServer-Verzeichnisses finden Sie im Verzeichnis “Powershell templates” ein Beispiel-Script mit den unterschiedlichen Entry-Points.

C++ Runtime

Für die Ausführung von Powershell-Patchscripten ist eine C++-Runtime auf den Systemen erforderlich.

Wenn Sie ihre Computer mit mypOsDeploy installiert haben ist diese automatisch bereits vorhanden; bei selbst installierten Betriebssystemen müssen Sie die C++-Runtime ggf. vorher installieren bzw. von mypDeploy installieren lassen.

PS-MypdpatEpNewPatch

Wird bei der Funktion PS-MypdpatEpNewPatch kein Result-Wert gesetzt, werden alle Patches der übergebenen Liste quittiert und beim nächsten Aufruf einer Funktion nicht mehr als “neu” bewertet.
Wird ein Result-Wert <> ““ gesetzt, werden alle Patches der übergebenen Liste beim nächsten Aufruf der Funktion nochmals als “neu” übergeben!

Befehlssatz

Sie dürfen grundsätzlich alle Powershell-Befehle benutzen, die die auf Ihren Systemen installierte Powershell-Version unterstützt.

Achten Sie aber darauf, dass Sie keine Neustarts/Abmeldungen erzeugen, da diese ansonsten sofort ohne weitere Ankündigung erfolgen.

Syntaxprüfung und Ausführungsfehler

Der mypDeploy-ClientService führt keine syntaktische oder semantische Prüfung der ihm übergebenen Powershell-Funktionen durch.
Auch Ausführungsfehler müssen selbst von Ihnen innerhalb der Powershell behandelt werden.
Wenn das Script einen Ausführungs- oder Syntaxfehler enthält wird dieser ins Protokoll eingetragen und die Ausführung als fehlerhaft gewertet.
Falls es sich bei dem Fehler um einen Laufzeitfehler handelt wird dieser mit in das Protokoll eingetragen.

Im folgenden Beispiel wurde innerhalb der Powerhell ein Cmdlet mit ungültigem Parameter aufgerufen; in der Protokollansicht von mypDeployAdmin erhalten Sie dann folgende Info:
Aktion: Ausführungs-Fehler Paket/Patch:
Zeit: 28.3.2022, 15:01:04
Computer: WWVTDEMO07
Quelle: Client
Meldung: Das Skript-Modul hat einen Fehler gemeldet (Code 2): PowerShell Initialisierungs-Fehler (Code 1510): System.Management.Automation.ParameterBindingException : Es wurde kein Parameter gefunden, der dem Parameternamen "File" entspricht.

Best Practice

Da die Testmöglichkeiten innerhalb von mypDeploy eingeschränkt sind und Sie nur den jeweils letzten Fehler aus der Powershell im Protokoll sehen können empfehlen wir Ihnen, Ihre Powershell-Patchscripte vorab mit PowerShell ISE oder ähnlichen Tools zu entwickeln und zu testen, bevor Sie sie in mypDeploy importieren.