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 istFunction 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 istFunction 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.