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. BizTalk-Servernamen eintragen.
2. Ausgabeverzeichnis wählen.
3. Dry run aktiviert lassen.
4. Mit Diagnose den Zugriff auf root\MicrosoftBizTalkServer prüfen.
5. Mit Snapshot Before die Datei before.json erzeugen.
6. Mit Shutdown den Plan shutdown-plan.json erzeugen und prüfen.
7. Dry run erst deaktivieren, wenn der Plan korrekt ist.
8. Nach der Wartung mit Restore aus before.json wiederherstellen.
9. Mit Snapshot After und Compare die Umgebung validieren.

Sicherheitsdesign

• Dry-run ist standardmäßig aktiviert.
• 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.
• 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
• Visual Studio mit .NET Framework 4.6.1 Developer Pack für Builds