Paket-Ausführungscripte (SME) als Powershell-Scripte erstellen
Dieses Feature steht erst ab Version 3.9.8.0 von mypDeploy zur Verfügung
mypDeploy bietet Ihnen ab Version 3.9.8.0 die Möglichkeit, Paket-Ausführungsscripte (ScriptMipExecute, kurz SME) zu erstellen, um für komplexe Pakete die Ausführung der Installation/Deinstallation zu überwachen oder bestimmte Aktionen während der Installation auszuführen.
Formaler Aufbau
Damit Ihr SME-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 fix vorgegebene Funktionsnamen definiert:
Function PS-MypdclnEpTestInstall (wird ausgeführt, nachdem das Paket ausgeführt wurde)
Function PS-MypdclnEpTestUnInstall (wird ausgeführt, nachdem das Paket entfernt wurde)
Parameter
Über $Args[index] können dieFunktionen auf Daten aus der mypDeploy-Datenbank zugreifen.
Function PS-MypdclnEpTestInstall
Args[0] enthält die Anzahl, wie häufig der mypDeployClientService das Script schon aufgerufen hat
Args[1] enthält 0, wenn das ausgeführte Paket keinen Reboot benötigt: 1, wenn das Paket einen Reboot benötigt (aber nicht zwingend sofort); 2, wenn das Paket einen sofortigen Reboot benötigt.
Args[2] enthält 0, wenn das Script im regulären Betrieb ausgeführt wird; 1, wenn sich der Rechner gerade im FullInstall-Modus befindet.Function PS-MypdclnEpTestUnInstall
Args[0] enthält die Anzahl, wie häufig der mypDeployClientService das Script schon aufgerufen hat
Args[1] enthält 0, wenn das deinstallierte Paket zum Abschluss keinen Reboot benötigt: 1, wenn das deinstallierte Paket zum Abschluss einen Reboot benötigt (aber nicht zwingend sofort); 2, wenn das deinstallierte Paket einen sofortigen Reboot benötigt.
Args[2] enthält 0, wenn das Script im regulären Betrieb ausgeführt wird; 1, wenn sich der Rechner gerade im FullInstall-Modus befindet.
Powershell-Erweiterungen
Wir haben für Sie eine Cmdlet-Erweiterung bereitgestellt, die sie in Ihrem Powershell-Script benutzen können, um mypDeploy über das Ergebnis Ihres Powershell-Scripts zu informieren.
CSL_ReturnValue "Result","Meldung"
Das Cmdlet erwartet zwei Strings als Parameter. “Result” ist fest vorgegeben, als zweiten Parameter tragen Sie Ihre Rückmeldung ein (s. nächster Absatz).
Rückmeldung an mypDeploy
Sie steuern innerhalb Ihrer Powershell-Funktion mit der Erweiterung “CSL_ReturnValue”, wie der mypDeployClientService die Ausführung des SME bewertet.
CSL_ReturnValue "Result","0" → die Ausführung der überwachten Installation ist noch nicht abgeschlossen, aber auch noch ohne Fehler
CSL_ReturnValue "Result","1" → die Ausführung der überwachten Installation ist erfolgreich abgeschlossen
CSL_ReturnValue "Result","2" → die Ausführung der überwachten Installation ist noch nicht abgeschlossen, der Client soll aber zunächst einen anstehenden Reboot ausführen.
CSL_ReturnValue "Result","Message" → die Ausführung der überwachten Installation ist gescheitert; in Message findet sich die Fehlerbeschreibung
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 und wertet CSL_ReturnValue aus.
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-MypdclnEpTestInstall
{
$ErrorActionPreference = "Continue"
Throw 'Das TestInstall-Script endet immer mit einem Fehler'
}erzeugt folgenden Protokolleintrag in mypDeploy:
Aktion: Ausführungs-Fehler
Zeit: 29.10.2022, 14:09:22
Computer: WWVTDEMO07
Quelle: Client
Meldung: 14761: Das Paket-Ausführungs-Skript-Skript "MypdclnEpTestInstall" hat einen Fehler gemeldet: PowerShell Initialisierungs-Fehler (Code 1510): System.Management.Automation.RuntimeException : Das TestInstall-Script endet immer mit einem Fehler
Reihenfolge der Ausführung
SME werden immer in nach der Aktion ausgeführt, die Sie überwachen
Installation Software A
Software A wird installiert
mypDeployClientService führt einen Wartezyklus seiner Hauptschleife aus
Das SME für Software A führt die Funktion PS-MypdclnEpTestInstall aus
mypDeployClientService wertet das Ergebnis des SME aus
hat das SME einen Neustart angefordert, wird dieser im nächst möglichen Neustartfenster ausgeführt.
Die Schritte 2-5 werden solange wiederholt, bis
das SME Erfolg, Misserfolg oder einen Fehler meldet
die maximale Laufzeit des SME erreicht ist. Dies wird als fehlerhafte Installation gewertet und mit einer entsprechenden Meldung in die mypDeploy-Datenbank eingetragen.
Deinstallation Software A
Software A wird deinstalliert
mypDeployClientService führt einen Wartezyklus seiner Hauptschleife aus
Das SME für Software A führt die Funktion PS-MypdclnEpTestUnInstall aus
mypDeployClientService wertet das Ergebnis des SME aus
hat das SME einen Neustart angefordert, wird dieser im nächst möglichen Neustartfenster ausgeführt.
Die Schritte 2-5 werden solange wiederholt, bis
das SME Erfolg, Misserfolg oder einen Fehler meldet
die maximale Laufzeit des SME erreicht ist. Dies wird als fehlerhafte Deinstallation gewertet und mit einer entsprechenden Meldung in die mypDeploy-Datenbank eingetragen.
SME registrieren
Über “Aktion/Serverseitig verwaltete Scripte” registrieren Sie Ihr SME in der mypDeploy-Datenbank.
Wählen Sie Ihr Script aus
Der Name wird Ihnen aus dem Scriptnamen vorgeschlagen.
Eine optionale Beschreibung kann mit Erläuterungen gefüllt werden.
In der maximalen Laufzeit legen Sie fest, wie lange Ihr SME maximal ausgeführt werden darf (ist bis dahin kein Ergebnis oder Fhler geliefert worden wird die Installation/Deinstallation als fehlerhaft abgebrochen)
SME zuordnen
Sobald Sie Ihr SME registriert haben, können Sie es
einer oder mehreren Scriptgruppen
einem oder mehreren Scripten
einem oder mehreren Paketen
zuordnen.
Wählen Sie aus den Listen die entsprechenden Gruppen/Scripte/Pakete aus
Ihre Auswahl sehen Sie anschließend in den Eigenschaften des SME
Mehrfachzuordnung
Einem Paket kann immer nur ein SME zugeordnet werden; sofern Sie schon Zuordnungen auf Scriptgruppen- oder Scriptgruppen getroffen haben werden Ihnen bei erneuter Zuordnung die zugehörigen Pakete und Gruppen nicht mehr angezeigt.
Sonstige Hinweise
Ablaufsteuerung
Bitte beachten Sie, das während der Ausführung eines SME keine weiteren Pakete, Patches, ClickToRun-Updates usw. ausgeführt werden. Das SME wird solange ausgeführt, bis es ein Ergebnis liefert oder die Zeit abgelaufen ist; erst danach werden weitere ausstehende Aktionen ausgeführt.
C++ Runtime
Für die Ausführung von Powershell-Patchscripten ist eine C++-Runtime 2010 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.
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 Powershell ein Cmdlet mit ungültigem Parameter aufgerufen; in der Protokollansicht von mypDeployAdmin erhalten Sie dann folgende Info:
Aktion: Ausführungs-Fehler Paket/Patch:
Zeit: 30.11.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.