Zum Inhalt springen

Powershell - Funktionen und Skripte

Aus Gerhards Wiki
Version vom 25. November 2025, 08:25 Uhr von Gerhard (Diskussion | Beiträge) (→Return-Werte)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

Kursübersicht

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

Was sind Funktionen?

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

# 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

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
💡
Tipp
Halte dich an die Verb-Nomen-Konvention für professionelle, konsistente Funktionen!

Return-Werte

# 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])"
ℹ️
Hinweis
In PowerShell wird ALLES, was ausgegeben wird, zurückgegeben. Verwende | Out-Null oder $null = um unerwünschte Ausgaben zu unterdrücken.

Modul 5.2: Parameter

Einfache Parameter

# 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

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

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

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

ValidateSet

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

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

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

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

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

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

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
💡
Tipp
Parameter-Validierung hilft, Fehler frühzeitig zu erkennen und macht Funktionen robuster!

Modul 5.4: Fortgeschrittene Parameter-Features

Parameter-Sets

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

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

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

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

Was ist [CmdletBinding]?

[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

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

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

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

Skript vs. Funktion

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

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

# 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

# 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

Einzeilige Kommentare

# Dies ist ein einzeiliger Kommentar

$name = "Anna"  # Kommentar am Zeilenende

# Mehrere
# aufeinanderfolgende
# Kommentare

Mehrzeilige Kommentare

<#
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

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

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

Übung 1: Temperatur-Konverter

Aufgabe: Erstelle eine Funktion, die:

  1. Celsius in Fahrenheit und Kelvin konvertiert
  2. Parameter für die Eingabe-Temperatur hat
  3. Parameter-Validierung verwendet (-273.15°C ist absoluter Nullpunkt)
  4. Ein Objekt mit allen drei Werten zurückgibt
  5. 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