AI-Maintainer-Handoff

Projekt und Sicherheitsziel

Das Repository enthält ein .NET-Framework-4.6.1-WinForms-Tool für kontrollierte BizTalk-2020-Wartungsoperationen. Änderungen müssen Dry-run, explizite Freigabe realer Aktionen, sichere Reihenfolgen und wiederherstellbare Installergrenzen erhalten. Die aktuelle Produktversion ist 2.3.3.

Installerinvarianten

Vor der ersten Mutation müssen Manifest, Länge, SHA-256 und Staging-Self-Test erfolgreich sein.
Eine laufende installierte Anwendung blockiert Update und Deinstallation.
Ein Update darf die aktive Vorversion erst nach erfolgreichem Staging verändern.
Das Backup einer bestehenden Installation wird nur atomar per Directory.Move erzeugt. Bei dauerhaftem Fehler bleibt die Vorversion aktiv; es gibt keinen In-place-Kopierfallback.
Nach ausgeschöpften Aktivierungs-Move-Retries darf eine erneut SHA-256-geprüfte Kopie nur in ein nicht vorhandenes Ziel geschrieben werden: bei einer Neuinstallation oder nachdem eine Update-Vorversion vollständig atomar ins Backup verschoben wurde.
Nach jeder Aktivierungsart läuft der Self-Test erneut aus dem endgültigen Installationsziel.
Sobald ein Zielverzeichnis teilweise angelegt sein kann, muss activated=true gesetzt sein, damit der Catch-Pfad es entfernt.
Scheitert der Ziel-Self-Test nach einem Update-Kopierfallback, muss die teilweise neue Version entfernt und das atomare Backup wieder als aktives Verzeichnis eingesetzt werden.
Windows-Integration wird erst nach bestandenem Ziel-Self-Test verändert und bei Folgefehlern aus dem Snapshot restauriert.
Startmenü-Link, Uninstaller und Uninstall-Registry sind verpflichtend; Fehler müssen weiterhin den vollständigen Rollback auslösen.
Der gemeinsame Desktop-Link ist optional und standardmäßig abgewählt. Snapshot, Erstellen/Entfernen, Validierung, Rollback und Uninstall müssen jeden Fehler als sichtbare Warnung isolieren und dürfen keine Kernoperation abbrechen.
Diagnose-Logging darf das eigentliche Setup-Ergebnis nie ersetzen.

Die zentrale Implementierung liegt in src/BizTalkPlatformManagementTool.Setup/InstallerEngine.cs. Move-Retries sind auf acht Versuche und 19,75 Sekunden Wartezeit begrenzt. Die injizierbaren directoryMover- und retryDelay-Delegates existieren ausschließlich, damit Sperrpfade ohne echte Wartezeit portabel getestet werden können.

Runtime- und Recovery-Invarianten

Ein isolierter WMI-, Adapter- oder Servicefehler darf keine späteren unabhängigen Planschritte verhindern.
Teilfehler werden vollständig pro Schritt persistiert; der Gesamtlauf bleibt sichtbar fehlgeschlagen und darf nicht als Erfolg ausgegeben werden.
Vor jeder Mutation wird der aktuelle Zustand geprüft. Bereits erreichte Sollzustände werden ohne Methodenaufruf als AlreadySatisfied erfasst.
Der Nachher-Snapshot wird unabhängig von Einzelfehlern versucht; sein Fehler gehört in denselben Ergebnisreport.
Die Runtime-WMI-Klassen liefern keine verlässliche Application-Zuordnung. BizTalkApplicationResolver liest deshalb die Management-DB-Position aus MSBTS_GroupSetting und indiziert die read-only ExplorerOM-Anwendungshierarchie. WMI bleibt Quelle für Zustand und Mutationen; ExplorerOM wird ohne Compile-time-Abhängigkeit und nur mit geprüfter Microsoft-Assemblyidentität geladen.
Scheitert die Katalogauflösung, bleibt die WMI-Zustandserfassung verfügbar, aber alle betroffenen Artefakte werden sichtbar unter (Unknown Application) gruppiert und Diagnose, Grid sowie Laufzeitlog müssen eine verwertbare Warnung ausgeben.
Shutdown-Kategorien gelten global über alle Anwendungen: Receive Locations, Orchestrations, Send Ports, Host Instances.
Zwischen der globalen Receive-Location-Phase und allen späteren Shutdown-Kategorien liegt ein persistierter Operator-Checkpoint. Ein realer Lauf darf nur nach explizitem Continue fortsetzen; Stop oder Handlerfehler markiert alle späteren Zeilen als NotExecuted und arbeitet fail-closed.
Dry-run zeigt den Checkpoint ohne Callback. Der Ergebnisreport muss Entscheidung, Zeitpunkt, OperatorStopped und NotExecutedCount dauerhaft enthalten.
Ein BizTalk-Application-Stop wird nicht zusätzlich ausgeführt: Partially Started ist während des Drains erwartbar, während Application-Stop-Optionen eine breitere, teils destruktive Semantik als das reine Setzen eines Statuswerts besitzen.
Restore-Kategorien gelten global über alle Anwendungen: Host Instances, Send Ports, Orchestrations, Receive Locations.
Emergency Restore überschreibt niemals die Eingabe-before.json, erzeugt eine timestamp-basierte Kopie und stellt ENTSSO vor Host Instances sicher.
Emergency Restore muss mit genau einer validen before.json funktionieren; Dateien eines vorherigen fehlgeschlagenen Laufs dürfen keine Voraussetzung sein.
Ein älterer kompatibler Snapshot, insbesondere aus 2.1.3, darf nicht allein anhand seines ToolVersion-Werts abgelehnt werden.
Der echte Emergency Restore erzeugt nach Möglichkeit automatisch einen timestamp-basierten Soll/Ist-Diff aus Recovery-Quelle und Nachher-Snapshot.
Die zentrale best-effort Orchestrierung liegt in OperationPlanExecutor; die WMI-/Service-Zustandsprüfung bleibt im produktiven Runtime-Adapter.
Datei-Logging und optionale GUI-Logweiterleitung sind Diagnosekanäle und dürfen niemals einen fachlichen Planschritt oder dessen Fehlerbehandlung unterbrechen.
Ein Laufzeitlogpfad gilt erst nach erfolgreichem Create/Write/Flush/Delete-Test als verfügbar. Die Reihenfolge ProgramData, LocalAppData, EXE-Logs, Temp ist stabil; ein Append-Fehler muss denselben Datensatz auf dem nächsten Kandidaten erneut versuchen.
Fallback und Totalausfall des Dateiloggings müssen mit Pfad und Exception im Grid sichtbar sein. Jeder GUI-Start persistiert einen Verifikationsdatensatz; der WMI-freie Self-Test prüft einen vollständigen Log-Write/Read-Roundtrip.
Scheduler-Preflight darf nur für Receive Locations mit passendem Adaptername oder scheduler:-URI laufen; normale Adapter dürfen keine zusätzliche Abhängigkeit erhalten.
Adapter-DLLs dürfen nur aus explizit konfigurierten, per Registry erkannten oder konventionellen Produktverzeichnissen und nur nach vollständiger Assemblyidentitätsprüfung geladen werden. Der Toolprozess verändert niemals den GAC.
Laufzeitlogs halten 30 Kalendertage, komprimieren abgeschlossene Tage und rehydrieren maximal 10.000 neue Einträge ins Grid. Ein Archiv-/Lesefehler darf keine BizTalk-Operation beeinflussen.

Versionierung

Bei einem Release sind mindestens diese Stellen konsistent zu ändern:

InstallerEngine.ProductVersion
Setup-Titel in MainForm
beide Properties/AssemblyInfo.cs
beide app.manifest
BizTalkOperationService.Version
CHANGELOG.md

Verifikation

Portable Befehle:

msbuild BizTalkPlatformManagementTool.sln /t:Rebuild /p:Configuration=Release '/p:Platform=Any CPU' /m:1
mono tests/BizTalkPlatformManagementTool.Tests/bin/Release/BizTalkPlatformManagementTool.Tests.exe
mono src/BizTalkPlatformManagementTool/bin/Release/BizTalkPlatformManagementTool.exe --self-test
mono src/BizTalkPlatformManagementTool.Packager/bin/Release/BizTalkPlatformManagementTool.Packager.exe . Release

Nach der Paketierung müssen ZIP, Base64-TXT und SHA-256-Datei gegengeprüft werden. Die abschließende Freigabe braucht zusätzlich einen repräsentativen Windows-/ACC-Test von UAC, Program Files-ACL/EDR, Registry, Verknüpfungen, Update, Rollback und Deinstallation sowie BizTalk-Diagnose und Dry-run.

7.4 KiB Raw Blame History