Powershell - Funktionen und Skripte
Kursübersicht
[Bearbeiten | Quelltext bearbeiten]Voraussetzungen: Kurs 1-4 abgeschlossen
Lernziele:
- Du schreibst eigene Funktionen
- Du definierst und validierst Parameter
- Du erstellst wiederverwendbare Skripte
- Du verstehst Scopes und Return-Werte
- Du dokumentierst deinen Code professionell
- Du nutzt fortgeschrittene Funktions-Features
Modul 5.1: Grundlagen von Funktionen
[Bearbeiten | Quelltext bearbeiten]Was sind Funktionen?
[Bearbeiten | Quelltext bearbeiten]Funktionen sind wiederverwendbare Code-Blöcke, die eine bestimmte Aufgabe erfüllen:
Vorteile:
- Wiederverwendbarkeit - Einmal schreiben, mehrfach nutzen
- Wartbarkeit - Änderungen an einer Stelle
- Lesbarkeit - Abstraktionsebene erhöhen
- Testbarkeit - Isolierte Tests möglich
Einfache Funktion
[Bearbeiten | Quelltext bearbeiten]# Funktion ohne Parameter
function Say-Hello {
Write-Host "Hallo Welt!"
}
# Funktion aufrufen
Say-Hello
# Funktion mit Code-Block
function Get-CurrentTime {
$zeit = Get-Date -Format "HH:mm:ss"
Write-Host "Aktuelle Zeit: $zeit"
}
Get-CurrentTime
Namenskonventionen
[Bearbeiten | Quelltext bearbeiten]PowerShell-Funktionen folgen der Verb-Substantiv-Konvention:
| Verb | Verwendung | Beispiel |
|---|---|---|
| Get | Daten abrufen | Get-UserInfo
|
| Set | Werte setzen | Set-Configuration
|
| New | Erstellen | New-LogEntry
|
| Remove | Löschen | Remove-OldFiles
|
| Test | Prüfen | Test-Connection
|
| Start | Starten | Start-Backup
|
| Stop | Stoppen | Stop-Service
|
| Invoke | Ausführen | Invoke-Command
|
# Genehmigte Verben anzeigen
Get-Verb
# Nach Verben filtern
Get-Verb -Verb Get
Get-Verb -Group Data
Return-Werte
[Bearbeiten | Quelltext bearbeiten]# Impliziter Return - letzte Ausgabe wird zurückgegeben
function Get-Summe {
param($a, $b)
$a + $b # Wird automatisch zurückgegeben
}
$ergebnis = Get-Summe 5 10
Write-Host "Summe: $ergebnis" # 15
# Expliziter Return
function Get-Produkt {
param($a, $b)
return $a * $b
}
$ergebnis = Get-Produkt 5 10
Write-Host "Produkt: $ergebnis" # 50
# Mehrere Ausgaben
function Get-Statistik {
param($zahlen)
$summe = ($zahlen | Measure-Object -Sum).Sum
$durchschnitt = ($zahlen | Measure-Object -Average).Average
# Beide Werte werden zurückgegeben (als Array)
$summe
$durchschnitt
}
$stats = Get-Statistik @(1, 2, 3, 4, 5)
Write-Host "Summe: $($stats[0]), Durchschnitt: $($stats[1])"
| Out-Null oder $null = um unerwünschte Ausgaben zu unterdrücken.Modul 5.2: Parameter
[Bearbeiten | Quelltext bearbeiten]Einfache Parameter
[Bearbeiten | Quelltext bearbeiten]# Parameter-Block
function Greet-Person {
param(
$name
)
Write-Host "Hallo, $name!"
}
Greet-Person "Anna"
Greet-Person -name "Bob"
# Mehrere Parameter
function Get-Rechteck {
param(
$breite,
$hoehe
)
$flaeche = $breite * $hoehe
$umfang = 2 * ($breite + $hoehe)
Write-Host "Fläche: $flaeche"
Write-Host "Umfang: $umfang"
}
Get-Rechteck -breite 5 -hoehe 10
Get-Rechteck 5 10 # Positionsparameter
Typisierte Parameter
[Bearbeiten | Quelltext bearbeiten]function Add-Numbers {
param(
[int]$zahl1,
[int]$zahl2
)
return $zahl1 + $zahl2
}
Add-Numbers 5 10 # 15
Add-Numbers "5" "10" # 15 (automatische Konvertierung)
# Add-Numbers "abc" "xyz" # Fehler!
# Verschiedene Typen
function New-User {
param(
[string]$name,
[int]$alter,
[bool]$aktiv,
[datetime]$geburtsdatum,
[array]$rollen
)
Write-Host "Benutzer: $name, Alter: $alter, Aktiv: $aktiv"
}
Standardwerte
[Bearbeiten | Quelltext bearbeiten]function Write-Log {
param(
[string]$nachricht,
[string]$level = "INFO",
[string]$datei = "C:\Logs\app.log"
)
$zeitstempel = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
$eintrag = "[$zeitstempel] [$level] $nachricht"
Add-Content -Path $datei -Value $eintrag
Write-Host $eintrag
}
# Mit Standardwerten
Write-Log "Anwendung gestartet"
# Standardwerte überschreiben
Write-Log -nachricht "Kritischer Fehler" -level "ERROR"
Write-Log -nachricht "Debug-Info" -level "DEBUG" -datei "C:\Logs\debug.log"
Mandatory Parameter
[Bearbeiten | Quelltext bearbeiten]function Connect-Server {
param(
[Parameter(Mandatory=$true)]
[string]$servername,
[Parameter(Mandatory=$true)]
[string]$username,
[Parameter(Mandatory=$false)]
[string]$port = "22"
)
Write-Host "Verbinde zu $servername`:$port als $username..."
}
# PowerShell fragt nach fehlenden Parametern
Connect-Server
# Cmdlet Connect-Server an Befehlspipelineposition 1
# Geben Sie Werte für die folgenden Parameter an:
# servername: ...
Modul 5.3: Parameter-Validierung
[Bearbeiten | Quelltext bearbeiten]ValidateSet
[Bearbeiten | Quelltext bearbeiten]Beschränkt Eingaben auf eine Liste erlaubter Werte:
function Set-LogLevel {
param(
[Parameter(Mandatory=$true)]
[ValidateSet("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")]
[string]$level
)
Write-Host "Log-Level gesetzt auf: $level"
}
Set-LogLevel -level "INFO" # OK
Set-LogLevel -level "TRACE" # Fehler!
# Mit Tab-Completion
Set-LogLevel -level <Tab> # Zeigt Optionen
ValidateRange
[Bearbeiten | Quelltext bearbeiten]Prüft, ob Zahlen in einem Bereich liegen:
function Set-Volume {
param(
[Parameter(Mandatory=$true)]
[ValidateRange(0, 100)]
[int]$lautstaerke
)
Write-Host "Lautstärke auf $lautstaerke% gesetzt"
}
Set-Volume -lautstaerke 50 # OK
Set-Volume -lautstaerke 150 # Fehler!
ValidateLength
[Bearbeiten | Quelltext bearbeiten]Prüft String-Länge:
function New-Username {
param(
[Parameter(Mandatory=$true)]
[ValidateLength(3, 20)]
[string]$username
)
Write-Host "Benutzername erstellt: $username"
}
New-Username -username "ab" # Fehler (zu kurz)
New-Username -username "max123" # OK
New-Username -username "a" * 25 # Fehler (zu lang)
ValidatePattern
[Bearbeiten | Quelltext bearbeiten]Prüft gegen Regex-Muster:
function Set-Email {
param(
[Parameter(Mandatory=$true)]
[ValidatePattern("^\w+@\w+\.\w+$")]
[string]$email
)
Write-Host "Email gesetzt: $email"
}
Set-Email -email "user@example.com" # OK
Set-Email -email "invalid-email" # Fehler!
# IP-Adresse validieren
function Test-IPAddress {
param(
[ValidatePattern("^(\d{1,3}\.){3}\d{1,3}$")]
[string]$ip
)
Write-Host "Gültige IP: $ip"
}
ValidateScript
[Bearbeiten | Quelltext bearbeiten]Führt eigenen Validierungs-Code aus:
function Remove-OldFile {
param(
[Parameter(Mandatory=$true)]
[ValidateScript({
Test-Path $_ -PathType Leaf
})]
[string]$pfad
)
Remove-Item -Path $pfad
Write-Host "Datei gelöscht: $pfad"
}
# Mit Fehlermeldung
function Set-Port {
param(
[ValidateScript({
if ($_ -ge 1024 -and $_ -le 65535) {
$true
} else {
throw "Port muss zwischen 1024 und 65535 liegen"
}
})]
[int]$port
)
Write-Host "Port gesetzt: $port"
}
ValidateNotNullOrEmpty
[Bearbeiten | Quelltext bearbeiten]Stellt sicher, dass Parameter nicht leer ist:
function New-Folder {
param(
[Parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[string]$name
)
New-Item -Path $name -ItemType Directory
Write-Host "Ordner erstellt: $name"
}
New-Folder -name "" # Fehler!
New-Folder -name $null # Fehler!
Mehrere Validierungen kombinieren
[Bearbeiten | Quelltext bearbeiten]function New-SecurePassword {
param(
[Parameter(Mandatory=$true)]
[ValidateNotNullOrEmpty()]
[ValidateLength(8, 50)]
[ValidatePattern("^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$")]
[string]$passwort
)
Write-Host "Sicheres Passwort erstellt!" -ForegroundColor Green
}
# Muss alle Kriterien erfüllen:
# - Nicht leer
# - 8-50 Zeichen
# - Mind. 1 Kleinbuchstabe, 1 Großbuchstabe, 1 Zahl, 1 Sonderzeichen
Modul 5.4: Fortgeschrittene Parameter-Features
[Bearbeiten | Quelltext bearbeiten]Parameter-Sets
[Bearbeiten | Quelltext bearbeiten]Definiere verschiedene Parameter-Kombinationen:
function Connect-Database {
[CmdletBinding(DefaultParameterSetName="Integrated")]
param(
[Parameter(ParameterSetName="Integrated", Mandatory=$true)]
[Parameter(ParameterSetName="SqlAuth", Mandatory=$true)]
[string]$server,
[Parameter(ParameterSetName="SqlAuth", Mandatory=$true)]
[string]$username,
[Parameter(ParameterSetName="SqlAuth", Mandatory=$true)]
[string]$password,
[Parameter(ParameterSetName="Integrated")]
[switch]$integratedSecurity = $true
)
if ($PSCmdlet.ParameterSetName -eq "Integrated") {
Write-Host "Verbinde mit integrierter Authentifizierung..."
} else {
Write-Host "Verbinde als $username..."
}
}
# Verwendung
Connect-Database -server "SQL01" # Integrated
Connect-Database -server "SQL01" -username "admin" -password "geheim" # SqlAuth
Pipeline-Input
[Bearbeiten | Quelltext bearbeiten]Funktionen können Werte aus der Pipeline empfangen:
function Convert-ToMB {
param(
[Parameter(ValueFromPipeline=$true)]
[long]$bytes
)
process {
$mb = [math]::Round($bytes / 1MB, 2)
Write-Host "$bytes Bytes = $mb MB"
}
}
# Aus Pipeline
Get-ChildItem | Select-Object -First 5 Length | Convert-ToMB
# Direkter Aufruf
Convert-ToMB -bytes 52428800
# Pipeline mit Objekteigenschaften
function Get-ProcessMemory {
param(
[Parameter(ValueFromPipelineByPropertyName=$true)]
[string]$Name
)
process {
$prozess = Get-Process -Name $Name -ErrorAction SilentlyContinue
if ($prozess) {
$memMB = [math]::Round($prozess.WorkingSet / 1MB, 2)
Write-Host "$Name : $memMB MB"
}
}
}
# Verwendung
Get-Process | Select-Object -First 5 Name | Get-ProcessMemory
Begin, Process, End
[Bearbeiten | Quelltext bearbeiten]Für Pipeline-Verarbeitung:
function Convert-Text {
param(
[Parameter(ValueFromPipeline=$true)]
[string]$text
)
begin {
Write-Host "=== Konvertierung starten ==="
$anzahl = 0
}
process {
$anzahl++
$gross = $text.ToUpper()
Write-Host "$anzahl. $gross"
}
end {
Write-Host "=== $anzahl Texte konvertiert ==="
}
}
# Verwendung
"anna", "bob", "clara" | Convert-Text
# Ausgabe:
# === Konvertierung starten ===
# 1. ANNA
# 2. BOB
# 3. CLARA
# === 3 Texte konvertiert ===
Switch-Parameter
[Bearbeiten | Quelltext bearbeiten]Boolean-Parameter ohne Wert:
function Get-Files {
param(
[string]$path = ".",
[switch]$recurse,
[switch]$hidden
)
$params = @{
Path = $path
}
if ($recurse) {
$params.Recurse = $true
}
if ($hidden) {
$params.Force = $true
}
Get-ChildItem @params
}
# Verwendung
Get-Files
Get-Files -recurse
Get-Files -path "C:\Temp" -recurse -hidden
# Switch-Wert abfragen
if ($recurse) {
Write-Host "Rekursive Suche aktiviert"
}
Modul 5.5: [CmdletBinding] und fortgeschrittene Funktionen
[Bearbeiten | Quelltext bearbeiten]Was ist [CmdletBinding]?
[Bearbeiten | Quelltext bearbeiten][CmdletBinding()] macht aus einer einfachen Funktion eine Advanced Function mit Cmdlet-Features:
function Get-AdvancedInfo {
[CmdletBinding()]
param(
[string]$name
)
Write-Verbose "Rufe Informationen für $name ab..."
Write-Host "Info für: $name"
}
# Aktiviert automatisch:
# -Verbose
# -Debug
# -ErrorAction
# -WarningAction
# -InformationAction
# -ErrorVariable
# -WarningVariable
# -OutVariable
# -OutBuffer
# -PipelineVariable
Get-AdvancedInfo -name "Test" -Verbose
Common Parameters
[Bearbeiten | Quelltext bearbeiten]function Test-AdvancedFunction {
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[string]$name
)
Write-Verbose "Verbose-Nachricht: Starte Verarbeitung"
Write-Debug "Debug-Nachricht: Name = $name"
Write-Warning "Warnung: Dies ist ein Test"
Write-Information "Info-Nachricht"
Write-Host "Verarbeite: $name"
}
# Verwendung
Test-AdvancedFunction -name "Test" -Verbose
Test-AdvancedFunction -name "Test" -Debug
Test-AdvancedFunction -name "Test" -WarningAction SilentlyContinue
SupportsShouldProcess
[Bearbeiten | Quelltext bearbeiten]Ermöglicht -WhatIf und -Confirm:
function Remove-CustomFile {
[CmdletBinding(SupportsShouldProcess=$true)]
param(
[Parameter(Mandatory=$true)]
[string]$path
)
if ($PSCmdlet.ShouldProcess($path, "Datei löschen")) {
Remove-Item -Path $path
Write-Host "Datei gelöscht: $path"
}
}
# Verwendung
Remove-CustomFile -path "test.txt" -WhatIf # Zeigt nur, was passieren würde
Remove-CustomFile -path "test.txt" -Confirm # Fragt nach Bestätigung
Remove-CustomFile -path "test.txt" # Führt aus
ConfirmImpact
[Bearbeiten | Quelltext bearbeiten]Bestimmt, wann automatisch nach Bestätigung gefragt wird:
function Remove-ImportantFile {
[CmdletBinding(
SupportsShouldProcess=$true,
ConfirmImpact="High"
)]
param(
[string]$path
)
if ($PSCmdlet.ShouldProcess($path, "Wichtige Datei löschen")) {
Remove-Item -Path $path -Force
Write-Host "Datei gelöscht"
}
}
# Bei ConfirmImpact="High" wird automatisch um Bestätigung gebeten
# (außer $ConfirmPreference wurde geändert)
Modul 5.6: Skripte erstellen
[Bearbeiten | Quelltext bearbeiten]Skript vs. Funktion
[Bearbeiten | Quelltext bearbeiten]| Aspekt | Funktion | Skript |
|---|---|---|
| Definition | Im Speicher | Als .ps1-Datei |
| Aufruf | Nach Name | Mit Pfad |
| Lebensdauer | Session | Datei bleibt |
| Parameter | param-Block | param-Block |
| Verwendung | Wiederverwendbare Bausteine | Komplette Programme |
Einfaches Skript
[Bearbeiten | Quelltext bearbeiten]Datei: Backup.ps1
# Backup-Skript
param(
[string]$quelle = "C:\Daten",
[string]$ziel = "D:\Backup"
)
Write-Host "=== Backup-Skript ==="
Write-Host "Quelle: $quelle"
Write-Host "Ziel: $ziel"
# Prüfen ob Quelle existiert
if (-not (Test-Path $quelle)) {
Write-Host "Fehler: Quelle existiert nicht!" -ForegroundColor Red
exit 1
}
# Zielordner erstellen
if (-not (Test-Path $ziel)) {
New-Item -Path $ziel -ItemType Directory | Out-Null
}
# Backup durchführen
$datum = Get-Date -Format "yyyy-MM-dd_HHmmss"
$backupOrdner = Join-Path $ziel "Backup_$datum"
Copy-Item -Path $quelle -Destination $backupOrdner -Recurse
Write-Host "Backup abgeschlossen: $backupOrdner" -ForegroundColor Green
Ausführen:
# Im aktuellen Verzeichnis
.\Backup.ps1
# Mit Parametern
.\Backup.ps1 -quelle "C:\Dokumente" -ziel "E:\Backups"
# Mit vollständigem Pfad
C:\Scripts\Backup.ps1
Skript-Parameter
[Bearbeiten | Quelltext bearbeiten]# SystemInfo.ps1
[CmdletBinding()]
param(
[Parameter(Mandatory=$false)]
[string[]]$computerName = $env:COMPUTERNAME,
[Parameter(Mandatory=$false)]
[switch]$exportieren,
[Parameter(Mandatory=$false)]
[string]$exportPfad = ".\system_info.csv"
)
$ergebnisse = @()
foreach ($computer in $computerName) {
Write-Verbose "Sammle Informationen von $computer..."
try {
$os = Get-CimInstance -ClassName Win32_OperatingSystem -ComputerName $computer
$cs = Get-CimInstance -ClassName Win32_ComputerSystem -ComputerName $computer
$info = [PSCustomObject]@{
Computer = $computer
OS = $os.Caption
Version = $os.Version
LastBoot = $os.LastBootUpTime
TotalRAM_GB = [math]::Round($cs.TotalPhysicalMemory / 1GB, 2)
Manufacturer = $cs.Manufacturer
Model = $cs.Model
}
$ergebnisse += $info
$info | Format-List
} catch {
Write-Warning "Fehler bei $computer : $_"
}
}
if ($exportieren) {
$ergebnisse | Export-Csv -Path $exportPfad -NoTypeInformation
Write-Host "`nExportiert nach: $exportPfad" -ForegroundColor Green
}
Exit-Codes
[Bearbeiten | Quelltext bearbeiten]# TestScript.ps1
param(
[string]$pfad
)
if (-not (Test-Path $pfad)) {
Write-Host "Fehler: Pfad nicht gefunden!" -ForegroundColor Red
exit 1 # Fehler-Code
}
if ((Get-Item $pfad).Length -eq 0) {
Write-Host "Warnung: Datei ist leer!" -ForegroundColor Yellow
exit 2 # Warnung-Code
}
Write-Host "Alles OK!" -ForegroundColor Green
exit 0 # Erfolg
# Exit-Code abfragen:
# .\TestScript.ps1 -pfad "test.txt"
# $LASTEXITCODE # Zeigt Exit-Code
Modul 5.7: Kommentare und Dokumentation
[Bearbeiten | Quelltext bearbeiten]Einzeilige Kommentare
[Bearbeiten | Quelltext bearbeiten]# Dies ist ein einzeiliger Kommentar
$name = "Anna" # Kommentar am Zeilenende
# Mehrere
# aufeinanderfolgende
# Kommentare
Mehrzeilige Kommentare
[Bearbeiten | Quelltext bearbeiten]<#
Dies ist ein mehrzeiliger Kommentar.
Er kann über mehrere Zeilen gehen.
Nützlich für längere Erklärungen.
#>
function Get-Data {
<#
Hier kann die Funktions-Dokumentation stehen.
Beschreibung der Funktion...
#>
# Code hier
}
Comment-Based Help
[Bearbeiten | Quelltext bearbeiten]Professionelle Dokumentation mit Get-Help:
function Get-UserReport {
<#
.SYNOPSIS
Erstellt einen Bericht über Benutzer.
.DESCRIPTION
Diese Funktion sammelt Informationen über Benutzer
und erstellt einen detaillierten Bericht.
Der Bericht kann in verschiedenen Formaten exportiert werden.
.PARAMETER username
Der Benutzername für den Bericht.
.PARAMETER format
Das Export-Format (CSV, JSON, HTML).
Standard ist CSV.
.PARAMETER outputPath
Der Pfad für die Export-Datei.
Standard ist das aktuelle Verzeichnis.
.EXAMPLE
Get-UserReport -username "anna"
Erstellt einen Bericht für Benutzer anna.
.EXAMPLE
Get-UserReport -username "bob" -format "JSON" -outputPath "C:\Reports"
Erstellt einen JSON-Bericht für bob im angegebenen Pfad.
.NOTES
Author: Max Mustermann
Version: 1.0
LastModified: 2025-01-15
.LINK
https://docs.example.com/get-userreport
#>
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[string]$username,
[ValidateSet("CSV", "JSON", "HTML")]
[string]$format = "CSV",
[string]$outputPath = "."
)
# Funktions-Code hier
Write-Host "Erstelle $format-Bericht für $username..."
}
# Hilfe anzeigen
Get-Help Get-UserReport
Get-Help Get-UserReport -Detailed
Get-Help Get-UserReport -Examples
Get-Help Get-UserReport -Full
Comment-Based Help Schlüsselwörter
[Bearbeiten | Quelltext bearbeiten]| Schlüsselwort | Beschreibung |
|---|---|
.SYNOPSIS |
Kurze Beschreibung (eine Zeile) |
.DESCRIPTION |
Detaillierte Beschreibung |
.PARAMETER |
Beschreibung eines Parameters |
.EXAMPLE |
Verwendungsbeispiel |
.INPUTS |
Was kann über Pipeline empfangen werden |
.OUTPUTS |
Was wird zurückgegeben |
.NOTES |
Zusätzliche Informationen |
.LINK |
Verweis auf Website/Dokument |
.COMPONENT |
Technologie/Feature |
.ROLE |
Zielrolle |
.FUNCTIONALITY |
Funktionalität |
Praktische Übungen
[Bearbeiten | Quelltext bearbeiten]Übung 1: Temperatur-Konverter
[Bearbeiten | Quelltext bearbeiten]Aufgabe: Erstelle eine Funktion, die:
- Celsius in Fahrenheit und Kelvin konvertiert
- Parameter für die Eingabe-Temperatur hat
- Parameter-Validierung verwendet (-273.15°C ist absoluter Nullpunkt)
- Ein Objekt mit allen drei Werten zurückgibt
- Comment-Based Help hat
Lösung anzeigen
<syntaxhighlight lang="powershell"> function Convert-Temperature {
<#
.SYNOPSIS
Konvertiert Celsius in Fahrenheit und Kelvin.
.DESCRIPTION
Diese Funktion nimmt eine Temperatur in Celsius entgegen
und konvertiert sie in Fahrenheit und Kelvin.
Der absolute Nullpunkt (-273.15°C) ist die Untergrenze.
.PARAMETER celsius
Die Temperatur in Grad Celsius.
.EXAMPLE
Convert-Temperature -celsius 25
Konvertiert 25°C in Fahrenheit und Kelvin.
.EXAMPLE
Convert-Temperature 0