Patchscripte als Powershell-Scripte erstellen

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

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"

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