BizTalkPlatformManagementTool/docs/PROD-ScheduledTask-und-Laufzeitlogging-2026-08-26.md

# PROD-Runbook: ScheduledTask-Steuerung und persistentes Laufzeitlogging

**Stand:** 2026-08-26

**Zielversion:** 2.3.3

**Betroffener Adapter:** BizTalk ScheduledTask Adapter 7.0.2

**Bestätigter Adapterpfad:** `C:\Program Files (x86)\BizTalk ScheduledTask Adapter 7.0.2`

## Ursache und Fix

`MSBTS_ReceiveLocation.Enable` und `.Disable` validieren die Transportdaten einer ScheduledTask-Receive-Location. Der Adapter benötigt dafür `Microsoft.BizTalk.Scheduler.dll`. Diese BizTalk-Assembly liegt im BizTalk-Installationsverzeichnis, ist aber nicht in jeder Umgebung im GAC auflösbar. Der Fehler lautete deshalb sinngemäß `Could not load file or assembly Microsoft.BizTalk.Scheduler, Version=3.13.0.0`.

Version 2.3.1 erkennt ScheduledTask-Schritte an Adaptername oder `scheduler:`-URI. Unmittelbar vor der WMI-Mutation sucht sie die Assembly in der lokalen BizTalk-/Adapterinstallation, prüft ihre .NET-Assemblyidentität und lädt sie nur für den laufenden Toolprozess. Weitere angeforderte Abhängigkeiten werden nach derselben Identitätsprüfung aufgelöst. Das Tool kopiert keine Fremd-DLL, registriert nichts und verändert den GAC nicht.

## Vorbereitung

1. Vorhandene `before.json`, Ergebnisdateien und Laufzeitlogs außerhalb des Installationsordners sichern.
2. Setup 2.3.3 als Administrator installieren beziehungsweise aktualisieren.
3. Im Setup-Log `setup_version=2.3.3.0` und erfolgreichen Ziel-Self-Test prüfen.
4. Tool als Administrator starten, den grünen Eintrag `Runtime log storage verified by startup append` prüfen und mit **Log Folder** den dort genannten aktiven Pfad öffnen. Normalfall ist `%ProgramData%\BizTalkPlatformManagementTool\Logs`.
5. Prüfen, dass der lokale BizTalk-Installationsordner `Microsoft.BizTalk.Scheduler.dll` enthält.
6. Nur wenn BizTalk oder der Adapter abweichend installiert wurde: `AdapterAssemblySearchPaths` in `BizTalkPlatformManagementTool.exe.config` um den vorhandenen lokalen Ordner ergänzen. Mehrere Pfade werden mit Semikolon getrennt. Keine DLL aus ACC, einer alten BizTalk-Version oder einem Downloadordner kopieren.

## Kontrollierter Funktionstest

1. **Diagnose** ausführen.
2. **Snapshot Before** ausführen und im Statusgrid die betroffene Receive Location mit Adapter und `scheduler:`-Adresse prüfen.
3. **Dry run** aktiviert lassen und **Shutdown** ausführen.
4. In `shutdown-plan.json` bei der betroffenen Receive Location `AdapterName` und `Address` prüfen.
5. Erst nach Planreview Dry-run deaktivieren, **Shutdown** erneut ausführen und bestätigen.
6. Im Operation Log müssen für den Scheduler-Schritt mindestens folgende Inhalte erscheinen:
   - `ScheduledTask adapter preflight`
   - `ProcessBitness=` und `SearchDirectories=`
   - `ScheduledTask dependency loaded process-locally`, `resolved through CLR/GAC` oder `already loaded`
   - `Calling MSBTS_ReceiveLocation.Disable`
   - `Reached: Disable receive location completed`
7. In `shutdown-result.json` muss der Schritt `Succeeded` oder bei bereits erreichtem Zustand `AlreadySatisfied` sein.
8. Am Drain-Checkpoint Receive-Location-Ergebnisse prüfen, Group Hub/Monitoring leer laufen lassen und erst dann **Yes** wählen.
9. Nach der Wartung **Restore** zunächst im Dry-run, danach real ausführen.
10. Entsprechend `Calling MSBTS_ReceiveLocation.Enable`, den erreichten Zustand und `Succeeded`/`AlreadySatisfied` prüfen.
11. **Snapshot After** und **Compare** ausführen; die Receive Location muss dem gespeicherten Sollzustand entsprechen.

## Logging-Test über Neustart

1. Einen erkennbaren Diagnose- oder Dry-run-Lauf durchführen und Uhrzeit notieren.
2. Tool regulär schließen und erneut starten.
3. Das Operation Log muss die Einträge des vorherigen Prozesses mit vollständigem Datum und Uhrzeit wieder anzeigen.
4. **Clear** leert nur das Grid. Nach erneutem Programmstart wird die aufbewahrte Historie wieder geladen.
5. **Log Folder** muss den lokalen Ordner öffnen.
6. Die aktuelle Tagesdatei heißt `BizTalkPlatformManagementTool-yyyy-MM-dd.log` und enthält den bei diesem Start erzeugten Verifikationseintrag.
7. Nach dem ersten Start an einem Folgetag wird der abgeschlossene Vortag zu `.log.gz` komprimiert.
8. Aktueller Tag plus 29 Vortage bleiben erhalten. Einträge außerhalb dieses Fensters werden beim Start entfernt.
9. Das Grid lädt höchstens die neuesten 10.000 Einträge; die 30-Tage-Dateien bleiben davon unabhängig vollständig erhalten.

ProgramData ist ein separates, üblicherweise ausgeblendetes Windows-Verzeichnis. Im Installationsordner unter Program Files wird im Normalfall kein Log erwartet. Version 2.3.1 prüft ProgramData durch einen echten Schreibzugriff; danach folgen LocalAppData, ein `Logs`-Unterordner im Installationsverzeichnis und Temp. Jeder Fallback oder vollständige Ausfall muss im Grid mit dem betroffenen Pfad und der Exception sichtbar sein.

## Fehlerfall und Supportpaket

Bei einem Fehler keine Assembly austauschen und den GAC nicht spontan verändern. Folgende unveränderte Evidenz sichern:

1. Aktuelle `.log` sowie relevante `.log.gz` aus dem über **Log Folder** geöffneten Ordner.
2. `shutdown-plan.json` oder `restore-plan.json`.
3. `shutdown-result.json`, `restore-result.json` oder den timestamp-basierten Emergency-Report.
4. `before.json` und vorhandenen Nachher-Snapshot.
5. `BizTalkPlatformManagementTool.exe.config`.
6. Screenshot des vollständigen roten Grid-Eintrags und der Umgebung.
7. Dateieigenschaften/Version von `Microsoft.BizTalk.Scheduler.dll`; die Datei selbst nur nach interner Freigabe übermitteln.

Der Fehlerdatensatz enthält Exceptiontyp, HRESULT, innere Ausnahmen, vorhandenes Fusion-Loaderprotokoll, Stacktrace, angeforderte Assembly, anfordernde Assembly und alle geprüften Suchpfade. Damit lässt sich unterscheiden zwischen fehlendem Pfad, falscher BizTalk-Version, nicht passender Strong-Name-Identität, Bitness-/Abhängigkeitsproblem und eigentlichem WMI-Fehler.

## Abnahmekriterien

- ScheduledTask-Receive-Location lässt sich real deaktivieren und wieder auf den Snapshotzustand aktivieren.
- Andere Receive Locations bleiben unverändert funktionsfähig und benötigen keinen Scheduler-Preflight.
- Ein einzelner Fehler bleibt `Failed`, verhindert aber keine späteren unabhängigen Planschritte.
- Ergebnisreport und Nachher-Snapshot werden auch bei einem Teilfehler soweit möglich geschrieben.
- Historisches Log erscheint nach Neustart wieder im Grid.
- Vortagslogs werden komprimiert und exakt 30 Kalendertage aufbewahrt.
- Setup, Tool und Ergebnisdateien melden Version 2.3.3 beziehungsweise `2.3.3-net461`.

Die lokale Mono-Toolchain prüft Resolverlogik, Identitätsgrenze, Persistenz, Kompression und Aufbewahrung ohne BizTalk. Die endgültige Freigabe erfordert diesen realen Windows-/BizTalk-/PROD-Test.