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

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

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