Harden BizTalk maintenance workflow and add installer

Dokumentation.md

@@ -1,105 +1,159 @@
-# BizTalk Platform Management Tool Dokumentation
+# Technische Dokumentation
 
-**Stand:** 2026-04-27
-**Implementierung:** C# WinForms, .NET Framework 4.6.1
-**Archivierte PowerShell-Version:** `archive/powershell/BizTalkPlatformManagementTool.ps1`
+**Stand:** 2026-08-06
 
-## Zweck
+**Version:** 2.1.0
 
-Das BizTalk Platform Management Tool unterstützt kontrollierte Wartungsfenster für Microsoft BizTalk Server 2020:
+**Technik:** C# WinForms, .NET Framework 4.6.1
 
-- Exakten Laufzeitstatus vor einer Wartung erfassen.
-- Receive Locations, Orchestrations, Send Ports und Host Instances in definierter Reihenfolge herunterfahren.
-- Den Laufzeitstatus aus einer gespeicherten `before.json` wiederherstellen.
-- Den Status nach der Wartung erfassen und beide Snapshots vergleichen.
-- Plan- und Ergebnisdateien für Review, Audit und Nachvollziehbarkeit schreiben.
+## Ziel und Sicherheitsprinzip
 
-## Projektstruktur
+Das Tool unterstützt geplante BizTalk-Wartungen, ohne den fachlich gewünschten
+Ausgangszustand zu verlieren. Der Vorher-Snapshot ist die einzige Quelle für
+den Restore. Das bedeutet insbesondere:
 
-- Solution: `BizTalkPlatformManagementTool.sln`
-- Projekt: `src/BizTalkPlatformManagementTool/BizTalkPlatformManagementTool.csproj`
-- UI: `src/BizTalkPlatformManagementTool/Ui/MainForm.cs`
-- WMI-Zugriff: `src/BizTalkPlatformManagementTool/Services/BizTalkWmiClient.cs`
-- Operationslogik: `src/BizTalkPlatformManagementTool/Services/BizTalkOperationService.cs`
-- PowerShell-Archiv: `archive/powershell/BizTalkPlatformManagementTool.ps1`
+- Nur Artefakte, die im Snapshot aktiv waren, werden heruntergefahren.
+- Nur Artefakte, die im Snapshot aktiv waren, werden wieder gestartet.
+- Zuvor gestoppte, gebundene oder deaktivierte Artefakte werden beim Restore nicht verändert.
+- Ein vorhandener Vorher-Snapshot wird durch **Herunterfahren** nicht ersetzt.
+- Snapshot und Zielserver müssen übereinstimmen; Kurzname und FQDN desselben Servers werden akzeptiert.
+- Bei mehrdeutiger WMI-Auflösung wird abgebrochen, statt möglicherweise das falsche Objekt zu verändern.
 
-## UI Workflow
+## Oberfläche
 
-1. Anwendung mit Administratorrechten starten.
-2. BizTalk-Servernamen eintragen.
-3. Ausgabeverzeichnis wählen.
-4. **Dry run** aktiviert lassen.
-5. Mit **Diagnose** den Zugriff auf `root\MicrosoftBizTalkServer` prüfen.
-6. Mit **Snapshot Before** die Datei `before.json` erzeugen.
-7. Mit **Shutdown** den Plan `shutdown-plan.json` erzeugen und prüfen.
-8. **Dry run** erst deaktivieren, wenn der Plan korrekt ist.
-9. Nach der Wartung mit **Restore** aus `before.json` wiederherstellen.
-10. Mit **Snapshot After** und **Compare** die Umgebung validieren.
+Die Oberfläche führt von links nach rechts durch sechs Schritte:
 
-Die Statusanzeige rechts im Kopfbereich bewertet die Host-Instance-Zustaende des letzten Snapshots und zeigt `Started`, `Stopped`, `Partial` oder `Unknown`. **Clear** leert die sichtbaren Ergebnis- und Log-Grids, loescht aber keine Dateien. **Close** beendet die Anwendung.
+1. **Verbindung prüfen**
+2. **Zustand erfassen**
+3. **Herunterfahren**
+4. **Wiederherstellen**
+5. **Nachher erfassen**
+6. **Vergleichen**
 
-## Sicherheitsdesign
+Kopfbereich, Status-Badge, einheitliche Eingabefelder, gleich große
+Workflow-Schaltflächen, farblich getrennte destruktive und wiederherstellende
+Aktionen sowie responsive Ergebnis- und Logtabellen sorgen für eine klare
+Bedienung auch bei kleineren Bildschirmgrößen und DPI-Skalierung.
 
-- 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.
-- 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.
-- 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.
-- WMI-Methodenrückgaben werden geprüft.
-- 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.
+Der Dry-run ist standardmäßig aktiviert. Bei echten Änderungen zeigt die
+Statusleiste einen roten Hinweis und jede Änderung verlangt eine zusätzliche
+Bestätigung mit Zielserver und verwendeter Zustandsdatei. Während einer
+Operation sind Eingaben gesperrt; das Fenster kann nicht versehentlich
+geschlossen werden.
 
-## Shutdown-Reihenfolge
+## Erfasster Zustand
 
-1. Receive Locations deaktivieren, die im Snapshot aktiviert waren.
-2. Orchestrations stoppen, die gestartet waren.
-3. Send Ports stoppen, die gestartet waren.
-4. Host Instances stoppen, die auf dem ausgewählten Server gestartet waren.
+Über `root\MicrosoftBizTalkServer` werden gelesen:
 
-## Restore-Reihenfolge
+| WMI-Klasse | Relevanter Zustand |
+| --- | --- |
+| `MSBTS_ReceiveLocation` | `IsDisabled`, Name, Receive Port, Adapter |
+| `MSBTS_SendPort` | `Status`, Name, Adaptertyp |
+| `MSBTS_Orchestration` | `OrchestrationStatus`, Name und Assembly-Identität |
+| `MSBTS_HostInstance` | `ServiceState`, Hostname und ausführender Server |
 
-1. Host Instances starten, die auf dem ausgewählten Server zuvor gestartet waren.
-2. Send Ports wiederherstellen.
-3. Orchestrations wiederherstellen, soweit dies sicher möglich ist.
-4. Receive Locations zuletzt wiederherstellen.
+Transportadressen werden bewusst nicht persistiert. Sie sind für Start/Stop
+nicht erforderlich und können Benutzerinformationen, Kennwörter oder andere
+sensible Bestandteile enthalten.
 
-## Restore-Grenzen
+## Zustandswerte
 
-- Send Ports werden auf `Started`, `Stopped` oder `Bound` zurückgesetzt.
-- Orchestrations mit Status `Started`, `Stopped` oder `Unbound` werden direkt behandelt.
-- Orchestrations mit Status `Bound` bleiben unverändert und werden zur manuellen Prüfung markiert, weil ein blindes Unenlist zu `Unbound` führen kann.
-- Receive Locations werden zuletzt aktiviert, damit eingehender Verkehr erst nach Host Instances und abhängigen Artefakten wieder aufgenommen wird.
+- Send Port: `1=Bound`, `2=Stopped`, `3=Started`
+- Orchestrierung: `1=Unbound`, `2=Bound`, `3=Stopped`, `4=Started`
+- Hostinstanz: `1=Stopped`, `2=StartPending`, `3=StopPending`, `4=Running`
+- Receive Location: `Enabled = !IsDisabled`
 
-## Ausgabedateien
+Weitere Host-Servicezustände werden als unbekannt angezeigt und nicht
+automatisch als gestartet behandelt.
 
-- Snapshots: `before.json`, `after.json`
-- Operationspläne: `shutdown-plan.json`, `restore-plan.json`
-- 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`
+## Shutdown-Plan
 
-## Fehleranalyse
+1. Alle im Snapshot aktivierten Receive Locations deaktivieren.
+2. Alle im Snapshot gestarteten Orchestrierungen kontrolliert stoppen.
+3. Alle im Snapshot gestarteten Send Ports stoppen.
+4. Alle im Snapshot gestarteten Hostinstanzen des ausgewählten Servers stoppen.
 
-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.
+Hostinstanzen anderer BizTalk-Knoten erscheinen als übersprungene Hinweise.
+Damit kann derselbe Gruppen-Snapshot nachvollziehbar bleiben, ohne remote
+Hostinstanzen versehentlich vom falschen Knoten aus zu verändern.
 
-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.
+## Restore-Plan
 
-## Status Mapping
+1. Zuvor gestartete Hostinstanzen starten.
+2. Zuvor gestartete Send Ports starten.
+3. Zuvor gestartete Orchestrierungen starten.
+4. Zuvor aktivierte Receive Locations zuletzt aktivieren.
 
-- `MSBTS_SendPort.Status`: `1=Bound`, `2=Stopped`, `3=Started`
-- `MSBTS_Orchestration.OrchestrationStatus`: `1=Unbound`, `2=Bound`, `3=Stopped`, `4=Started`
-- `MSBTS_ReceiveLocation`: `Enabled = !IsDisabled`
-- `MSBTS_HostInstance.ServiceState`: `1=Stopped`, `2=StartPending`, `3=StopPending`, `4=Started`
+Gestoppte oder gebundene Send Ports, gestoppte/gebundene/ungebundene
+Orchestrierungen, deaktivierte Receive Locations und gestoppte Hostinstanzen
+erzeugen keine Restore-Aktion.
 
-## Anforderungen
+## Eindeutige WMI-Auflösung
 
-- Windows Server oder Administrationshost mit .NET Framework 4.6.1
-- BizTalk Server 2020 oder installierte BizTalk Administration Tools
-- Berechtigungen auf den WMI-Namespace `root\MicrosoftBizTalkServer`
-- Lokale Administratorrechte und Start der Anwendung mit **Als Administrator ausführen**
-- Visual Studio mit .NET Framework 4.6.1 Developer Pack für Builds
+WMI-Abfragen werden ohne dynamisch zusammengesetzte WQL-`WHERE`-Klauseln
+ausgeführt. Die Filterung erfolgt im Prozess und behandelt Sonderzeichen in
+Namen sicher. Zusätzlich werden verwendet:
+
+- Receive Location: `Name` plus `ReceivePortName`
+- Orchestrierung: `Name` plus `AssemblyName`
+- Hostinstanz: `InstanceName` plus `RunningServer`
+
+Die vollständige Assembly-Identität einer Orchestrierung wird im Snapshot und
+beim Vergleich berücksichtigt. Liefert WMI trotz der Qualifier mehrere
+Treffer, wird die Operation mit einer eindeutigen Fehlermeldung abgebrochen.
+Jeder Schritt prüft vor dem Methodenaufruf den aktuellen Zustand. Bereits
+erreichte Zielzustände werden protokolliert und übersprungen; dadurch können
+teilweise ausgeführte Pläne nach einer Fehlerkorrektur sicher erneut gestartet
+werden.
+
+## Dateisicherheit
+
+JSON-Dateien werden zunächst vollständig in eine temporäre Datei geschrieben,
+auf den Datenträger gespült und anschließend atomar ersetzt. Leere Dateien und
+Dateien über 16 MiB werden verworfen. UTF-8 mit und ohne BOM sowie der sichtbare
+BOM-Marker älterer Konvertierungen werden beim Lesen toleriert.
+
+Vergleiche verwenden zusammengesetzte Identitäten. Gleichnamige Artefakte in
+unterschiedlichen Anwendungen, Receive Ports oder Assembly-Versionen werden
+nicht miteinander vermischt.
+
+## Verzeichnisse
+
+```text
+%ProgramFiles%\BizTalkPlatformManagementTool\
+  BizTalkPlatformManagementTool.exe
+  BizTalkPlatformManagementTool.exe.config
+
+%ProgramData%\BizTalkPlatformManagementTool\
+  Wartungen\
+  Logs\
+```
+
+Die Trennung verhindert, dass ein Update Zustandsdateien überschreibt, und
+ermöglicht normale Logrotation außerhalb des geschützten Programmverzeichnisses.
+Logs werden für den aktuellen Tag und vier vorherige Tage aufbewahrt.
+
+## Installer und Rollback
+
+Der .NET-Installer benötigt keine PowerShell. Er validiert die Assembly, baut
+ein Staging-Verzeichnis auf, verschiebt eine bestehende Installation in ein
+Backup und aktiviert anschließend die neue Version. Bei einem Fehler wird das
+Backup zurückverschoben. Startmenü- und optionale Desktop-Verknüpfung werden
+systemweit angelegt.
+
+Der Release-Packager erzeugt den Installationsordner, ein ZIP, eine
+Base64-Transportdatei und eine SHA-256-Datei.
+
+## Tests
+
+Die Regressionstests prüfen:
+
+- Restore enthält ausschließlich zuvor aktive Artefakte.
+- Shutdown enthält ausschließlich zuvor aktive Artefakte.
+- Receive Locations erhalten ihren zusätzlichen WMI-Qualifier.
+- Vergleiche trennen gleichnamige Artefakte verschiedener Anwendungen.
+- fremde Server-Snapshots werden abgewiesen.
+- atomarer JSON-Ersatz hinterlässt keine temporären Dateien.
+
+Ein echter WMI-Integrationstest muss auf einem BizTalk-2020-System im Dry-run
+und anschließend in einem freigegebenen Wartungsfenster erfolgen.