BizTalkPlatformManagementTool/Dokumentation.md

Technische Dokumentation

Stand: 2026-08-06

Version: 2.1.0

Technik: C# WinForms, .NET Framework 4.6.1

Ziel und Sicherheitsprinzip

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:

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

Oberfläche

Die Oberfläche führt von links nach rechts durch sechs Schritte:

1. Verbindung prüfen
2. Zustand erfassen
3. Herunterfahren
4. Wiederherstellen
5. Nachher erfassen
6. Vergleichen

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.

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.

Erfasster Zustand

Über root\MicrosoftBizTalkServer werden gelesen:

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

Transportadressen werden bewusst nicht persistiert. Sie sind für Start/Stop nicht erforderlich und können Benutzerinformationen, Kennwörter oder andere sensible Bestandteile enthalten.

Zustandswerte

• 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

Weitere Host-Servicezustände werden als unbekannt angezeigt und nicht automatisch als gestartet behandelt.

Shutdown-Plan

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.

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.

Restore-Plan

1. Zuvor gestartete Hostinstanzen starten.
2. Zuvor gestartete Send Ports starten.
3. Zuvor gestartete Orchestrierungen starten.
4. Zuvor aktivierte Receive Locations zuletzt aktivieren.

Gestoppte oder gebundene Send Ports, gestoppte/gebundene/ungebundene Orchestrierungen, deaktivierte Receive Locations und gestoppte Hostinstanzen erzeugen keine Restore-Aktion.

Eindeutige WMI-Auflösung

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

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