PowerShell-Script Header und Parameter zur Verwendung in ScriptRunner

Autor: | Lesezeit: 4 Minuten | Kategorie: Development, PowerShell

PowerShell-Script Header und Parameter, ScriptRunner, PowerShell-Script Code

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:

<# .SYNOPSIS A summary of how the script works and how to use it. .DESCRIPTION A long description of how the script works and how to use it. .NOTES Information about the environment, things to need to be consider and other information. .COMPONENT Information about PowerShell Modules to be required. .LINK Useful Link to ressources or others. .Parameter ParameterName Description for a parameter in param definition section. Each parameter requires a separate description. The name in the description and the parameter section must match. #>

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

<# .SYNOPSIS Copy a Active Directory account, properties and group memberships. .DESCRIPTION .NOTES This PowerShell script was developed and optimized for ScriptRunner. The use of the scripts requires ScriptRunner. The customer or user is authorized to copy the script from the repository and use them in ScriptRunner. The terms of use for ScriptRunner do not apply to this script. In particular, AppSphere AG assumes no liability for the function, the use and the consequences of the use of this freely available script. PowerShell is a product of Microsoft Corporation. ScriptRunner is a product of AppSphere AG. © AppSphere AG .COMPONENT Requires Module ActiveDirectory .LINK https://github.com/scriptrunner/ActionPacks/tree/master/ActiveDirectory/Users .Parameter OUPath Specifies the AD path .Parameter SourceUsername Display name, SAMAccountName, DistinguishedName or user principal name of Active Directory user .Parameter GivenName Specifies the new user's given name .Parameter Surname Specifies the new user's last name or surname .Parameter Password Specifies the password value for the new account .Parameter DomainAccount Active Directory Credential for remote execution without CredSSP .Parameter SamAccountName Specifies the Security Account Manager (SAM) account name of the new user .Parameter UserPrincipalName Specifies the user principal name (UPN) in the format @. .Parameter NewUserName Specifies the name of the new user .Parameter DisplayName Specifies the new user's display name .Parameter EmailAddress Specifies the user's e-mail address .Parameter CopyGroupMemberships Copies the group memberships too .Parameter ChangePasswordAtLogon Specifies whether a password must be changed during the next logon attempt .Parameter DomainName Name of Active Directory Domain .Parameter SearchScope Specifies the scope of an Active Directory search .Parameter AuthType Specifies the authentication method to use #>

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:

param(
    [Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
    [Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")]
    [string]$OUPath,  
    [Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
    [Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")]
    [string]$SourceUsername,
    [Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
    [Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")]
    [string]$GivenName,
    [Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
    [Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")]
    [string]$Surname,    
    [Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
    [Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")]
    [string]$Password,
    [Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")]
    [PSCredential]$DomainAccount,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [string]$SAMAccountName,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [string]$UserPrincipalName,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [string]$NewUserName,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [string]$DisplayName, 
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [string]$EmailAddress,   
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [switch]$CopyGroupMemberships,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [switch]$ChangePasswordAtLogon,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [string]$DomainName,
    [Parameter(ParameterSetName = "Local or Remote DC")]
    [Parameter(ParameterSetName = "Remote Jumphost")]
    [ValidateSet('Basic', 'Negotiate')]
    [string]$AuthType="Negotiate"
)

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.

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.

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.

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

Wenn Sie weitere Informationen zu PowerShell Scripting und die automatische grafische UI in ScriptRunner erhalten möchten, dann wenden Sie sich an uns. 

Diese Beiträge könnten Sie auch interessieren:

PowerShell Script Code, PowerShell Parameter und ihre grafische Darstellung in ScriptRunner
ScriptRunner &