Add transactional installer and harden runtime operations

Dokumentation.md

@@ -1,6 +1,6 @@
 # BizTalk Platform Management Tool Dokumentation
 
-**Stand:** 2026-04-27
+**Stand:** 2026-08-11
 **Implementierung:** C# WinForms, .NET Framework 4.6.1
 **Archivierte PowerShell-Version:** `archive/powershell/BizTalkPlatformManagementTool.ps1`
 
@@ -21,6 +21,10 @@ Das BizTalk Platform Management Tool unterstützt kontrollierte Wartungsfenster
 - UI: `src/BizTalkPlatformManagementTool/Ui/MainForm.cs`
 - WMI-Zugriff: `src/BizTalkPlatformManagementTool/Services/BizTalkWmiClient.cs`
 - Operationslogik: `src/BizTalkPlatformManagementTool/Services/BizTalkOperationService.cs`
+- Snapshot-Validierung: `src/BizTalkPlatformManagementTool/Services/SnapshotValidator.cs`
+- Installer: `src/BizTalkPlatformManagementTool.Setup`
+- Release-Paketierung: `src/BizTalkPlatformManagementTool.Packager`
+- Regressionstests: `tests/BizTalkPlatformManagementTool.Tests`
 - PowerShell-Archiv: `archive/powershell/BizTalkPlatformManagementTool.ps1`
 
 ## UI Workflow
@@ -42,9 +46,9 @@ Die Statusanzeige rechts im Kopfbereich bewertet die Host-Instance-Zustaende des
 
 - Dry-run ist standardmäßig aktiviert.
 - Beim Start wird geprüft, ob die Anwendung mit Administratorrechten läuft. Ohne erhöhte Rechte wird eine Fehlermeldung angezeigt und die Anwendung beendet.
-- Echte Shutdown-/Restore-Aktionen verlangen bei deaktiviertem Dry-run eine zusätzliche Bestätigung.
+- Echte Shutdown-/Restore-Aktionen verlangen erst nach Erzeugung und Speicherung des frischen Plans eine zusätzliche Bestätigung mit Zielserver, Plandatei und exakter Zahl ausführbarer Schritte.
 - Jede Operation schreibt Einträge in das sichtbare Operation Log.
-- Zusätzlich wird neben der EXE eine tägliche Logdatei `BizTalkPlatformManagementTool-yyyy-MM-dd.log` geschrieben.
+- Zusätzlich wird unter `%ProgramData%\BizTalkPlatformManagementTool\Logs` eine tägliche Logdatei `BizTalkPlatformManagementTool-yyyy-MM-dd.log` geschrieben. Nur wenn ProgramData nicht verfügbar ist, wird auf das EXE-Verzeichnis zurückgefallen.
 - Logdateien werden rollierend für den aktuellen Tag plus vier vorherige Tage vorgehalten.
 - Der Kopfbereich zeigt den zuletzt erkannten Umgebungsstatus aus den Host Instances.
 - Operationspläne werden vor Laufzeitänderungen gespeichert.
@@ -52,6 +56,9 @@ Die Statusanzeige rechts im Kopfbereich bewertet die Host-Instance-Zustaende des
 - Wartezeiten nutzen konfigurierbare Timeout- und Polling-Werte.
 - Host Instances auf anderen Servern werden übersprungen und als Warnung protokolliert.
 - Echte Shutdown-/Restore-Schritte protokollieren WMI-Klasse, Schlüssel, Zielobjekt und Methode, damit Fehler wie WMI-Query- oder Methodenfehler eindeutig zugeordnet werden können.
+- Restore-Pläne werden abgelehnt, wenn Snapshot-Server und ausgewählter Zielserver nicht übereinstimmen; Kurzname und FQDN desselben Hosts gelten als identisch.
+- Pro Windows-Sitzung ist nur eine Toolinstanz zulässig; das Fenster kann während einer aktiven WMI-Operation nicht geschlossen werden.
+- Die EXE enthält zusätzlich einen WMI-freien `--self-test`, den der Installer vor und nach der Aktivierung ausführt.
 
 ## Shutdown-Reihenfolge
 
@@ -81,13 +88,53 @@ Die Statusanzeige rechts im Kopfbereich bewertet die Host-Instance-Zustaende des
 - Nachher-Snapshots: `shutdown-after.json`, `restore-after.json`
 - Diff: `diff.json`, `diff.csv`, `diff.html`
 - Snapshot-Reports: `*.csv`, `*.hosts.csv`, `*.html`
-- Laufzeitlogs neben der EXE: `BizTalkPlatformManagementTool-yyyy-MM-dd.log`
+- Laufzeitlogs: `%ProgramData%\BizTalkPlatformManagementTool\Logs\BizTalkPlatformManagementTool-yyyy-MM-dd.log`
+- Installerlogs: `%ProgramData%\BizTalkPlatformManagementTool\InstallerLogs\setup-*.log`
 
 ## Fehleranalyse
 
 Bei echten Shutdown- und Restore-Aktionen wird jeder Schritt vor der Ausführung mit Artefakttyp, WMI-Klasse, Schlüsselproperty, Schlüsselwert und Methodenname protokolliert. Die Objektauflösung verwendet eine breite `SELECT * FROM <class>`-Abfrage und filtert danach im Prozess auf den Schlüsselwert. Dadurch können Host-Instance-Namen und andere BizTalk-Namen mit Sonderzeichen keine ungültige WMI-WQL-`WHERE`-Query mehr erzeugen.
 
-Snapshot- und Plan-JSON-Dateien werden als UTF-8 ohne BOM geschrieben. Beim Laden werden vorhandene Dateien mit UTF-8-BOM oder durch Encoding-Konvertierung sichtbar gewordenem BOM-Marker toleriert.
+Snapshot- und Plan-JSON-Dateien werden als UTF-8 ohne BOM über eine temporäre Datei im Zielverzeichnis und anschließenden atomaren Austausch geschrieben. Beim Laden werden vorhandene Dateien mit UTF-8-BOM oder durch Encoding-Konvertierung sichtbar gewordenem BOM-Marker toleriert. Deserialisierte Snapshots werden normalisiert und auf leere Namen, Duplikate und fehlende Strukturen geprüft.
+
+Diffs verwenden den zusammengesetzten Schlüssel aus Anwendung und Artefaktname. Gleichnamige Artefakte in verschiedenen BizTalk-Anwendungen überschreiben sich daher nicht mehr. CSV-Werte mit Präfix `=`, `+`, `-`, `@` oder Tab werden mit einem Apostroph neutralisiert, damit Tabellenkalkulationen sie nicht als Formel ausführen.
+
+WMI-Abfrageobjekte sowie Rückgabeobjekte von WMI-Methoden werden deterministisch freigegeben. Polling wartet am Timeout-Ende nur noch für die tatsächlich verbleibende Zeit.
+
+## Installer- und Updatearchitektur
+
+Das Releasepaket enthält `Setup.exe`, `application.manifest`, den Payload-Ordner `application` und die Installationsanleitung. Vor jeder Änderung prüft der Installer, dass jede Payload-Datei vollständig im Manifest enthalten ist und Länge sowie SHA-256 entsprechen. Nicht deklarierte Zusatzdateien führen zum Abbruch.
+
+Die Aktivierung ist transaktional aufgebaut:
+
+1. Payload validieren.
+2. Eindeutiges Staging-Verzeichnis neben dem Installationsziel erstellen.
+3. Kopierte Dateien nochmals per SHA-256 und die Staging-EXE per `--self-test` prüfen.
+4. Laufende Toolinstanz ausschließen.
+5. Bestehendes Verzeichnis in ein eindeutiges Backup verschieben.
+6. Staging auf demselben Volume als produktives Verzeichnis aktivieren.
+7. Aktivierte EXE erneut per `--self-test` prüfen.
+8. Erst danach Startmenü, optionale Desktop-Verknüpfung und Windows-Uninstall-Eintrag schreiben.
+9. Bei einem Fehler die neue Version entfernen und das Backup einschließlich Windows-Integration wiederherstellen.
+
+Das äußere ZIP erhält zusätzlich eine SHA-256-Datei und eine Certutil-kompatible Base64-TXT-Datei. Diese äußere Prüfsumme erkennt Übertragungsfehler; sie ist keine digitale Herausgebersignatur. Details und Befehle stehen in `Installation.md`.
+
+## Automatisierte Verifikation
+
+`tests/BizTalkPlatformManagementTool.Tests` prüft derzeit:
+
+- Atomare JSON-Aktualisierung und BOM-Kompatibilität.
+- Anwendungsbezogene Diff-Identität bei gleichnamigen Artefakten.
+- Restore-Servergrenze und sichere Restore-Reihenfolge.
+- Neutralisierung formelartiger CSV-Werte.
+- Erkennung manipulierter Payload-Dateien.
+- Ablehnung nicht deklarierter Dateien und aus dem Payload-Verzeichnis ausbrechender Manifestpfade.
+- Staging-Fehler ohne Mutation einer bestehenden Installation.
+- Erfolgreiche Staging-Aktivierung.
+- Wiederherstellung der Vorversion, wenn der Self-Test nach Aktivierung fehlschlägt.
+- Deinstallation durch atomare Umbenennung des Programmverzeichnisses vor der bestmöglichen Bereinigung.
+
+Der portable Build, die Tests, der Anwendungsselftest und die Paketkonsistenz sind lokal unter Mono prüfbar. Die endgültige Freigabe erfordert zusätzlich einen Windows-Test von UAC, Registry, Verknüpfungen und Setup-Rollback sowie einen repräsentativen BizTalk-2020-Test von Diagnose, Dry-run, Shutdown und Restore.
 
 ## Status Mapping