PowerShell Parameter grafische Darstellung ScriptRunner

PowerShell Parameter und ihre grafische Darstellung in ScriptRunner

Eine sehr wichtige und kundenfreundliche Funktionalität von ScriptRunner ist die grafische Oberfläche für die Eingabe von PowerShell Parametern in der Admin und Delegate App. Die Anforderung für eine einfach bedienbare Eingabe entsteht ausnahmslos bei allen Kunden aus den Erfordernissen im praktischen IT-Betrieb. Mit den PowerShell Scripten werden vielfältige Geschäftslogiken für Automatisierung und Delegation abgebildet. Die Anwendung der Scripte soll jedoch nicht auf der Kommandozeile, sondern über eine verständliche grafische Oberfläche erfolgen. Dieser Beitrag zeigt Ihnen, wie Sie PowerShell Parameter in den Eingabeformularen verwenden und wie Sie diese gestalten können. Wenn Sie diese Hinweise berücksichtigen, erhalten Sie als Lohn den Dank Ihrer Anwender!

Das Grundprinzip der grafischen Darstellung für Eingabe-Parameter

Mit PowerShell Bordmitteln

Für das Problem einer grafischen Darstellung bietet PowerShell von Haus aus keine zufriedenstellende Lösung an. Als „Hausmittel“ gibt es die Möglichkeit, WPF Formulare zu codieren oder umfangreichen XAML-Code zu verwenden. Die Praxis hat jedoch gezeigt, dass diese Variante mit vielen Nachteilen behaftet ist:

  1. In der Konsequenz entsteht am Ende für jedes Script ein separates Miniprogramm (meist eine kompilierte EXE). Diese Miniprogramme unterscheiden sich in ihren Anforderungen zur Ausführung nicht von einem Script. Der Ausführende muss PowerShell ausführen dürfen und er muss in dem Rechtekontext arbeiten, der zur Scriptausführung notwendig ist.
  2. Die Miniprogramme müssen zum Anwender verteilt werden. Das kann mit Softwareverteilungssystemen erfolgen, was komplexe, einzuhaltende Prozeduren nach sich zieht. Wer stattdessen einmal mit dem Browser auf ein Script zugegriffen und es von dort gestartet hat, will das nicht mehr missen.
  3. Die Delegation einer Aufgabe mit sauberer Auftrennung der Rechte ist so nicht möglich. Welcher sicherheitsbewusste Administrator und Verantwortliche möchte im Service Desk oder bei den Endanwendern lauter PowerShell Administratoren tätig werden sehen?
  4. WPF und insbesondere XAML-Code im Skript führen zu einem unübersichtlichen, gemischten „Monstercode“. Viele Administratoren können und wollen derartigen Code weder schreiben noch pflegen oder weiterentwickeln. Zudem sind solche Lösungen aus Erfahrungen in der PowerShell Community enorm fehleranfällig.
  5. Bei jeder Änderung am Script ist der „grafische Overhead“ mitzutesten. Damit büßt man schnell Agilität ein und die Qualitätssicherung wird viel aufwändiger als nötig.

Mit ScriptRunner

Die ScriptRunner Admin und Delegate App wurden speziell für Administratoren und Service Desk Mitarbeiter konzipiert, die PowerShell Scripte im täglichen IT-Betrieb mit einer grafischen Oberfläche anwenden wollen.

Im Mittelpunkt des Designs und der Entwicklung standen dabei folgende Eigenschaften:

  • Automatisches Generieren von grafischen Eingabeformularen aus den PowerShell Scripten selbst, ohne Codieren, ohne Zuordnungen konfigurieren zu müssen und mit automatischer Anpassung bei Scriptänderungen
  • Automatisches Zuweisen typischer und bekannter Darstellungsmöglichkeiten wie Felder, Schalter, unterschiedliche Drop-Down-Menüs, Datums- und Zeitanzeigen usw. auf die unterschiedlichen Parametertypen
  • Automatisches Anwenden von zusätzlichen Validierungsoptionen von erweiterten Typdeklarationen
  • Automatisches Anzeigen von Feldbeschreibungen und Hinweisen zur Verwendung des Scriptes
  • Dynamisches Auswählen und Suchen nach Eingabewerten für die PowerShell Parameter unter Verwendung von Queries, auch mit kaskadierter Logik
  • Anzeigen von IST-Werten unter Verwendung von Queries. So können Sie im Formular bspw. Eigenschaften eines Benutzers im AD so angezeigt werden, wie Sie es gewohnt sind. Sie können diese Werte direkt im Formular überschreiben und ändern.
  • Eingabe-Parameter eines Scriptes können für die Ausführung bereits vorbelegt werden. Die Vorbelegung kann änderbar oder auch nicht änderbar (also fix) sein.
  • Das erzeugte Eingabeformular soll auch bei vielen Eingabe-Parametern möglichst übersichtlich bleiben
  • Starten des Scriptes nach dem Ausfüllen des Formulars
  • Rückmelden des Ergebnisses und Einsehen des generierten Reports
  • Einfaches Anzeigen und Anwenden der Formulare und Funktionen in allen gängigen Browsern (IE11, Edge, Chrome, Firefox, Opera)

Um diese hilfreichen Funktionen abbilden zu können, arbeitet ScriptRunner vereinfacht nach den folgenden Prinzipien:

  • Alle Scripte im Script Repository werden regelmäßig im Hintergrund auf Änderungen geprüft und geparst. Fehlerhafte Scripte werden in der Admin App in der Liste der Scripte, Queries und Aktionen gekennzeichnet.
  • Beim Parsen werden zu jedem PowerShell Script Metadaten auf dem ScriptRunner Host erzeugt. Diese enthalten alle Informationen zum Script Header und zur Parameterdeklaration. Änderungen am Script führen auch zu Änderungen an den Metadaten.
  • Einige Metadaten, wie die Liste der Parameter im param-Block sowie die Beschreibungen aus dem Script Header werden auf den entsprechenden Wizardseiten angezeigt. Die Synopsis bzw. die Beschreibungen aus dem Header werden automatisch in die Beschreibung für das Script und der Aktion übernommen. Sie können dort geändert oder entfernt werden. Ein Rückschreiben von Änderungen in das Script erfolgt nicht.
  • ScriptRunner definiert verschiedene Darstellungsobjekte und Darstellungsoptionen. Diese stellen die Basis für die Formulargenerierung bereit.
  • Beim Erstellen, Aufrufen oder Ändern einer Aktion in der Admin oder Delegate App werden die Darstellungsfunktionen von ScriptRunner mit den Metadaten des Scriptes zur Laufzeit zusammengeführt, das Formular generiert und angezeigt. Durch die Echtzeitgenerierung ist gewährleistet, dass immer ein aktuelles, zum Script passendes Formular generiert und angezeigt wird. Es ist deshalb auch nicht notwendig, Zuordnungen von Parametern zu Feldern vorzunehmen. Es werden auch keine „fertigen“ Formulare abgespeichert.
  • Die Formulardarstellung unterscheidet zwei Modi mit teilweise unterschiedlichem Verhalten im Detail. Der EDIT-Mode einer Aktion dient der Konfiguration derselben. Es werden nicht alle erweiterten Darstellungsoptionen angewendet. Im RUN-Mode einer Aktion hingegen werden alle erweiterten Darstellungsoptionen für das Formular verwendet.
ScriptRunner erzeugt automatisch Eingabeformulare für PowerShell Parameter

ScriptRunner erzeugt automatisch Eingabeformulare für PowerShell Parameter

Aus diesen Grundprinzipien leiten sich auch einige Gegebenheiten und Best Practices für die Scriptentwicklung ab:

  • Es ist unbedingt ein Script Header und ein Param-block für die Eingabe-Parameter im Script zu verwenden. Dieser sollte die Beschreibung und Hinweise zur Verwendung des Scriptes und einzelnen Eingabe-Parameter enthalten.
  • Unbedingt erforderliche Parameter werden im Param-block zuerst definiert. Dadurch werden sie automatisch im Eingabeformular in der Reihenfolge zuerst angezeigt.
  • In der Admin App wird pro Eingabe-Parameter ein entsprechendes Formularfeld mit Variablenname und Beschreibung angezeigt.
  • In der Delegate App wird pro Eingabe-Parameter ein entsprechendes Formularfeld mit Beschreibung angezeigt. Bei fehlender Beschreibung wird stattdessen der sonst nicht sichtbare Variablenname dargestellt.
  • Zur Verwendung verschiedener Darstellungsoptionen für die Eingabemaske als auch für die Validierung von Eingaben sollten erweiterte Parameter- und Typdeklarationen verwendet werden.
  • Fest vorbelegte Eingabe-Parameter werden im RUN-Mode aus dem Formular ausgeblendet, da der Anwender keine Änderungen daran vornehmen kann.
  • Um auch für komplexe Scripte mit vielen, aber nicht immer notwendigen Eingabe-Parametern, ein übersichtliches Eingabeformular zu erzeugen, sollten nicht verwendete Parameter über die feste Vorbelegung mit einem leeren Wert ausgeblendet werden.

Darstellung von PowerShell Datentypen in ScriptRunner

PowerShell unterstützt von Haus aus Datentypen für Parameter. Die weithin übliche Eingabe von Input-Parametern auf der Kommandozeile erfolgt auf dem Typbasis String. PowerShell kann den Eingabe-Typ String in unterschiedliche andere Typen in Abhängigkeit des deklarierten Script-Parameters konvertieren. Wird kein Typ deklariert, konvertiert PowerShell in Abhängigkeit der Notation in ein passendes Format.

Best Practice: Nutzen Sie die Deklaration von Datentypen in PowerShell, da die typfreie Konvertierung häufig auch Ursache für Verarbeitungsprobleme im Script und den Cmdlets ist.

Die generische Darstellung in den ScriptRunner Apps unterstützt und prüft auf gültige Wertebereiche für folgende Datentypen:

  • alle String-Typen
  • Number-Typen: byte, sbyte, short, ushort, int, uint, long, ulong, Int16, UInt16, Int32, UInt32, Int64, UInt64, System.Int16, System.UInt16, System.Int32, System.UInt32, System.Int64, System.UInt64; prüft diese auf gültige Zahlen- und Zahlenbereichseingabe
  • Boolean-Typen: switch
  • Array-Typen: String-Arrays und Number-Typen-Arrays
  • Credentials: PSCredential, securestring
  • Datum/Zeit-Typen: DateTime, TimeSpan

ScriptRunner bildet die genannten Datentypen im generischen Browserinterface der Admin App und der Delegate App ab. Die Art der Darstellung in der Admin App hängt auch davon ab, ob eine Aktion konfiguriert (EDIT-Mode) oder gestartet (RUN-Mode) werden soll.

PowerShell Datentyp

Darstellung in der Admin App

Darstellung in der Delegate App

String-Typen

Texteingabefeld

Texteingabefeld

Number-Typen

Texteingabefeld mit Prüfung auf Zahlentyp und Wertebereich

Texteingabefeld mit Prüfung auf Zahlentyp und Wertebereich

Array-Typen

Texteingabefeld für mehrere Werte mit Trennzeichen

Texteingabefeld für mehrere Werte mit Trennzeichen

[switch]

Auswahlhäckchen

Auswahlhäckchen

[DateTime]

DatePicker

Not implemented yet

DatePicker

Not implemented yet

[TimeSpan]

Not implemented yet

Not implemented yet

[PSCredential]

Dropdown-Auswahl in ScriptRunner oder einem Passwortstore hinterlegte Credentials

Dropdown-Auswahl in ScriptRunner oder einem Passwortstore hinterlegte Credentials

[securestring]

Texteingabefeld umschaltbar Klartextanzeige, verdeckte Anzeige

Not implemented yet

Texteingabefeld umschaltbar Klartextanzeige, verdeckte Anzeige

Not implemented yet

Darstellung mit erweiterten PowerShell Parameter-Deklarationen

Neben der reinen Datentyp-Deklaration erlaubt PowerShell eine erweiterte Parameter-Deklaration. Diese dient vor allem Validierungsfunktionen für die Eingabe und deren Reihenfolge. ScriptRunner unterstützt die in der Tabelle aufgeführten Deklarationen. Daraus ergeben sich folgende Vorteile:

  1. Es gibt verschiedene, erweiterte Darstellungsoptionen für die Eingaben. So sind zusätzlich einfache Dropdown-Menüs, Dropdown-Menüs mit Mehrfachauswahl, Auswahlhäckchen, DatePicker etc. möglich.
  2. Erweiterte Eingabeprüfung bereits im Eingabeformular und vor dem Starten des Scriptes. Erst nach valider Eingabe kann das Script gestartet werden.
  3. Erzwungene Eingaben für definierte Parameter sind mit einem roten Rahmen gekennzeichnet. Erst nach gültigen Auswahl oder Eingabe kann das Script gestartet werden.
  4. Unterbindet Fehleingaben und Fehlausführung eines Scriptes.

Die Darstellungsmöglichkeiten in der Admin App richten sich nach deren Modus.

PowerShell Deklaration

Admin App im EDIT Mode

Admin App im RUN Mode und Delegate App

Generell auch ohne erweiterte Deklaration

Der Parameter kann mit einem Wert vorbelegt werden. Die Eingabe wird auf einen gültigen Wertebereich in Abhängigkeit des Datentyps geprüft. Der Wert kann vom Anwender geändert werden oder ist fest zugeordnet.

Die Eingabe wird auf einen gültigen Wertebereich in Abhängigkeit des Datentyps geprüft. Das Eingabefeld fest vorbelegter Parameter wird ausgeblendet.

[Parameter (Mandatory=$true)]

Das Eingabefeld wird mit einem grauen Hinweiszeichen versehen. Der Parameter kann mit einem Wert vorbelegt werden.

Das Eingabefeld wird rot umrandet und mit einem roten Hinweiszeichen versehen. Ohne gültige Eingabe oder Auswahl kann das Script nicht gestartet werden.

[Parameter (Position=n)]

Das Eingabefeld wird in der Anzeige-Reihenfolge an n-ter Stelle positioniert.

Das Eingabefeld wird in der Anzeige-Reihenfolge an n-ter Stelle positioniert.

[ValidateRange(min,max)]

Das Eingabefeld prüft Eingaben auf die Einhaltung des angegebenen Minimal- und Maximalwertes.

Bei falscher Eingabe wird das Eingabefeld mit einem roten Rahmen markiert und das Script kann nicht gestartet werden.

Das Eingabefeld prüft Eingaben auf die Einhaltung des angegebenen Minimal- und Maximalwertes.

Bei falscher Eingabe wird das Eingabefeld mit einem roten Rahmen markiert und das Script kann nicht gestartet werden.

[ValidateLenght(min,max)]

Das Eingabefeld prüft Eingaben auf die Einhaltung des angegebenen Minimal- und Maximalwertes für die Zeichenlänge.

Bei falscher Eingabe wird das Eingabefeld mit einem roten Rahmen markiert und das Script kann nicht gestartet werden.

Das Eingabefeld prüft Eingaben auf die Einhaltung des angegebenen Minimal- und Maximalwertes für die Zeichenlänge.

Bei falscher Eingabe wird das Eingabefeld mit einem roten Rahmen markiert und das Script kann nicht gestartet werden.

[ValidateSet(‚a‘,’b‘,’c‘)]

Das Eingabefeld erscheint als dropdown-Menü mit den Werten a, b und c. In Kombination mit Array-Typen wird ein dropdown mit Mehrfachauswahl angezeigt.
Bei falscher Eingabe wird das Eingabefeld mit einem roten Rahmen markiert und das Script kann nicht gestartet werden.

Das Eingabefeld erscheint als dropdown-Menü mit den Werten a, b und c. In Kombination mit Array-Typen wird ein dropdown mit Mehrfachauswahl angezeigt.

Bei falscher Eingabe wird das Eingabefeld mit einem roten Rahmen markiert und das Script kann nicht gestartet werden.

Ein Beispiel:

Die Anwendung dieses Script Headers führt im automatisch generierten Formular zur Darstellung der unterschiedlichen Formulareigenschaften.

Im EDIT-Mode der ScriptRunner Admin App wird bereits die Reihenfolge und eine etwaige Vorbelegung der Werte im Script selbst geprüft. Eine Überprüfung auf „mandatory“ ist in diesem Modus nicht sinnvoll und deshalb nicht möglich.

Es können nun per Konfiguration alle Werte manuell oder mittels dropdown etc. vorbelegt werden. Vorbelegte Werte erscheinen direkt im Eingabeformular im RUN Mode, können jedoch vom Anwender noch geändert werden. Wird am Parameter die Option ‚cannot be changed at script runtime‘ gesetzt, so wird der Vorgabewert als fester Wert verwendet. Das Formular im RUN Mode wird in der Anzeige um diesen Parameter verkürzt. Dem liegt das Prinzip zugrunde, dass nicht änderbare Werte auch nicht mehr angezeigt werden sollten. Der Anwender konzentriert sich in dem Fall komplett auf die noch offenen Eingabefelder.

Die Darstellung und Auswahl des Datentyps [PSCredential] ist ausschließlich im EDIT Mode möglich.

Parameterdarstellung in der Admin App im EDIT Mode

Parameterdarstellung in der Admin App im EDIT Mode

Der RUN Mode der Admin App dient zum Testen der Einstellungen und der Scriptausführung. Aus diesem Grunde verhalten sich die Eingabefelder in diesem Modus analog zur Delegate App. In diesem Modus erfolgt zuerst die Überprüfung auf „mandatory“. Diese Felder werden rot umrahmt und mit einem Ausrufezeichen versehen, sofern sie noch leer sind, also kein Wert eingetragen wurde. Anschließend erfolgt pro Feld bei der Eingabe eine entsprechende Validierung. Hinweise zur Validierung werden direkt im Eingabefeld angezeigt, wenn dieses leer ist.

Werden ungültige Werte eingegeben bzw. stellt der Validierungs-Algorithmus einen Fehler fest, wird das entsprechende Feld rot umrahmt.

Fehlende oder fehlerhafte Eingaben führen auch dazu, dass das Script nicht gestartet werden kann. Der entsprechende Ok- bzw. Run-Button ist inaktiv. Das verhindert das Starten von Scripten mit falschen oder unerlaubten Eingabewerten, welche zu einem Fehler in der Ausführung führen würden.

Im RUN Mode der Admin App erfolgen alle Validierungen - PowerShell Parameter

Im RUN Mode der Admin App erfolgen alle Validierungen

Die Darstellung und die Validierungen in der Delegate App erfolgen analog zum RUN Mode in der Admin App.

Darstellung von Parameter-Sets

Eine weitere Möglichkeit ergibt sich durch Parameter-Sets. Diese sind ursprünglich in PowerShell eingeführt worden, um einen Use Cases in einem PowerShell Cmdlet unterschiedlich abbilden zu können. In Verbindung mit Scripten und ScriptRunner ergeben sich dadurch sehr interessante zusätzliche Möglichkeiten.

Dazu ein Beispiel: Benutzer haben im AD unterschiedliche Eigenschaften. Neben reinen Informationen wie Telefonnummer, Department etc. eben auch Statusinformationen wie „gesperrt“ oder „inaktiv“. Fasst man alle diese Möglichkeiten in einem Script „Change User“ zusammen, so kann man mit Parameter-Sets unterschiedliche Use Cases abbilden.

Der Script-Header unten bildet drei Use Cases ab:

  • das Ändern von Benutzerinformationen eines Benutzerkontos -> Parameter-Set ‚Change‘
  • das Entsperren eines Benutzerkontos -> Parameter-Set ‚Unlock‘
  • das Deaktivieren und Aktivieren eines Benutzerkontos -> Parameter-Set ‚EnableDisable‘
Nun können Sie in ScriptRunner drei Cases mit ein und demselben Script konfigurieren. Die Unterscheidung erfolgt durch die Auswahl des Parameter-Sets in der jeweiligen Aktion. Das jeweilige Parameter-Set für den Use Cases können Sie im EDIT Mode der Admin App bereits festlegen. Erfolgt keine Festlegung, kann der Anwender in der Delegate App bzw. im RUN der Admin App das Parameter-Set auswählen.

Unterschiedliche Use Cases in Aktionen per Parameter-Set - PowerShell Parameter

Unterschiedliche Use Cases in Aktionen per Parameter-Set

Das angezeigte Eingabe-Formular ändert sich dynamisch mit der Auswahl des jeweiligen Parameter-Sets. Wurde das Parameter-Set per Konfiguration bereits vorgegeben, dann erscheint beim Anwender das passende Formular für den Case.

Im Ergebnis haben Sie drei Aktionen definiert, welche unterschiedliche Use Cases realisieren. In der Anwendung erhält jeder Use Case automatisch ein passendes Formular mit den notwendigen Eingabefeldern. Eingabefelder welche nicht zu dem Use Case bzw. Parameter-Set gehören, werden ausgeblendet.

Use Cases in der Delegate App, mit Script und Parameter-Sets

Drei Use Cases in der Delegate App, realisiert mit einem Script und Parameter-Sets

Verwenden von Queries

Die konsequente Fortführung in der Verwendung von Eingabeparametern ergeben sich aus der Anwendung von ScriptRunner Queries. Dazu sind keine Änderungen am Script selbst notwendig, es werden ausschließlich entsprechende Konfigurationen vorgenommen.

Dazu wird im EDIT Mode der Admin App einem Eingabeparameter eine zuvor konfigurierte Query zugeordnet. Aufgabe der Query ist es, zur Laufzeit eine Auswahlliste für den jeweiligen Eingabeparameter zu „besorgen“. Die Liste der ermittelten Eingabewerte erscheint im Formular als dropdown. Ist der Eingabeparameter als Array deklariert, erscheint ein Drop-Down mit der Möglichkeit zur Mehrfachauswahl.

PowerShell Parameter and Query

Zuweisen einer Query zu einem Eingabeparameter, hier als abhängige Kaskade

Zusätzlich kann bei der Query-Konfiguration festgelegt werden, ob ein Suchfeld und eine Suchfunktion erscheinen soll. Das Suchfeld hat zwei Aufgaben:

  • Pre-Search – die Suche wird für den Suchvorgang parametrisiert. Die Eingabe von „Mü“ bei einer User Query ermittelt eine Liste aller Benutzer mit „mü“ im festgelegten Attribut, bspw. im Namen.
  • Post-Search – die interaktive Suche erfolgt nun in der Ergebnismenge der bereits durchgeführten Query. Die Eingabe von „Mümm“ filtert nun alle Übereinstimmungen aus der Ergebnisliste „mü“ heraus.

In Kombination mit entsprechenden Attribute-Queries können die Eigenschaften von Werten bereits angezeigt werden.

Eingabe Formular mit automatisch abgefragten Werten

Eingabe Formular mit automatisch abgefragten IST-Werten

 

 

Wir beantworten gerne Ihre Fragen!
Haben Sie Fragen zu diesem Beitrag oder zu ScriptRunner? Dann schreiben Sie uns!
Frank Kresse

Frank Kresse

Head of Products Division bei ScriptRunner
Frank Kresse ist verantwortlich für die technische Entwicklung von ScriptRunner. Als Erfinder der Automations- und Delegationslösung für PowerShell berät er Kunden bei Use Case Szenarien und entwickelt Lösungen für die Automation und Digitalisierung ihrer Prozesse. Darüber hinaus engagiert er sich bei Tech-Startups.
Frank Kresse