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

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