PowerShell Parameter und ihre grafische Darstellung in ScriptRunner

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. Die Ausführenden müssen PowerShell ausführen dürfen und  müssen in dem Rechtekontext arbeiten, der zur Scriptausführung notwendig ist.
2. Die Miniprogramme müssen zu den Anwendern 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 Helpdesk 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 Helpdesk-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 Dropdown-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 Anwenders 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 generiert 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.

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 auch nach deren Attributen.

Ein Beispiel:

 <# .SYNOPSIS An example for the generic display of input parameters with different data types and extended parameter declarations in ScriptRunner Admin and Delegate App .PARAMETER MyString Please enter a simple string .PARAMETER MyStringSelect Please select one of the simple strings .PARAMETER MyUintArray Please enter several numbers, separated by comma .PARAMETER MyStringArray Please select multiple strings, use CTRL Click .PARAMETER MyNumber Please enter a Number .PARAMETER MySwitch Please select the box .PARAMETER MyCredential Please select a Credential #>

param

(
  [Parameter(Mandatory=$true)]      #this input is mandatory

  [ValidateLength(5, 10)]           #only min 5 and max 10 chars allowed

  [string]$MyString,


  [Parameter(Mandatory=$true,Position=4)]   #this param will displayed on fourth position

  [ValidateSet('first','second','third')]   #only these values are allowed

  [string]$MyStringSelect,

  [ValidateRange(7, 18)]            #the input min/max per value is allowed, comma separated

  [uint16[] ]$MyUintArray,

  [ValidateSet('one','two','three','four')] #only this values are allowed, multiple selection possible

  [string[]]$MyStringArray,


  [Parameter(Position=2)]

  [ValidateRange(2018,2023)]        #the input of minimum 2018 and maximum 2023 is allowed

  [int]$MyNumber,

  [switch]$MySwitch,                #defines a switch

  [PSCredential]$MyCredential       #defines a PowerShell credential parameter
)The application of this script header leads to the display of the different properties in the automatically generated form.

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.

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.

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‘

    [string]$UserName,


    [Parameter(Mandatory=$false, ParameterSetName="Unlock")]

    [switch]$Unlock,


    [Parameter(Mandatory=$false, ParameterSetName="EnableDisable")]

    [ValidateSet('Keep', 'Enable', 'Disable')]

    [string]$Enable = 'Keep',


    [Parameter(Mandatory=$false, ParameterSetName="Change")]

    [string]$City,


    [Parameter(Mandatory=$false, ParameterSetName="Change")]

    [string]$Department,


    [Parameter(Mandatory=$false, ParameterSetName="Change")]

    [string]$StreetAddress,


    [Parameter(Mandatory=$false, ParameterSetName="Change")]

    [string]$OPhone

)

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

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.

Three use cases in the Delegate App, realized with a script and parametersets

 

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.

Weisen Sie einem Eingangsparameter eine Abfrage zu, hier als abhängige Kaskade

Assign a query to an input parameter, here as a dependent cascade

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.