Skip to the main content.

ScriptRunner Blog

PowerShell Script Header und Parameter zur Verwendung in ScriptRunner

Inhaltsverzeichnis

Post Featured Image

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, 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 ActionPacks) 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 ActionPack 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 UserPrincipal
Name 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 Practices 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 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 ActionPack. 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.
Inhalte des Script Headers werden unter anderem für die Beschreibungen der Scripte und Aktionen verwendet

Inhalte des Script Headers werden unter anderem für die Beschreibungen der Scripte und Aktionen verwendet

Auch im Aktionsreport werden Informationen aus dem Script Header angezeigt

Auch im Aktionsreport werden Informationen aus dem Script Header angezeigt

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.

powershell-params-in-scriptrunner-action-properties-1

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-Listen, 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.

Im Run / Test Mode der Admin App werden zusätzliche Formatinformationen berücksichtigt, bspwe. die mandatory Eigenschaft

Im Run / Test Mode der Admin App werden zusätzliche Formatinformationen berücksichtigt, bspwe. die mandatory Eigenschaft

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 stattdessen die Variablen angezeigt
Ansicht einer Aktion in der Delegate App

Ansicht einer Aktion in der Delegate App

Wenn Sie weitere Informationen zu PowerShell Scripting und die automatische grafische UI in ScriptRunner erhalten möchten, nehmen Sie gerne Kontakt auf! 

Zusammenhängende Posts

2 min read

VMUG Webcast: VMware Management meistern mit PowerCLI

5 min read

PowerShell mit Get-Help meistern

Über den Autor: