14 min read
Der Schlüssel zu produktiver Softwareverwaltung: winget & PowerShell
Steigere die IT-Effizienz mit Winget und PowerShell! Lies, wie du Installationen, Updates und die Verwaltung von...
ScriptRunner Blog
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.
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
#>
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.
Der Script Header erfüllt in ScriptRunner mehrere Aufgaben:
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
Die Parameter-Deklaration erfüllt in ScriptRunner ebenfalls verschiedene Aufgaben. Im Einzelnen sind das:
Beim Generieren der Eingabefelder in der Admin App werden zwei Modi unterschieden:
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-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
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:
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!
Dez 19, 2024 by Jeffery Hicks
Steigere die IT-Effizienz mit Winget und PowerShell! Lies, wie du Installationen, Updates und die Verwaltung von...
Dez 19, 2024 by Damian Scoles
Mit Microsoft Purview verstehst und verwaltest du Daten in deinem gesamten Datenbestand – wie kannst du PowerShell...
Dez 17, 2024 by Sonny Jamwal
Erweitere PowerShell mit .NET für eine leistungsstarke Ereignisautomatisierung. Systemereignisse wie ein Profi...
Frank Kresse ist Head of Product und CEO von ScriptRunner. Als Erfinder der Automatisierungs- und Delegationslösung für PowerShell berät er Kunden zu Use-Case-Szenarien und entwickelt Lösungen für die Automatisierung und die Digitalisierung ihrer Prozesse. Außerdem ist er an Technologie-Start-ups beteiligt.