BizTalkPlatformManagementTool/Dokumentation.md

# BizTalk Platform Management Tool Dokumentation

**Stand:** 2026-08-11
**Implementierung:** C# WinForms, .NET Framework 4.6.1
**Archivierte PowerShell-Version:** `archive/powershell/BizTalkPlatformManagementTool.ps1`

## Zweck

Das BizTalk Platform Management Tool unterstützt kontrollierte Wartungsfenster für Microsoft BizTalk Server 2020:

- 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.

## Projektstruktur

- 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`
- 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`

## Code-Dokumentationsstandard

Die vollständige C#-Codebasis in Anwendung, Installer, Packager und Regressionstests ist auf Typ- und Methodenebene mit XML-Dokumentationskommentaren versehen. Methoden dokumentieren ihre Parameter mit `<param>`, generische Typen mit `<typeparam>` und Rückgabewerte mit `<returns>`, soweit jeweils vorhanden. Die Release-Konfiguration jedes Projekts erzeugt zusätzlich eine XML-Dokumentationsdatei im jeweiligen `bin\Release`-Verzeichnis. Dadurch prüft der Compiler Syntax und Referenzen der öffentlichen Dokumentation bei jedem Release-Build.

Deutsche Inline-Kommentare stehen gezielt an Stellen, deren Zweck nicht allein aus dem Code hervorgeht. Dazu zählen insbesondere:

- sichere Shutdown-/Restore-Reihenfolge und Schutz gebundener Orchestrierungen,
- WMI-Auflösung über breite Abfrage mit clientseitigem Filter,
- atomare JSON-Ersetzung auf demselben Volume,
- Neutralisierung formelartiger CSV-Werte,
- Persistenz eines Operationsplans vor der Benutzerbestätigung,
- Staging-, Aktivierungs-, Quarantäne- und Rollbackgrenzen des Installers,
- begrenzte Self-Test-Prozess- und Streambehandlung.

Selbsterklärende Zuweisungen und reine UI-Konstruktion werden nicht zeilenweise kommentiert. Kommentare sollen die fachliche Begründung, Sicherheitsgrenze oder Plattformbesonderheit festhalten und nicht lediglich den unmittelbar sichtbaren Code wiederholen.

## UI Workflow

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 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.

## Sicherheitsdesign

- 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 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 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.
- 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.
- 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

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.

## Restore-Reihenfolge

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.

## Restore-Grenzen

- 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.

## Ausgabedateien

- 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: `%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 ü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; kurzzeitige Rename-Sperren werden mit acht begrenzten Versuchen und insgesamt höchstens 19,75 Sekunden Backoff behandelt.
7. Aktivierte EXE erneut per `--self-test` prüfen.
8. Erst danach Startmenü, optionale Desktop-Verknüpfung und Windows-Uninstall-Eintrag schreiben.
9. Windows-Integration durch Rücklesen der Verknüpfungen und der wesentlichen Registrywerte verifizieren.
10. Bei einem Fehler nach der ersten Mutation die neue Version entfernen und das Backup einschließlich Windows-Integration wiederherstellen.

Fehler vor der ersten Mutation werden als **Kein Rollback erforderlich** ausgewiesen. Ein Rollback wird nur als erfolgreich bezeichnet, wenn seine einzelnen Schritte ohne Fehler abgeschlossen wurden; ein verbliebenes Backup ohne aktives Programmverzeichnis verletzt eine zusätzlich geprüfte Invariante und wird als unvollständiger Rollback gemeldet. Bereinigungsprobleme an einem nicht mehr benötigten Backup oder Deinstallations-Quarantäneverzeichnis werden als erfolgreiche Operation mit Warnung protokolliert und zerstören die wiederherstellbaren Dateien nicht blind.

Wenn ausschließlich die atomare Staging-Umbenennung einer Neuinstallation dauerhaft gesperrt bleibt, ist ein eng begrenzter Kopierfallback zulässig: Es existiert dabei keine aktive Vorversion, jede Zieldatei wird erneut anhand des Manifests per SHA-256 geprüft und der zweite Self-Test läuft weiterhin aus dem endgültigen Ziel. Updates verwenden diesen Fallback absichtlich nicht, weil die unveränderte alte Installation Vorrang vor einer nicht atomaren In-place-Aktualisierung hat. Jeder Retry und die verwendete Aktivierungsmethode stehen im Setup-Log.

Das dauerhafte Setup-Log enthält pro Lauf einen Kontextkopf mit Version, Betriebssystem, 32-/64-Bit-Kontext, CLR, Rechner, Identität und Elevation. Hinzu kommen Pfade, freier Speicher, Dateiversion/-größe/-SHA-256, vollständige Self-Test-Ausgaben mit Exitcode, Exception-Ketten mit HRESULT und Stacktrace sowie jeder Rollbackschritt. Stabile `SETUP-*`- und `UNINSTALL-*`-Fehlercodes ermöglichen die Zuordnung unabhängig vom lokalisierten Meldungstext. Die Aufbewahrung beträgt 90 Tage. Wenn ProgramData für die Diagnose nicht verfügbar ist, wird ein Temp-Fallback verwendet und sichtbar gemeldet; die Schaltfläche **Diagnoselogs öffnen** öffnet den regulären Ablageort.

Der Self-Test ist eine technische Installationsabnahme ohne BizTalk-WMI. Ein fachlicher Umgebungszustand wie fehlender WMI-Zugriff oder `Unknown` führt deshalb nicht zum Installer-Rollback. Nach erfolgreicher Installation bleiben **Diagnose** und ein Dry-run gegen das Zielsystem verpflichtende Abnahmeschritte.

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.
- Erholung nach einer vorübergehenden Rename-Sperre mit korrektem Backoff und Diagnoseereignissen.
- Verifizierter Kopierfallback einer dauerhaft move-gesperrten Neuinstallation.
- Begrenzter Abbruch eines dauerhaft move-gesperrten Updates ohne Veränderung der Vorversion.
- Wiederherstellung der Vorversion, wenn der Self-Test nach Aktivierung fehlschlägt.
- Deinstallation durch atomare Umbenennung des Programmverzeichnisses vor der bestmöglichen Bereinigung.
- Eindeutige Fehlerphase ohne irreführende Rollbackmeldung bei einem Staging-Fehler.
- Vollständiger Diagnosekontext mit Exception-Kette und Temp-Fallback für das Setup-Log.
- Unabhängigkeit der Installation von Fehlern der UI-Fortschrittsanzeige.

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

- `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`

## Anforderungen

- 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