Sektion 49: Erkennungs- und Korrekturskripts für Remediations schreiben

In Sektion 48 hast du Remediations als Werkzeug kennengelernt: Voraussetzungen, Einstellungen, Zeitpläne und Berichte. Jetzt geht es um den Teil, an dem die meisten Pakete in der Praxis scheitern: die beiden Skripts selbst. Ein Erkennungsskript, das bei einem Fehler das Falsche meldet, oder ein Korrekturskript, das beim zweiten Lauf etwas kaputt macht, richtet auf hunderten Geräten gleichzeitig Schaden an.

Du baust in dieser Sektion ein Skriptpaket für einen Dienst, der laufen soll, und ein reines Erkennungsskript für wenig Speicherplatz. Dabei lernst du die Regeln, nach denen Intune die Skripts auswertet, und die Fallen, die man immer wieder in fertigen Beispielen findet.

Grundlagen: Wer macht was?

Erkennung prüft, Korrektur ändert

Ein Skriptpaket besteht aus einem Erkennungsskript und optional einem Korrekturskript. Die Rollen sind klar verteilt:

• Das Erkennungsskript liest nur. Es ändert nichts am Gerät, denn es läuft bei jedem Zeitplan-Durchlauf, auch auf Geräten ohne Problem.
• Das Korrekturskript ändert den Zustand. Es startet nur, wenn die Erkennung ein Problem gemeldet hat.
• Danach läuft die Erkennung noch einmal. Erst dieser zweite Lauf entscheidet, ob die Korrektur im Bericht als erfolgreich zählt. Erkennung und Korrektur müssen also genau dasselbe meinen.

Der Exitcode ist der Vertrag

Intune schaut nicht auf den Text, den dein Skript ausgibt, sondern auf den Exitcode. Laut Microsoft Learn gilt:

• exit 1 im Erkennungsskript heißt „Problem gefunden“. Nur dann startet das Korrekturskript.
• Jeder andere Exitcode und auch eine leere Ausgabe bedeuten „kein Problem gefunden“.
• Die Ausgabe darf höchstens 2.048 Zeichen lang sein. Der Text ist nur eine Information für dich im Bericht.

Im Bericht landen Ausgabe und Fehler getrennt. Die Graph-Ressource deviceHealthScriptDeviceState zeigt das gut: Es gibt eigene Felder für die Ausgabe der Erkennung vor und nach der Korrektur und für die Fehler aller drei Läufe. Nutz das bewusst: Normale Meldungen schreibst du mit Write-Output, echte Fehler mit Write-Error.

Praxis: Ein Skriptpaket für einen Dienst

Beispiel: Der Agent einer Contoso-Software läuft als Dienst ContosoAgent. Er soll automatisch starten und laufen. Ersetz den Namen durch den Dienst, um den es bei dir geht.

1. Das Erkennungsskript

# Detect_Contoso_Agentdienst.ps1 - Erkennungsskript (prüft nur, ändert nichts)
# exit 1 = Problem gefunden, Korrekturskript startet
# exit 0 = in Ordnung oder nichts, was die Korrektur beheben könnte
$dienst = 'ContosoAgent'

try {
    $svc = Get-Service -Name $dienst -ErrorAction Stop
}
catch {
    # Dienst fehlt: Das kann die Korrektur nicht beheben, also kein exit 1
    Write-Output "Nicht installiert: $dienst"
    exit 0
}

$abweichung = @()
if ($svc.StartType -ne 'Automatic') { $abweichung += "Starttyp $($svc.StartType)" }
if ($svc.Status -ne 'Running')      { $abweichung += "Status $($svc.Status)" }

if ($abweichung.Count -gt 0) {
    Write-Output "Abweichung ${dienst}: $($abweichung -join ', ')"
    exit 1
}

Write-Output "OK: $dienst laeuft, Starttyp Automatic"
exit 0

Drei Dinge sind hier bewusst so gebaut:

• Nur exit 1, wenn die Korrektur helfen kann. Fehlt der Dienst ganz, kann das Korrekturskript ihn nicht herbeizaubern. Würde die Erkennung trotzdem exit 1 melden, liefe die Korrektur jedes Mal ins Leere und das Gerät stünde dauerhaft als fehlgeschlagen im Bericht. Fehlende Software gehört in die App-Bereitstellung, nicht in die Remediation.
• Eine kurze, gleichbleibende Zeile als Ausgabe. Microsoft empfiehlt stabile Ergebnisse ohne Werte, die sich bei jedem Lauf ändern, etwa Zeitstempel. So kannst du die Ausgaben im CSV-Export sauber gruppieren.
• Alle Abweichungen in einer Zeile. Wer im Bericht „Starttyp Manual, Status Stopped“ liest, weiß sofort, was los war.

2. Das Korrekturskript

# Remediate_Contoso_Agentdienst.ps1 - Korrekturskript (darf beliebig oft laufen)
$dienst = 'ContosoAgent'

try {
    $svc = Get-Service -Name $dienst -ErrorAction Stop

    if ($svc.StartType -ne 'Automatic') {
        Set-Service -Name $dienst -StartupType Automatic -ErrorAction Stop
    }
    if ($svc.Status -ne 'Running') {
        Start-Service -Name $dienst -ErrorAction Stop
    }

    # Ergebnis selbst noch einmal prüfen, statt Erfolg nur anzunehmen
    $svc = Get-Service -Name $dienst -ErrorAction Stop
    if ($svc.Status -eq 'Running' -and $svc.StartType -eq 'Automatic') {
        Write-Output "Korrigiert: $dienst laeuft, Starttyp Automatic"
        exit 0
    }
    Write-Error -Message "Nach Korrektur: Status $($svc.Status), Starttyp $($svc.StartType)" -ErrorAction Continue
    exit 1
}
catch {
    Write-Error -Message "Korrektur fehlgeschlagen: $($_.Exception.Message)" -ErrorAction Continue
    exit 1
}

• Idempotent: Das Skript ändert nur, was abweicht. Läuft es zweimal hintereinander, passiert beim zweiten Mal nichts Schädliches. Das ist wichtig, weil du es auch über die Geräteaktion „Run remediation“ (derzeit Vorschau) von Hand auf ein Gerät schicken kannst, ohne zu wissen, in welchem Zustand es gerade ist.
• -ErrorAction Stop: Ohne diesen Parameter sind Fehler bei Set-Service und Start-Service nicht abbrechend und der catch-Block würde nie erreicht. Mit Stop landet jeder Fehler sicher im catch.
• Selbst nachprüfen: Am Ende liest das Skript den Dienst noch einmal und meldet nur dann Erfolg, wenn der Zustand wirklich stimmt. Fehler gehen per Write-Error in das Fehlerfeld des Berichts, dazu kommt exit 1.

3. Ablauf testen

Teste das Paket vor der Zuweisung genau so, wie die IME es ausführt: im Systemkontext, erst Erkennung, dann Korrektur, dann wieder Erkennung. Ein fertiges Testskript dafür findest du in Sektion 48. Spiel dabei bewusst alle Fälle durch: Dienst läuft, Dienst gestoppt, Starttyp manuell, Dienst nicht vorhanden. Bei den ersten drei Fällen muss am Ende die Erkennung exit 0 liefern, beim letzten schon die erste.

Praxis: Nur erkennen, nicht korrigieren

Nicht jedes Problem lässt sich per Skript sicher beheben. Wenig Speicherplatz ist so ein Fall: Automatisch Dateien zu löschen ist riskant. Ein Paket ohne Korrekturskript liefert dir trotzdem einen Bericht über alle betroffenen Geräte:

# Detect_Contoso_Speicherplatz.ps1 - nur Erkennung, kein Korrekturskript im Paket
# Meldet Geräte mit weniger als 15 % freiem Speicher auf C:
$grenzeProzent = 15

function Write-KurzeAusgabe {
    param([string]$Text)
    $max = 2048   # Intune übernimmt höchstens 2.048 Zeichen
    if ($Text.Length -gt $max) { $Text = $Text.Substring(0, $max - 3) + '...' }
    Write-Output $Text
}

try {
    $lw = Get-CimInstance -ClassName Win32_LogicalDisk -Filter "DeviceID='C:'" -ErrorAction Stop
    $freiProzent = [math]::Round($lw.FreeSpace / $lw.Size * 100)
    $freiGB      = [math]::Round($lw.FreeSpace / 1GB)

    if ($freiProzent -lt $grenzeProzent) {
        Write-KurzeAusgabe "Wenig Speicher: C: $freiProzent % frei ($freiGB GB)"
        exit 1
    }
    Write-KurzeAusgabe "OK: C: $freiProzent % frei"
    exit 0
}
catch {
    Write-Error -Message "Pruefung fehlgeschlagen: $($_.Exception.Message)" -ErrorAction Continue
    exit 1
}

Die Werte sind auf ganze Prozent und Gigabyte gerundet, damit sich die Ausgabe nicht bei jedem Lauf minimal ändert. Die kleine Funktion Write-KurzeAusgabe schneidet zu lange Texte bei 2.048 Zeichen ab. Bei einer Zeile wie hier ist das nicht nötig, aber sobald du Listen ausgibst, etwa mehrere Dienste oder Ordner, schützt sie dich vor abgeschnittenen Berichten.

Im Erkennungsstatus erscheinen Geräte mit exit 1 als Geräte mit Problemen („With issues“). Weil kein Korrekturskript im Paket ist, versucht Intune keine Reparatur. Den CSV-Export kannst du dann gezielt an den Support geben.

Typische Fallen

return statt exit

In einigen Beispielskripts, auch in der Microsoft-Sammlung für Remediations, steht ein return direkt vor dem exit 1. Laut about_Return beendet return aber das ganze Skript. Das exit 1 darunter wird nie erreicht:

# Falsch: return beendet das Skript, das exit 1 darunter wird nie erreicht
$treffer = 3
if ($treffer -gt 0) {
    Write-Output "Match"
    return $treffer
    exit 1
}
exit 0

Startest du dieses Skript mit powershell.exe -File, ist der Exitcode 0. Intune wertet das als „kein Problem gefunden“ und das Korrekturskript startet nie. Verwende für das Ergebnis immer exit (siehe about_Language_Keywords) und gib Werte vorher mit Write-Output aus.

Fehler in der Erkennung

Was soll passieren, wenn die Prüfung selbst scheitert, etwa weil eine WMI-Abfrage fehlschlägt? Das entscheidest du pro Paket. Im Speicherplatz-Beispiel endet der catch mit exit 1, damit das Gerät im Bericht auffällt. Bei einem Paket mit Korrekturskript startet damit aber auch die Korrektur. Das ist nur in Ordnung, wenn sie idempotent ist und selbst prüft, ob es etwas zu tun gibt. Sonst ist exit 0 mit einer klaren Fehlermeldung die sicherere Wahl.

Kodierung und Umlaute

Microsoft verlangt UTF-8, bei aktiver Signaturprüfung UTF-8 ohne BOM. Windows PowerShell 5.1 liest UTF-8-Dateien ohne BOM aber laut about_Character_Encoding unter Umständen falsch, wenn sie Nicht-ASCII-Zeichen enthalten. Deshalb stehen in den Ausgaben oben Wörter wie „laeuft“ statt „läuft“. Umlaute in Kommentaren schaden nicht, in Ausgaben und Vergleichswerten können sie verstümmelt ankommen. So prüfst du eine Datei und speicherst sie ohne BOM:

$datei = 'C:\Test\Detect_Contoso_Agentdienst.ps1'

# Prüfen, ob die Datei mit einem BOM (EF BB BF) beginnt
$bytes = [System.IO.File]::ReadAllBytes($datei)
if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
    'UTF-8 mit BOM'
} else {
    'Kein BOM'
}

# Als UTF-8 ohne BOM neu speichern (nur für Dateien, die schon UTF-8 sind)
$text = [System.IO.File]::ReadAllText($datei)
[System.IO.File]::WriteAllText($datei, $text, (New-Object System.Text.UTF8Encoding $false))

Wichtig: Out-File -Encoding UTF8 schreibt in Windows PowerShell 5.1 immer mit BOM. Die .NET-Methode oben ist der einfachste Weg, ohne BOM zu speichern.

Falscher Kontext

Beide Skripts eines Pakets laufen mit denselben Einstellungen: entweder als SYSTEM oder mit den Anmeldeinformationen des Benutzers, und in 32- oder 64-Bit-PowerShell. Prüft die Erkennung etwa HKCU:, liest sie als SYSTEM nicht den Zweig des angemeldeten Benutzers. Bei Unsicherheit hilft ein kurzes Diagnoseskript, dessen Ausgabe du im Bericht siehst:

# Kurz prüfen, in welchem Kontext das Skript läuft (Ausgabe landet im Bericht)
$wer   = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
$64bit = [Environment]::Is64BitProcess
Write-Output "Benutzer: $wer | 64-Bit-Prozess: $64bit"
exit 0

Mehr zu Benutzer- und Systemkontext kommt in einer späteren Sektion. Die Auswirkungen der 64-Bit-Einstellung auf Registry-Pfade hast du schon in Sektion 48 gesehen.

Troubleshooting: Typische Probleme

Erkennung meldet nie ein Problem

• Das Skript endet mit return oder ganz ohne exit 1.
• Ein Vergleich schlägt wegen der Kodierung fehl, etwa ein Umlaut im Sollwert.
• Die Erkennung prüft im falschen Kontext oder im falschen Registry-Zweig (32 statt 64 Bit).

Korrektur läuft, aber die zweite Erkennung meldet weiter einen Fehler

• Erkennung und Korrektur prüfen nicht dasselbe, zum Beispiel unterschiedliche Sollwerte oder Pfade. Leg die Werte in beiden Skripts identisch oben in Variablen ab.
• Die Korrektur meldet Erfolg, ohne nachzuprüfen. Ein Fehler ohne -ErrorAction Stop wird dabei leicht übersehen.
• Etwas anderes setzt den Zustand sofort zurück, etwa eine Richtlinie. Dann hilft kein Skript, sondern nur die Ursache zu finden. Mehr Beispiele dazu findest du im Beitrag Intune Remediations: PowerShell-Skripte, die sich selbst heilen.

Bericht zeigt Skriptfehler statt Ergebnis

• Die Signaturprüfung ist aktiv, aber das Skript ist nicht signiert oder mit BOM gespeichert.
• Ein Syntaxfehler. Teste jedes Skript vorher lokal mit powershell.exe -NoProfile -File, also mit Windows PowerShell 5.1 und nicht nur in PowerShell 7.

Best Practices

• Dateinamen wie bei Microsoft: Detect_… und Remediate_… mit demselben Rest, damit die Paare zusammenbleiben.
• Sollwerte oben im Skript als Variablen, in beiden Skripts identisch.
• Erkennung ändert nichts. Korrektur ändert nur, was abweicht, und prüft danach selbst.
• Eine Zeile Ausgabe ohne Zeitstempel und ohne Umlaute. Fehler über Write-Error.
• Nur exit 1, wenn die Korrektur das Problem auch lösen kann.
• Keine Neustartbefehle, keine Kennwörter, keine personenbezogenen Daten in Skript und Ausgabe.
• Erst nur mit Erkennung an eine Pilotgruppe, dann die Korrektur ergänzen.

Fazit

Gute Remediation-Skripts sind unspektakulär: Die Erkennung liest, entscheidet und meldet eine klare Zeile. Die Korrektur ändert nur das Nötige, prüft sich selbst und darf beliebig oft laufen. Wenn du die Fallen rund um return, Kodierung und Kontext kennst, verhalten sich deine Pakete auf allen Geräten gleich und die Berichte sagen dir wirklich, was los ist.

Zusammenfassend für deinen Workflow:

• Zustand und Sollwerte festlegen, Erkennung schreiben, die nur liest.
• Korrektur idempotent schreiben, mit -ErrorAction Stop und eigener Nachprüfung.
• Kodierung prüfen und alle Fälle lokal mit Windows PowerShell 5.1 als SYSTEM testen.
• Ausgaben und Fehler im Bericht oder CSV-Export auswerten.

In der nächsten Sektion geht es um die Grundlagen der Microsoft Graph API: wie du dich authentifizierst und welche Endpunkte du für Intune brauchst. Einen Überblick über alle Sektionen findest du auf der Seite Intune-Kurs.

Quellen

• Microsoft Learn: Verwenden von Korrekturmaßnahmen (Remediations)
• Microsoft Learn: PowerShell-Skripts für Remediations
• Microsoft Learn (englisch): deviceHealthScriptDeviceState resource type
• Microsoft Learn: about_Return
• Microsoft Learn: about_Language_Keywords
• Microsoft Learn: about_Character_Encoding
• Microsoft Learn: Set-Service
• Microsoft Learn: Start-Service
• Microsoft Learn: Write-Error

↑ Zur Kursübersicht: Intune-Kurs (alle Sektionen)