# 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 - `BizTalkPlatformManagementTool-2.3.3-source.zip.b64.txt`: vollständiger Quellstand als Base64-TXT - `BizTalkPlatformManagementTool-2.3.3-source.zip.sha256.txt`: SHA-256 des Quellarchivs Auf dem Zielsystem wird die TXT-Datei so rekonstruiert und geprüft: ```bat 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. Die standardmäßig abgewählte, optionale Desktop-Verknüpfung nur bei Bedarf für alle Benutzer aktivieren. 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 primär: `%ProgramData%\BizTalkPlatformManagementTool\Logs` - Installerlogs: `%ProgramData%\BizTalkPlatformManagementTool\InstallerLogs` - Uninstaller: `%ProgramData%\BizTalkPlatformManagementTool\Setup\Uninstall.exe` - Startmenü: `BizTalk Platform Management Tool` ## Laufzeitlog-Ablage prüfen Der normale Laufzeitlogordner liegt nicht im Programmverzeichnis. `%ProgramData%` entspricht üblicherweise `C:\ProgramData` und ist im Explorer standardmäßig ausgeblendet. Dass unter `C:\Program Files\BizTalkPlatformManagementTool` nur EXE, Konfiguration und Installationsstatus sichtbar sind, ist daher allein noch kein Logfehler. Ab Version 2.3.1 akzeptiert die Anwendung einen Ablageort erst nach einem echten Create/Write/Flush/Delete-Test. Sie prüft in dieser Reihenfolge: 1. `%ProgramData%\BizTalkPlatformManagementTool\Logs` 2. `%LocalAppData%\BizTalkPlatformManagementTool\Logs` 3. `%ProgramFiles%\BizTalkPlatformManagementTool\Logs` 4. `%TEMP%\BizTalkPlatformManagementTool\Logs` Danach wird bei jedem Programmstart die Zeile `Runtime log storage verified by startup append. Active file: ...` wirklich in die Tagesdatei geschrieben und im Grid angezeigt. **Log Folder** öffnet genau den aktiven Pfad. Bei einem Fallback nennt eine gelbe Grid-Warnung den verworfenen Pfad samt Exception. Kann kein Kandidat beschrieben werden, erscheint `RUNTIME FILE LOGGING UNAVAILABLE`; vor einer echten Wartungsoperation müssen dann Berechtigungen, Datenträger oder Sicherheitssoftware geklärt werden. Der WMI-freie Installer-Self-Test schreibt und liest zusätzlich einen eigenen temporären Runtime-Logmarker. Damit wird eine Version, deren Logger grundsätzlich keine Datei erzeugen kann, bereits vor der Aktivierung abgelehnt. Die PROD-Abnahme des realen Maschinenpfads bleibt nach dem Update erforderlich. ## Anwendungszuordnung ab 2.3.3 Die Runtime-WMI-Klassen für Send Ports, Receive Locations und Orchestrierungen liefern keine verlässliche BizTalk-Anwendungszuordnung. Version 2.3.3 liest deshalb `MgmtDbServerName` und `MgmtDbName` aus `MSBTS_GroupSetting` und verwendet die lokal installierte `Microsoft.BizTalk.ExplorerOM.dll` ausschließlich read-only zum Aufbau der Application-/Artefakthierarchie. Zustandsabfrage sowie Shutdown-/Restore-Mutationen bleiben WMI-basiert. Es wird keine BizTalk-DLL mit dem Paket ausgeliefert. Die Microsoft-Assembly wird aus dem GAC oder aus einem vorhandenen, identitätsgeprüften BizTalk-Installationspfad geladen. Das ausführende Konto benötigt neben WMI-Zugriff Leserechte auf den BizTalk-Anwendungskatalog in der Management-Datenbank. Nach dem Update muss **Diagnose** für PROD dieselbe Zahl bei `Send ports visible` und `application associations resolved` melden. Andernfalls zeigt das Log den Lade-, Berechtigungs- oder Zuordnungsfehler; ein realer Lauf darf erst nach Klärung freigegeben werden. ## Shutdown-Drain-Checkpoint ab 2.3.2 Ein echter Shutdown pausiert nach allen Receive Locations und vor Orchestrierungen, Send Ports und Host Instances. Der Dialog zeigt erfolgreiche, bereits deaktivierte und fehlgeschlagene Receive Locations. Er darf geöffnet bleiben, während Group Hub, laufende Service Instances, MessageBox-/Queue-Metriken und das Enterprise-Monitoring geprüft werden. - **Yes** protokolliert `CheckpointDecision=Continue` und setzt den gespeicherten Plan fort. - **No** beendet den Lauf sicher; alle späteren Zeilen werden als `NotExecuted` gespeichert. - Ein fehlender oder fehlerhafter Dialog stoppt ebenfalls fail-closed und wird als Fehler protokolliert. - Dry-run zeigt den Checkpoint im Plan/Grid, fordert aber keine echte Entscheidung an. - Nach einem Stopp werden `shutdown-after.json` und `shutdown-result.json` soweit möglich trotzdem geschrieben. Der Dialog behauptet nicht automatisch, die Umgebung sei leer. Diese fachliche Entscheidung bleibt bewusst beim Operator und den vorhandenen Enterprise-Monitoringquellen. `Partially Started` in der BizTalk-Konsole ist direkt nach dem Abschalten der Receive Locations erwartbar. Es wird kein pauschaler Application-Stop ergänzt, da dieser je nach Modus weitere Artefaktzustände, Subscriptions, Policies oder laufende Instanzen verändert. ## 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. Kann ausschließlich die Umbenennung des geprüften Staging-Verzeichnisses dauerhaft nicht ausgeführt werden, darf der Installer nach vollständig ausgeschöpften Move-Versuchen auf eine verifizierte Kopie zurückfallen. Dabei wird jede Datei aus dem Staging nochmals gegen ihren Manifest-SHA-256 geprüft; anschließend läuft auch der zweite Self-Test aus dem endgültigen Ziel. Bei einer Neuinstallation muss das Ziel noch fehlen. Bei einem Update ist der Fallback erst zulässig, nachdem die vollständige Vorversion atomar ins Backup verschoben wurde und das Ziel ebenfalls nicht mehr existiert. Er ist damit kein In-place-Update und überschreibt keine aktive Version. Scheitern Kopie, Hashprüfung oder Ziel-Self-Test, entfernt das Setup das teilweise neue Ziel und stellt beim Update das zuvor atomar erzeugte Backup wieder her. Kann bereits die Vorversion nicht atomar ins Backup verschoben werden, bleibt sie unverändert aktiv und das Update bricht ohne Kopierfallback 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`. ### Optionale Desktop-Verknüpfung für alle Benutzer Der gemeinsame Desktop-Link unter `%PUBLIC%\Desktop` ist eine Komfortfunktion und ab Version 2.2.4 standardmäßig abgewählt. Fehlende Rechte, eine WSH-/COM-Sperre, eine abweichende Linkvalidierung oder ein Fehler beim Sichern, Entfernen beziehungsweise Wiederherstellen dieses optionalen Links dürfen Installation, Update, Rollback und Deinstallation nicht abbrechen. Das Setup zeigt eine Warnung, schreibt die vollständige Exception ins Diagnoselog und setzt die Kernoperation fort. Startmenü-Link, Uninstaller unter ProgramData und Uninstall-Registry bleiben verpflichtende Windows-Integration. Scheitert einer dieser Bestandteile, wird die Installation weiterhin als fehlgeschlagen behandelt und die vorherige Version vollständig wiederhergestellt. Der Installer verändert keine ACLs und umgeht keine Sicherheitsrichtlinie; bei einem Desktop-Link-Fehler bleibt der Link lediglich im tatsächlich erreichbaren Zustand. ## 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`. Ein Kopierfallback protokolliert `event=activation_fallback_started`, `event=activation_fallback_complete`, den Geltungsbereich `scope=new_install` oder `scope=update_after_backup` und im Abschluss `activation_method=verified_copy_fallback`. Kann bei einem Update bereits das Backup nicht erzeugt werden, endet es weiterhin mit `SETUP-ACTIVATION`, bevor die aktive Version verändert wurde. Ein Fehler des gemeinsamen Desktop-Links erscheint als `event=optional_windows_integration_warning` mit einer Rolle wie `desktop_shortcut_snapshot`, `desktop_shortcut_create`, `desktop_shortcut_remove`, `desktop_shortcut_validate`, `desktop_shortcut_rollback_restore` oder `desktop_shortcut_uninstall_remove`. Der erfolgreiche Gesamtabschluss enthält dann `optional_desktop_shortcut_warning=True` und beispielsweise `result=success_with_optional_desktop_shortcut_warning`; er ist kein Rollback und kein fehlgeschlagenes Setup. 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.3.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. Auch ein Fehler der GUI-Logweiterleitung ist vom fachlichen Executor isoliert und kann die späteren Planschritte nicht abbrechen. Für ScheduledTask-Receive-Locations enthält die installierte EXE-Konfiguration `AdapterAssemblySearchPaths`. Normalerweise ist keine Anpassung nötig: BizTalk- und ScheduledTask-Installationsverzeichnisse werden zusätzlich automatisch erkannt. Nur bei einem abweichenden lokalen Installationspfad darf der vorhandene Wert um diesen Pfad ergänzt werden. Die Assembly muss aus genau dieser BizTalk-/Adapterinstallation stammen; das Tool verändert den GAC nicht. 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: ```bat 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: ```sh 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.