Add transactional installer and harden runtime operations
This commit is contained in:
+68
-26
@@ -1,40 +1,82 @@
|
||||
# Installation
|
||||
# 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
|
||||
- Für Builds: Visual Studio mit .NET Framework 4.6.1 Developer Pack
|
||||
- Zugriff auf den WMI-Namespace `root\MicrosoftBizTalkServer`
|
||||
- Ausreichende Rechte zum Lesen und Ändern von BizTalk-Artefakten
|
||||
- Lokale Administratorrechte und Start der EXE mit **Als Administrator ausführen**
|
||||
- Schreibrechte im Verzeichnis der EXE für die tägliche Logdatei
|
||||
- Lokale Administratorrechte; `Setup.exe` und die Anwendung fordern diese per UAC-Manifest an
|
||||
- Zugriff auf `root\MicrosoftBizTalkServer` mit den erforderlichen BizTalk-Rechten
|
||||
|
||||
## Build
|
||||
## Übergabe als TXT
|
||||
|
||||
1. Repository öffnen.
|
||||
2. `BizTalkPlatformManagementTool.sln` in Visual Studio öffnen.
|
||||
3. Konfiguration `Release|Any CPU` auswählen.
|
||||
4. Solution bauen.
|
||||
5. Das Ergebnis liegt unter `src\BizTalkPlatformManagementTool\bin\Release\`.
|
||||
Das Release erzeugt folgende Dateien unter `artifacts`:
|
||||
|
||||
## Deployment
|
||||
- `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
|
||||
|
||||
1. Den Release-Ordner auf einen BizTalk-Server oder einen Administrationshost kopieren.
|
||||
2. Sicherstellen, dass der ausführende Benutzer WMI-Zugriff auf `root\MicrosoftBizTalkServer` hat.
|
||||
3. `BizTalkPlatformManagementTool.exe` mit **Als Administrator ausführen** starten.
|
||||
4. Als Ausgabeverzeichnis einen Ordner wählen, in dem Plan-, Snapshot- und Report-Dateien abgelegt werden dürfen.
|
||||
5. Prüfen, dass im EXE-Verzeichnis `BizTalkPlatformManagementTool-yyyy-MM-dd.log` geschrieben werden kann. Logs werden für maximal fünf Tage vorgehalten.
|
||||
Auf dem Zielsystem wird die TXT-Datei so rekonstruiert und geprüft:
|
||||
|
||||
## Erster Funktionstest
|
||||
```bat
|
||||
certutil -decode BizTalkPlatformManagementTool-Setup.zip.b64.txt BizTalkPlatformManagementTool-Setup.zip
|
||||
certutil -hashfile BizTalkPlatformManagementTool-Setup.zip SHA256
|
||||
type BizTalkPlatformManagementTool-Setup.zip.sha256.txt
|
||||
```
|
||||
|
||||
1. Anwendung mit **Als Administrator ausführen** starten.
|
||||
2. Zielserver eintragen oder den vorgeschlagenen lokalen Server verwenden.
|
||||
3. **Dry run** aktiviert lassen.
|
||||
4. **Diagnose** ausführen.
|
||||
5. **Snapshot Before** ausführen und prüfen, ob `before.json` sowie CSV/HTML-Reports erzeugt wurden.
|
||||
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.
|
||||
|
||||
## Produktive Nutzung
|
||||
## Neuinstallation
|
||||
|
||||
Vor produktiven Änderungen immer zuerst einen Dry-run ausführen und die erzeugten `shutdown-plan.json` beziehungsweise `restore-plan.json` prüfen. Dry-run erst deaktivieren, wenn der Plan fachlich und technisch korrekt ist.
|
||||
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 und Uninstaller: `%ProgramData%\BizTalkPlatformManagementTool`
|
||||
- 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.
|
||||
6. Die aktivierte EXE führt den Self-Test erneut aus.
|
||||
7. Erst danach werden Verknüpfungen und Windows-Uninstall-Eintrag aktualisiert.
|
||||
|
||||
Schlägt ein Schritt nach Beginn der Umschaltung fehl, entfernt das Setup die neue Version und stellt das Backup wieder her. Staging und Backup werden anschließend bestmöglich bereinigt. Das genaue Phasenprotokoll steht unter `%ProgramData%\BizTalkPlatformManagementTool\InstallerLogs`.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user