Zum Inhalt springen

Powershell - Funktionen und Skripte

Aus Gerhards Wiki

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

[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"
}
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]

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

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!

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"
}

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

Modul 5.4: Fortgeschrittene Parameter-Features

[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

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

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

  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