BizTalkPlatformManagementTool/Dokumentation.md

# BizTalk Platform Management Tool Dokumentation

**Stand:** 2026-04-27
**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`
- PowerShell-Archiv: `archive/powershell/BizTalkPlatformManagementTool.ps1`

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

## 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 neben der EXE: `BizTalkPlatformManagementTool-yyyy-MM-dd.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.

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