PowerShell-Skript ausführen

WMS 1.0.1 (2020)

PowerShell-Aktivität mit Angabe einer Datei

ab 2.1.0 mit Angabe von Parametern

Die Aktivität führt ein beliebiges von Ihnen entwickelte PowerShell-Skript aus einer Datei aus.

WMS 2.1.0
Mit einer überarbeiteten Version kann das PowerShell-Skript jetzt direkt angegeben werden. Ebenso können Parameter definiert und dem Skript übergeben werden.

Inhalt

1 Hinweise und Hilfe
2 Eigenschaften
- 2.1 Eingabe
- 2.2 Ausgabe
3 Parameter
4 Ergebnis (PSObject)
- 4.1 Beispiel 1: String-Werte
- 4.2 Beispiel 2: Komplexe Ergebnistypen (z.B. von einem Web-Request)
5 Informationen

Hinweise und Hilfe

Beachten Sie, dass das WMS das Skript weder verarbeitet noch auswertet oder prüft. Somit erfolgt auch keine Prüfung der Mandantenverzeichnisse.

Die Accantum GmbH übernimmt keine Verantwortung für Schäden, welche durch die Ausführung von Skripten verursacht werden. Das WMS hat keinen Einfluss auf die Skripten und kann deren Inhalt nicht prüfen. Mit einem PowerShell-Skript können sicherheitsrelevante Einschränkungen umgangen und somit nicht gewollte, schädliche Aktionen auf dem Server ausgeführt werden.

Informationen zur sicheren Verwendung von PowerShell-Skripts finden Sie auf den Seiten von Microsoft:
Weitere Informationen zur sicheren Verwendung von PowerShell-Skripts - Configuration Manager

Viele weitere Beispiele und Anleitungen zur Anwendung von PowerShell-Skripten finden Sie ebenfalls auf den Seiten von Microsoft:
PowerShell-Dokumentation - PowerShell

Eigenschaften

Eingabe

Name	Beschreibung	Datentyp	Erforderlich

Name	Beschreibung	Datentyp
Dateiname	Name der Datei, die das Skript enthält.	string
Verzeichnis	Verzeichnis, in dem die Datei liegt	string
Ressource	Resourcedatei, die das Skript enthält, siehe dazu Ressourcen Einstellungen und Zuordnungen	WmsSettingMapping
Ressource verwenden	Kennzeichen, ob eine Ressourcen verwendet werden soll, statt eines Dateinamens	bool
Auswahl “von Datei / per Text”	Mit der Auswahl kann festgelegt werden, ob das Skript von einer Datei geladen oder ob das Skript direkt als Text angegeben werden soll.
Text WMS 2.1.0	Alternativ zur Angabe einer PowerShell-Skript-Datei können Sie PowerShell-Befehle direkt in das Textfeld eingegeben. Bei Klick auf die Schaltfläche mit dem Stift-Symbol, öffnet sich ein Fenster, in dem das Skript in einem größeren Fenster und mit Syntax-Highlighting editiert werden kann.	string
Parameter definieren… WMS 2.1.0	Beim Klick auf die Schaltfläche öffnet sich ein Fenster, in dem Parameter definiert werden können, auf die bei der Ausführung des PowerShell-Skripts zugegriffen werden kann. Die Namen der Parameter enthalten kein “$”-Zeichen und müssen mit denen im Skript übereinstimmen.	Auflistung
Script bei Fehler abbrechen WMS 2.1.0	Wenn Kennzeichen gesetzt ist, dann wird die Ausführung des Skripts unterbrochen, sobald ein Fehler mit “write-error” protokolliert wird.

Ausgabe

Name	Beschreibung	Datentyp	Erforderlich

Name

Beschreibung

Datentyp

Erforderlich

Ergebnis

Das Ergebnis der Ausführung des Skripts. Leer, wenn das Skript kein Ergebnis liefert.

List<PSObject>

Informationen
WMS 2.1.0

Meldungen, welche während der Ausführung des PowerShell-Skripts ausgegeben wurden.

Im Skript können die Meldungen mit den Aufrufen von write-error, write-warning, write-information, etc. protokolliert werden.

List<WmsPowerShellMessageItem>

Parameter

Ab WMS 2.1.0 können Sie in der Aktivität Parameter definieren. Mit Klick auf die Schaltfläche “Parameter definieren…“ öffnet sich ein Fenster, in dem eine Liste von Parametern angelegt werden kann. Als Werte können beliebige Objekte verwendet werden.

Um im PowerShell-Skript auf die Parameter zugreifen zu können, müssen diese im Skript wie folgt definiert werden:

param( [string]$ParamString,
         [Int]$ParamInt,
         [double]$ParamDouble,
         [datetime]$ParamDateTime)

Innerhalb von param(…) müssen die Parameter in einer Komma separierten Liste angegeben werden. Dabei ist vor dem Namen des Parameters das Zeichen “$” zu setzen (z.B. lautet für Parametername “ParamString” die Variable “$ParamString”).

Optional kann vor dem Variablennamen in eckigen Klammern der Datentyp angegeben werden (z.B. [string]$ParamString). Wir empfehlen dies, weil dadurch eine Differenz des Datentyps bei einem übergebenen Wert sofort zu einem Fehler führt und somit ein ungewolltes Verhalten bei der Ausführung des Skripts vermieden werden kann.

Ergebnis (PSObject)

Beispiel 1: String-Werte

Das Ergebnis der Aktivität ist eine Liste der Ausgaben aus dem Powershell-Script. Mittels ToString können sie den Wert aus dem PSObject ermitteln.

In folgenden Beispiel enthält die Liste zwei Werte:

Beispiel 2: Komplexe Ergebnistypen (z.B. von einem Web-Request)

Handelt es sich bei einer Rückgabe um einen komplexeren Typ, können dessen Eigenschaften über die Namen abgerufen werden.

Powershell-Skript:

$obj =  [PSCustomObject]@{
    Name     = 'MyName'
    Description = 'MyDescription'
    State    = 'ok'
}

Im Workflow:

psObject.Properties.Item("Description").Value.ToString()

Der Value der Eigenschaft ist dabei vom Typ "object". d.h. um damit weiter arbeiten zu können müssen Sie den Typ kennen und konvertieren.

Informationen

Die Aktivität gibt eine Liste von Informationen aus, welche im PowerShell-Skript protokolliert werden. Je nach Befehl im PowerShell-Skript können diese Informationen als Fehler, Warnung oder Information spezifiziert werden:

write-error
write-warning
write-information bzw. write-host