BizTalkPlatformManagementTool/Installation.md

Installation und Update

Voraussetzungen

• Windows Server 2019/2022 oder ein Windows-Administrationshost
• Microsoft BizTalk Server 2020 oder BizTalk Administration Tools
• .NET Framework 4.6.1 Runtime
• Lokale Administratorrechte; Setup.exe und die Anwendung fordern diese per UAC-Manifest an
• Zugriff auf root\MicrosoftBizTalkServer mit den erforderlichen BizTalk-Rechten

Übergabe als TXT

Das Release erzeugt folgende Dateien unter artifacts:

• BizTalkPlatformManagementTool-Setup.zip.b64.txt: Certutil-kompatible Base64-Übertragung
• BizTalkPlatformManagementTool-Setup.zip.sha256.txt: SHA-256 des ZIP-Archivs
• BizTalkPlatformManagementTool-Setup.zip: direkt entpackbares Installationspaket

Auf dem Zielsystem wird die TXT-Datei so rekonstruiert und geprüft:

certutil -decode BizTalkPlatformManagementTool-Setup.zip.b64.txt BizTalkPlatformManagementTool-Setup.zip
certutil -hashfile BizTalkPlatformManagementTool-Setup.zip SHA256
type BizTalkPlatformManagementTool-Setup.zip.sha256.txt

Der Hash aus certutil muss exakt dem Wert in der SHA-256-Datei entsprechen. Danach das ZIP in einen neuen Ordner entpacken und Setup.exe starten. Ein Code-Signing-Zertifikat ist derzeit nicht Bestandteil des Repositories; deshalb schützt SHA-256 gegen Übertragungsfehler, ersetzt aber keine Signaturprüfung der Herausgeberidentität.

Neuinstallation

1. ZIP vollständig entpacken; Setup.exe, application.manifest und der Ordner application müssen nebeneinander liegen.
2. Setup.exe starten und die UAC-Abfrage bestätigen.
3. Optional die Desktop-Verknüpfung abwählen.
4. Installieren wählen.
5. Den Abschluss und den Pfad des Diagnoselogs prüfen.
6. Die Anwendung starten, Dry run aktiviert lassen und zuerst Diagnose ausführen.

Installationsziele:

• Programm: %ProgramFiles%\BizTalkPlatformManagementTool
• Laufzeitlogs: %ProgramData%\BizTalkPlatformManagementTool\Logs
• Installerlogs: %ProgramData%\BizTalkPlatformManagementTool\InstallerLogs
• Uninstaller: %ProgramData%\BizTalkPlatformManagementTool\Setup\Uninstall.exe
• Startmenü: BizTalk Platform Management Tool

Update und Rollback

Der Installer verändert eine bestehende Installation erst nach erfolgreicher Paketprüfung:

1. Jede Payload-Datei wird gegen Länge und SHA-256 im application.manifest geprüft; unbekannte Zusatzdateien werden abgelehnt.
2. Die neue Version wird in ein eindeutiges Staging-Verzeichnis kopiert und dort mit --self-test geprüft.
3. Eine laufende Toolinstanz blockiert das Update.
4. Die bestehende Installation wird in ein Backup-Verzeichnis verschoben.
5. Das validierte Staging wird auf demselben Volume aktiviert. Atomare Verzeichnisverschiebungen werden bei IOException oder UnauthorizedAccessException mit begrenztem Backoff bis zu achtmal versucht (insgesamt höchstens 19,75 Sekunden Wartezeit).
6. Die aktivierte EXE führt den Self-Test erneut aus.
7. Erst danach werden Verknüpfungen und Windows-Uninstall-Eintrag aktualisiert.

Bei einer Neuinstallation ohne bestehendes Ziel darf der Installer nach vollständig ausgeschöpften Move-Versuchen auf eine verifizierte Kopie zurückfallen. Dabei wird jede Datei aus dem bereits geprüften Staging nochmals gegen ihren Manifest-SHA-256 geprüft; anschließend läuft auch der zweite Self-Test aus dem endgültigen Ziel. Dieser Fallback gilt ausdrücklich nicht für Updates: Kann dort die Vorversion nicht atomar ins Backup verschoben werden, bricht das Update unverändert ab.

Schlägt ein Schritt nach Beginn der Umschaltung fehl, entfernt das Setup die neue Version und stellt das Backup wieder her. Tritt der Fehler bereits bei Paketprüfung oder Staging auf, meldet das Setup ausdrücklich Kein Rollback erforderlich, weil die aktive Installation unverändert blieb. Staging und Backup werden anschließend bestmöglich bereinigt. Kann ein nicht mehr benötigtes temporäres Verzeichnis wegen einer Dateisperre nicht gelöscht werden, bleibt die erfolgreiche Installation aktiv und das Log kennzeichnet den Abschluss als success_with_temporary_cleanup_warning.

Installer-Diagnose

Jeder Installations-, Update- und Deinstallationslauf erzeugt ein eigenes UTF-8-Log. Über Diagnoselogs öffnen kann der Ordner direkt aus dem Setup geöffnet werden. Die Logs werden 90 Tage aufbewahrt. Ist ProgramData nicht beschreibbar, versucht das Setup ein Fallback unter %TEMP%\BizTalkPlatformManagementTool\InstallerLogs und zeigt dessen Pfad an. Kann auch dort kein Log erzeugt werden, bleibt der eigentliche Fehler in der Setup-Meldung sichtbar.

Die Abschlussmeldung enthält einen stabilen Fehlercode und die betroffene Phase:

Fehlercode	Bedeutung
SETUP-INITIALIZATION	Daten-/Logverzeichnis oder Ausgangszustand konnte nicht vorbereitet werden
SETUP-PACKAGE-VALIDATION	Manifest, Payload, SHA-256 oder Prüfung auf laufende Anwendung fehlgeschlagen
SETUP-STAGING-VALIDATION	Kopie ins Staging oder erster Self-Test fehlgeschlagen; aktive Installation unverändert
SETUP-ACTIVATION	Sichern oder Aktivieren der Programmdateien fehlgeschlagen
SETUP-ACTIVATED-SELFTEST	Zweiter Self-Test nach der Aktivierung fehlgeschlagen
SETUP-WINDOWS-INTEGRATION	Verknüpfung, Uninstaller oder Registry-Registrierung/Verifikation fehlgeschlagen
UNINSTALL-*	Die entsprechende Initialisierungs-, Prozess-, Quarantäne- oder Integrationsphase der Deinstallation fehlgeschlagen

Das Log enthält Betriebssystem, Prozess-/OS-Bitness, .NET-Version, Rechner, Windows-Identität und Elevation sowie Installationspfade, freien Speicher, Dateigrößen, Versionen und SHA-256. Für Self-Tests werden Laufzeit, Exitcode dezimal und hexadezimal sowie vollständiges stdout und stderr geschrieben. Bei Fehlern folgen Exception-Kette, HRESULT und Stacktrace; jeder Rollbackschritt und sein Ergebnis werden separat protokolliert. Passwörter oder Verbindungsdaten werden vom Installer nicht verarbeitet oder geloggt.

Bei einer gesperrten Verzeichnisverschiebung erscheinen event=directory_move_retry und nach einer Erholung event=directory_move_recovered. Eine Neuinstallation mit Kopierfallback protokolliert event=activation_fallback_started, event=activation_fallback_complete und im Abschluss activation_method=verified_copy_fallback. Ein dauerhaft gesperrtes Update verwendet keinen Kopierfallback und endet weiterhin mit SETUP-ACTIVATION, bevor die aktive Version verändert wurde.

Für eine Supportanalyse bitte sichern:

1. Vollständige Fehlermeldung einschließlich Fehlercode und Phase.
2. Das jüngste setup-*.log aus dem vom Setup angezeigten Pfad.
3. Ob Neuinstallation, Update oder Deinstallation ausgeführt wurde und ob Virenscanner/Endpoint Protection eine Datei blockiert hat.

Ein erfolgreicher Installer-Self-Test bestätigt Paket, Programmstart und lokale Kernfunktionen. Der fachliche BizTalk-Zustand ist bewusst kein Rollbackkriterium: WMI-Erreichbarkeit, Berechtigungen und Umgebungszustand danach separat über Diagnose und einen Dry-run prüfen. So wird beispielsweise ein erreichbarer Installer nicht wegen eines fachlichen Unknown-Zustands zurückgerollt.

Emergency Restore nach einem Teilabbruch

Version 2.2.1 kann einen Wiederanlauf allein aus einer erhaltenen before.json vorbereiten und ausführen. Eine mit Version 2.1.3 erzeugte Datei ist kompatibel; zusätzliche Plan- oder Nachher-Dateien des fehlgeschlagenen Laufs sind nicht erforderlich.

1. Die erhaltene before.json außerhalb des Arbeitsverzeichnisses zusätzlich sichern.
2. Anwendung als Administrator starten und denselben Zielserver wählen, der im Snapshot gespeichert ist.
3. Über State... die erhaltene Datei auswählen oder im Feld State ihren vollständigen Pfad eintragen.
4. Validate State ausführen. Diese Prüfung öffnet keine WMI-Verbindung und verändert keinen Laufzeitzustand.
5. Dry run aktiviert lassen und Emergency Restore wählen.
6. Den timestamp-basierten emergency-restore-plan-* prüfen. Die bestehende before.json wird dabei nicht überschrieben.
7. Dry run deaktivieren, Emergency Restore erneut wählen und den expliziten Dialog bestätigen.

Der Emergency Restore stellt zuerst sicher, dass der Windows-Dienst ENTSSO läuft. Danach folgen Host Instances, Send Ports, Orchestrations und zuletzt Receive Locations. Vor jeder Mutation wird der aktuelle Zustand geprüft; bereits korrekte Zustände werden als AlreadySatisfied protokolliert. Ein isolierter Fehler wird als Failed festgehalten, während alle späteren unabhängigen Schritte weiter versucht werden.

Jeder Lauf schreibt eine unveränderte Snapshot-Kopie sowie timestamp-basierte Plan- und Ergebnisdateien. Der echte Lauf versucht zusätzlich Nachher-Snapshot und emergency-restore-diff-* als JSON, CSV und HTML. Ein Ergebnis mit mindestens einem fehlgeschlagenen Schritt bleibt im GUI ausdrücklich Failed und verlangt Operator-Review, auch wenn alle anderen Schritte erfolgreich waren.

Deinstallation

Die Deinstallation ist über Apps & Features / Programme und Features oder über den Setup-Button Deinstallieren möglich. Vorher muss die Anwendung geschlossen sein. Das Programmverzeichnis wird zuerst atomar aus dem aktiven Pfad in ein eindeutiges Quarantäneverzeichnis verschoben; erst danach werden Verknüpfungen und Uninstall-Eintrag entfernt und die Dateien bestmöglich gelöscht. Scheitert die Windows-Integration, werden Programmverzeichnis, Registrywerte, Verknüpfungen und vorheriger Uninstaller wiederhergestellt. Installerlogs und der supportfähige Setup-Ordner bleiben bewusst zur Fehleranalyse unter %ProgramData%\BizTalkPlatformManagementTool erhalten.

Build, Test und Paketierung

In einer Visual-Studio-Developer-Eingabeaufforderung mit .NET Framework 4.6.1 Developer Pack:

scripts\test-release.cmd
scripts\package-release.cmd

test-release.cmd baut alle vier Projekte und führt die Regressionstests aus. package-release.cmd baut und testet erneut, erzeugt Paket, ZIP, Base64-TXT und SHA-256-Datei und validiert dabei das interne Payload-Manifest.

Die Release-Konfiguration erzeugt außerdem pro Assembly eine XML-Dokumentationsdatei im jeweiligen bin\Release-Verzeichnis. Damit werden XML-Kommentare und cref-Referenzen während des Builds compilerseitig geprüft; diese Entwicklerartefakte sind für den Betrieb nicht erforderlich und deshalb nicht Bestandteil der Installer-Payload.

Unter Mono kann der portable Anteil lokal geprüft werden:

msbuild BizTalkPlatformManagementTool.sln /p:Configuration=Release /p:Platform="Any CPU" /m:1
mono tests/BizTalkPlatformManagementTool.Tests/bin/Release/BizTalkPlatformManagementTool.Tests.exe
mono src/BizTalkPlatformManagementTool/bin/Release/BizTalkPlatformManagementTool.exe --self-test

Mono ersetzt nicht die abschließende Prüfung von UAC, Registry, Verknüpfungen und BizTalk-WMI auf einem repräsentativen Windows-/BizTalk-System.