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

  1. Software A wird installiert

  2. mypDeployClientService führt einen Wartezyklus seiner Hauptschleife aus

  3. Das SME für Software A führt die Funktion PS-MypdclnEpTestInstall aus

  4. mypDeployClientService wertet das Ergebnis des SME aus

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

  1. Software A wird deinstalliert

  2. mypDeployClientService führt einen Wartezyklus seiner Hauptschleife aus

  3. Das SME für Software A führt die Funktion PS-MypdclnEpTestUnInstall aus

  4. mypDeployClientService wertet das Ergebnis des SME aus

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