ScriptTipp Header und Parameter

PowerShell Script Header und Parameter zur Verwendung in ScriptRunner

PowerShell unterstützt als Programmiersprache selbstverständlich Headerinformationen für Scripte. Während die Header für die interaktive Anwendung in der PowerShell Konsole oder der PowerShell ISE keine Bedeutung haben, trifft für PowerShell Scripte genau das Gegenteil zu. Auch Parametereingaben, so wie sie aus PowerShell Cmdlets bekannt sind, sollten als Eingabeparameter im Script fest deklariert werden. Microsoft empfiehlt in seinen „best practices for powershell scripting“ sowohl Script Header als auch Parameter Deklarationen einzusetzen. Aus diesen und weiteren Gründen wirft dieser Beitrag einen Blick auf den PowerShell Script Header und welche Auswirkungen er auf die Arbeitsweise von ScriptRunner hat.

Best Practices für PowerShell Script Header

Es gibt verschiedene Informationen im Script Header, welche die Lesbarkeit und Nachvollziehbarkeit von Scripten verbessern sollen. Folgende Headerinformationen kommen in den Scriptsammlungen für ScriptRunner (den ScriptRunner Action Packs) zur Anwendung:

 

Ein Praxisbeispiel: PowerShell Script Header des Scripts „Copy-ADUser“ aus dem ScriptRunner Action Pack for Active Directory.

Best Practises für die Deklaration von PowerShell Parametern

In PowerShell Scripten nutzt man Parameter-Deklarationen. Diese definieren und strukturieren die Eingabe bzw. den Input für das PowerShell Script. Die Deklaration wird in einem Block zusammengefasst und als Param-Block oder auch Parameter Section bezeichnet. Die Parameternamen in der Deklaration müssen mit dem Namen für die Variable im Header übereinstimmen. Eine Parameter-Deklaration enthält in der Regel den Typ der Variable und deren Namen. Zusätzlich können weitere Eigenschaften zur Verwendung der Variable und den erlaubten Eingabemöglichkeiten festgelegt werden.

Die Parameter-Deklaration für das Praxisbeispiel hier im Folgenden:

Nachdem nun sowohl der Script Header als auch die PowerShell Parameter definiert wurden, werden nachfolgend die Auswirkungen dieser beiden Blöcke in ScriptRunner aufgezeigt.

Verwendung der PowerShell Script Header in ScriptRunner

Der Script Header erfüllt in ScriptRunner mehrere Aufgaben:

  • Automatisches Ausfüllen eines Beschreibungsfeldes für das Script. In dieses Feld wird der Header .SYNOPSIS übernommen. Ist dieser nicht vorhanden oder leer wird der Header .DESCRIPTION dafür verwendet und ggf. automatisch gekürzt. Das lästige Ausfüllen von Beschreibungsfeldern wird von ScriptRunner übernommen. Das Beschreibungsfeld kann manuell überschrieben werden, ohne dass sich der Script Header ändert.
  • Automatisches Ausfüllen eines  Beschreibungsfeldes für eine ScriptRunner Aktion, welche dieses Script verwendet. Die Beschreibung wird aus den Scripteigenschaften übernommen.
  • Automatische Anzeige des Header .NOTES und Hinweise zum Action Pack. Diese findet man auf der Seite der Eigenschaften beim Script und der Aktion, in welcher das Script verwendet wird.
  • Automatische Anzeige einer Kurzbeschreibung auf der Formulareingabeseite beim Ausführen einer Aktion in den Web Apps für Administratoren, Operatoren und Endbenutzer.
  • Automatisches Ausfüllen der Ursachenbeschreibung im Report einer ausgeführten Aktion, sofern beim Starten der Aktion kein anderer Ursachen-Code vorlag. Somit ist jederzeit ein Bezug zu der beabsichtigten Funktion, welche das Script ausführen soll, auch im Report und für Auswertungen gegeben.
  • Automatische Anzeige des Header .PARAMETER paramname als beschreibender Titels des generisch erzeugten Eingabefeldes im Formular der Admin und Delegate App.

PowerShell header and parameter declaration in ScriptRunner property pages

PowerShell header and parameter in ScriptRunner Reports

 

Verwendung der PowerShell Parameter in ScriptRunner

Die Parameter-Deklaration erfüllt in ScriptRunner ebenfalls verschiedene Aufgaben. Im Einzelnen sind das:

  • Automatisches Auflisten aller Eingabeparameter auf der Eigenschaftsseite des Scripts (siehe Abb. oben)
  • Automatisches Generieren von Eingabefeldern zum Vorbelegen von Werten auf der Konfigurationsseite für eine ScriptRunner Aktion
  • Automatisches Generieren von Eingabefeldern auf der Konfigurationsseite von Scripted Queries
  • Automatisches Generieren von Eingabefeldern sowie deren Verhalten auf der Formularseite zum Eingeben der Werte vor dem Ausführen eines Scripts in der Admin und Delegate App

Beim Generieren der Eingabefelder in der Admin App werden zwei Modi unterschieden:

  • Edit Mode
  • Run / Test Mode

Es werden in beiden Modi neben den Headern .SYNOPSIS und .PARAMETER auch die Parameternamen bzw. Variablen des Param-Blocks selbst angezeigt. Im Edit mode können die Parameter mit Werten (Values) sowohl vorbelegt als auch arretiert werden. Arretierte Werte wirken somit als Konstanten mit festen Wert. Das Verhalten der Parameter-Typen aus der Deklaration wird dabei berücksichtigt.

Configuration and Predefinition of PowerShell parameters in ScriptRunner

In ScriptRunner bestimmt die Reihenfolge der Parameter in der Deklaration auch die Reihenfolge der automatisch erzeugten Formularfelder in den Eingabemasken. Außerdem interpretiert ScriptRunner bekannte Variablentypen und Formatinformationen. So werden Parameter mit den Zusatzeigenschaften „Mandatory“ zu Pflichteingabefeldern, „ValidateSets“ werden zu dropdown-Menus, „ValidateRange“ und „ValidateLength“ prüfen die Benutzereingaben usw.

Im Run / Test Mode der Admin App  werden zusätzliche Formatinformationen berücksichtigt. Hier im Praxisbeispiel die „mandatory“ Eigenschaft. Parameter, welche im Edit Mode vorbelegt wurden, werden mit der ausgefüllten Wert-Vorbelegung angezeigt. Solche, die arretiert wurden, werden im Run Mode nicht mehr angezeigt, da sie bereits mit fixen Werten belegt sind.

Auto-generation of input form in ScriptRunner Admin Web App in Run/Test mode

 

In der Delegate App existiert nur eine Darstellung für den Run-Mode. Dieser entspricht weitgehend der Admin App. Es gibt jedoch zwei wichtige Unterschiede:

  • Die Parameter- bzw. Variablennamen werden dem Anwender nicht dargestellt.
  • Existieren keine Header .PARAMETER paramname, so werden statt dessen die Variablen angezeigt
PowerShell Script

Auto-generation of input form in ScriptRunner Delegate Web App

 

Wenn Sie weitere Informationen zu PowerShell Scripting und die automatische grafische UI in ScriptRunner erhalten möchten, dann wenden Sie sich an 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