Clientscripte als Powershell-Scripte erstellen

Owned by Onlinehilfe CebiCon
13.März.2024
4 min read

Mit Hilfe von Clientscripten können Sie benutzerdefinierte Werte setzen, die Sie dann in mypDeploy für Filter, automatische Zuordnungen und ähnliches nutzen können.

Diese Scripte wurden Ihnen bisher nur von der CebiCon GmbH zur Verfügung gestellt und konnten nicht bearbeitet werden.

Ab Version 3.9.8.0 von mypDeploy können Sie selber benutzerdefinierte Werte mit Powershell-Scripten setzen.

Main.csl

Sollten Sie aus älteren Versionen von mypDeploy noch ein Script “Main.csl” in Ihrem Verzeichnis der Clientscripte haben, so löschen Sie dieses bitte. Der Inhalt ist veraltet; ein neues Script wird automatisch beim Hochladen generiert; allerdings nur, wenn das Script vorher nicht vorhanden ist.

Formaler Aufbau

Damit Ihr Clientscript als Powershell-Script erkannt wird, muss es mit dieser Powershell-Kommentarzeile beginnen:

# mypDeploy PowerShell Script

Danach können Sie mit beliebigem Powershell-Code fortfahren.

Einstiegs-Funktion

Jedes von Ihnen erstellte Powershell-Script muss einen Einstiegspunkte mit fix vorgegebenem Funktionsnamen definieren:

  • Function PS-GetClientProperties

Parameter

Im Gegensatz zu anderen mypDeploy-Scripten verfügen Clientscripte nicht über Parameter.

Powershell-Erweiterungen

Wir haben für Sie eine Cmdlet-Erweiterung bereitgestellt, die Sie in Ihrem Powershell-Script benutzen können, um mypDeploy Namen, Inhalt und Datentyp einer Clienteigenschaft zu übergeben.

Generelle Syntax:

CSL_ReturnValue "<PropertyName>","PropertyValue”,”PropertyType”

PropertyName und PropertyValue müssen angegeben werden; PropertyType ist ein optionaler Parameter.

  • In “PropertyName” definieren Sie den Namen/Bezeichnung Ihrer Clienteigenschaft.

  • In PropertyValue” tragen Sie den Wert ein, den Sie dieser Clienteigenschaft zuweisen möchten.

  • In PropertyType können Sie festlegen, welchen Datentyp die Eigenschaft hat.
    Zulässige Werte:

    • Bool (True/False)

    • Integer (beliebige Ganzzahl)

    • Date (in der Form TT.MM.JJJJ)

    • Time (in der Form HH:MM:SS)

    • DateTime (in der Form TT.MM.JJJJ, HH:MM:SS)

    • Version (in der Form W.X.Y.Z)

    • IpAddress (in der Form xxx.xxx.xxx.xxx)

    • IpAddressV6 (in der Form a:b:c:d:e:f:g:h)

Wird kein Parameter PropertyType mitgegeben, wird der Inhalt als Text behandelt.

Beispiele:

CSL_ReturnValue “neue_Texteigenschaft”, ”eine neue Clienteigenschaft”

CSL_ReturnValue “neue_Datumseigenschaft”, ”01.01.1990”, “Date”

CSL_ReturnValue “neue_DateTime_Eigenschaft”, ”01.01.2000, 12:00:00”, “DateTime”

Zeichensatz

Der PropertyName darf nur alphanumerische Zeichen (Groß-/Kleinschreibung) und “_” enthalten; Sonderzeichen sind im Namen nicht zulässig.

Rückmeldung an mypDeploy

Das Setzen der Clienteigenschaften erfolgt über die o.g. Erweiterung.

Mehrfach-Eigenschaften

Ein Powershell-Clientscript darf auch mehr als eine Eigenschaft setzen.

Hierzu kann CSL_ReturnValue mehrfach innerhalb des Scripts aufgerufen werden; es müssen dann nur für “PropertyName” immer unterschiedliche Bezeichner verwendet werden.

Function PS-GetClientProperties ()
{
$Result = Get-ComputerInfo OsName,WindowsEditionId,OsVersion,OSDisplayVersion,OsBuildNumber,OsHardwareAbstractionLayer,WindowsVersion
CSL_ReturnValue "OS_Version", $($Result.OsName + ' ' + $Result.OSDisplayVersion + ' ' + $Result.OsBuildNumber)
CSL_ReturnValue "OS_Edition", $Result.WindowsEditionId
CSL_ReturnValue "OS_Build", $Result.OsBuildNumber, "Integer"

Dieses Script setzt die Texteigenschaften “OS_Version” und “OS_Edition” und die Eigenschaft “OS_Build” als Ganzzahl.

Sie steuern innerhalb Ihrer Powershell-Funktion, wie der mypDeployClientService die Ausführung der Clientscripte 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 in der Datei “ClientProperties.log” im temporären Systemverzeichnis (i.d.R. c:\windows\temp) erstellen und die Verarbeitung fortsetzen. Im Protokolleintrag erhalten Sie entweder den via Throw'' gesetzten Fehlertext oder (wenn Sie die Funktion über Exit/Return verlassen) den Inhalt von $Error[0].

Fehlerbehandlung

Sofern eines der Clientscripte mit einem Fehler beendet wird, werden für diesen Durchlauf der Hauptschleife des mypDeploy-Clients keine Eigenschaften an die mypDeploy-Datenbank übermittelt!

Typ-Prüfung

Wenn Sie im Parameter “PropertyType” einen Typ angeben liegt es in der Verantwortung des von Ihnen erstellten Scripts, dort einen gültig formatierten Wert zu übergeben.

Nach Verlassen der Funktion werden die Daten vom mypDeployClientService überprüft; ein ungültiger Typ oder ein nicht zur Typdefinition passender Inhalt wird als fehlerhafte Ausführung des Scripts gewertet.

Laden von Clientscripten

Über “Aktion/Serverseitig verwaltete Scripte” können Sie Ihre Clientscripte speichern, ändern und wieder laden.

Wählen Sie für das Herunterladen/Hochladen jeweils ein Verzeichnis aus.

Clientscripte werden immer in Gänze exportiert und importiert; alle bereits in der Datenbank gespeicherten Scripte werden hierbei überschrieben. Wenn Sie ein einzelnes Script ändern wollen, laden Sie zunächst die Scripte in ein Verzeichnis, führen dort die Änderungen durch und laden anschließend das Verzeichnis wieder hoch.

Beim Hochladen aus einem Verzeichnis findet eine formale Prüfung der Scripte statt. Falls eines der Scripte den Formalen Kriterien nicht genügt erhalten Sie einen entsprechenden Fehlermeldung mit einem Hinweis, wie der Fehler zu korrigieren ist. Im folgenden Beispiel fehlt dem Powershell-Script der erforderliche Einsprungspunkt:

Best Practice

Sammeln Sie alle von uns bereitgestellten und von Ihnen selber erstellten Scripte in einem separaten Verzeichnis und nehmen Änderungen nur dort vor.

So stellen Sie sicher, beim Laden von Clientscripten immer einen konsistenten Stand aller benötigten Scripte zu laden.

Sonstige Hinweise

C++ Runtime

Für die Ausführung von Powershell-Patchscripten ist eine C++-Runtime 2010 x86 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-Funktion 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 auf dem ausführenden System im Windows-Temp-Verzeichnis ins Protokoll “ClientProperties.log” 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 einer nicht deklarierten Funktion ausgerufen; im Protokoll erhalten Sie dann folgende Info:
>>> Fehler
Bei der Ausführung des Skriptes ist Fehler 14761 aufgetreten:
Fehler in Zeile 4 der Datei "c:\Program Files (x86)\mypackage\mypDeployClient_ClientScripts\SystemLocale.csl" bei "CallIntScript ("mypDeployPsStub", "PS-GetClientProperties")":
Das Skript-Modul hat einen Fehler gemeldet (Code 2): PowerShell Initialisierungs-Fehler (Code 1510): System.Management.Automation.CommandNotFoundException : Die Benennung "Invalid-Function" wurde nicht als Name eines Cmdlet, einer Funktion, einer Skriptdatei oder eines ausführbaren Programms erkannt. Überprüfen Sie die Schreibweise des Namens, oder ob der Pfad korrekt ist (sofern enthalten) und wiederholen Sie den Vorgang.

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-Clientscripte vorab mit PowerShell ISE oder ähnlichen Tools zu entwickeln und zu testen, bevor Sie sie in mypDeploy importieren.