Paket-Compliance-Scripte (SMC) 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-Compliance-Scripte (ScriptMipCompliance, kurz SMC) zu erstellen.
Hierüber können Sie beispielsweise in migrierten oder teilweise verwalteten Umgebungen feststellen, ob ein durch mypDeploy bereitgestelltes Paket bereits anderweitig installiert wurde.
Formaler Aufbau
Damit Ihr SMC-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-MypdclnEpTestCompliance (wird ausgeführt, bevor eine Paketinstallation/-deinstallation ausgeführt wird)
Parameter
Die Funktion verfügt über keine Parameter.
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" → das Paket ist nicht installiert
CSL_ReturnValue "Result","1" → das Paket ist installiert
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-MypdclnEpTestCompliance
{
$ErrorActionPreference = "Continue"
Throw 'Das Compliance-Script endet immer mit einem Fehler'
}erzeugt folgenden Protokolleintrag in mypDeploy:
Aktion: Ausführungs-Fehler
Zeit: 02.12.2022, 17:09:22
Computer: WWVTDEMO07
Quelle: Client
Meldung: 14761: Das Paket-Ausführungs-Skript-Skript "MypdclnEpTestCompliance" hat einen Fehler gemeldet: PowerShell Initialisierungs-Fehler (Code 1510): System.Management.Automation.RuntimeException : Das Compliance-Script endet immer mit einem Fehler.
Verzögern der Installation
Diese Erweiterung der Rückgabewerte steht erst ab Version 3.16.2.0 von mypDeploy zur Verfügung
Sie können über Ihr SMC mypDeploy auch anweisen, das Paket mit einer Verzögerung zu installieren.
CSL_ReturnValue "Result","2" → das Paket ist nicht installiert, soll aber aktuell auch nicht installiert werden.
CSL_ReturnValue "DelayMin","X" → erneuter Installationsversuch in x Minuten.
CSL_ReturnValue "DelayMsg","erneuter Versuch" → Eine Meldung, die in das Protokoll des Clients eingetragen wird.
Beispiel:
# mypDeploy PowerShell script
Function PS-MypdclnEpTestCompliance
{
$ErrorActionPreference = "Continue"
If ((Get-WmiObject -class win32_battery).EstimatedChargeRemaining -ge 50)
{
CSL_ReturnValue "Result", "0"
}
Else
{
CSL_ReturnValue "Result", "2"
CSL_ReturnValue "DelayMin", "15"
CSL_ReturnValue "DelayMsg", "Akkustand zu niedrig; erneuter Versuch in 15 Minuten"
}
}
erzeugt folgenden Protokolleintrag in mypDeploy:
Aktion: Paketstatus geändert
Paket/Patch:
Neuer Status: Nicht installiert
Zeit: 3.1.2024, 10:50:50
Computer: WWMPBN07
Benutzer: WWMPBN07
Quelle: Client
Meldung: Akkustand zu niedrig; erneuter Versuch in 15 Minuten
In diesem Beispiel wird geprüft, ob der Akku zu mindestens 50% geladen ist. Falls nicht wird die entsprechende Meldung zurück an mypDeploy gegeben. Nach der eingestellten Wartezeit wird beim nächsten Durchlauf des mypDeploy-Clients das SMC erneut ausgeführt.
Reihenfolge der Ausführung
SMC werden immer vor der Aktion ausgeführt, die Sie überwachen (Installation/Deinstallation)
Installation Software A
Software A wird zugewiesen
Das SMC für Software A führt die Funktion PS-MypdclnEpTestCompliance aus
mypDeployClientService wertet das Ergebnis des SMC aus
hat das SMC als Ergebnis “1” gemeldet, wird das Paket nicht heruntergeladen, sondern in der mypDeploy-Datenbank als “installiert” aktualisiert und ggf. noch im Cache befindliche Installationsdateien gelöscht
hat das SMC als Ergebnis “0” gemeldet, wird das Paket wie gewohnt heruntergeladen und installiert
Deinstallation Software A
Software A wird zur Deinstallation zugewiesen
Das SMC für Software A führt die Funktion PS-MypdclnEpTestCompliance aus
mypDeployClientService wertet das Ergebnis des SMC aus
hat das SMC als Ergebnis “0” gemeldet, wird das Paket nicht heruntergeladen, sondern in der mypDeploy-Datenbank als “nicht installiert” aktualisiert und ggf. noch im Cache befindliche Installationsdateien gelöscht
hat das SMC als Ergebnis “1” gemeldet, wird das Paket wie gewohnt heruntergeladen und deinstalliert
SMC registrieren
Über “Aktion/Serverseitig verwaltete Scripte” registrieren Sie Ihr SMC 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.
SMC zuordnen
Sobald Sie Ihr SMC registriert haben, können Sie es genau einem Paket zuordnen.
Wählen Sie aus den Listen das Paket aus, das das SMC prüfen soll. Es werden Ihnen nur Pakete angeboten, keine Scripte oder Scriptgruppen.
Ihre Auswahl sehen Sie anschließend in den Eigenschaften des SMC
Mehrfachzuordnung
Einem Paket kann immer nur ein SMC zugeordnet werden; sofern Sie bereits ein anderes SMC zugeordnet haben werden Ihnen bei erneuter Zuordnung die Pakete nicht mehr angezeigt.
Wenn Sie ein anderes SMC zuordnen möchten, müssen Sie zunächst über das Kontextmenü die alte Zuordnung löschen.
Sonstige Hinweise
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 diese 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.
Scriptfehler
Ein Ausführungsfehler in einem SMC wird als “nicht installiert” gewertet!
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.