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.