Der Installer des Bootstrappers 2.0

Ab 2.0 installiert der Starter eine Anwendung für den Windows-Benutzer so, wie Windows Installer ein Paket je Benutzer installiert: aus einer Beschreibung ihrer Bestandteile, als eine Transaktion, die bei einem Fehler zurückgerollt wird, und mit jedem gemeinsam genutzten Teil gezählt – damit Update, Rückkehr zu einer früheren Version, Reparatur und Deinstallation genau den Zustand hinterlassen, den sie versprechen. Nichts davon braucht Administratorrechte.

registration.json ist die Registrierung der DLL je Benutzer als Daten, geschrieben beim Bau des Pakets (tools\Export-Registration.ps1 der WKL Forms Object Library). Der Starter schreibt diese Schlüssel selbst, statt regsvr32 auszuführen; Windows Installer rät von der Selbstregistrierung ab, weil sie sich nicht zuverlässig zurückrollen lässt und verbirgt, was sie schreibt.

Jeder Teil einer installierten Version ist eine Komponente mit einem Schlüsselpfad; die Komponente gilt als installiert, wenn ihr Schlüsselpfad existiert. Jede Produktversion, die eine Komponente verwendet, ist einer ihrer Clients – das ist der Referenzzähler.

Verzeichnet wird alles in der Installer-Datenbank des Benutzers, %LOCALAPPDATA%\WKL\Installer\installer.db (SQLite, die Kopie von SQLite, die Windows mitbringt; eine Datenbank für alle Produkte des Benutzers). Ihre Tabellen:

So prüfen Sie das von außen.

• Wkl.Bootstrapper.exe /list gibt jede installierte Version und jede Komponente mit der Zahl ihrer Verwender aus; eine Komponente, deren Schlüsselpfad fehlt, ist mit MISSING (repair: /repair) markiert. /list /json gibt dasselbe als JSON aus (siehe Befehle und Exitcodes).
• Die Datenbank lässt sich mit jedem SQLite-Werkzeug lesen, zum Beispiel SELECT * FROM ComponentClient. Nur lesen: Der Starter ist der einzige, der hineinschreibt.
• Das Protokoll des Produkts (Logs\bootstrapper.log) hat eine Zeile je Schritt: Datum und Uhrzeit mit Millisekunden, die Prozess-ID, der Schritt auf 12 Zeichen aufgefüllt, dann der Text. Je Installation schreibt es eine Zeile mit dem Schritt install: für eine Auslieferung im Format 1 install <version> <copy>, gefolgt von components <release>, wenn Komponenten registriert wurden; für ein Projekt im Format 2 install <product> <version>: <n> entries, <n> registry keys. Eine Auslieferung, die eine vorhandene Registrierung verwendet, schreibt stattdessen components using the existing registration ....

Ein Start mit einer neuen Version (oder der erste Start) führt diese Schritte als eine Transaktion aus:

1. Eine unterbrochene frühere Transaktion wird zuerst zurückgerollt (der PC wurde ausgeschaltet, der Prozess beendet).
2. Beim ersten Kontakt mit dem Produkt wird übernommen, was der Starter 1.0 installiert hat (siehe unten).
3. Die Version wird verzeichnet.
4. Die Kopie wird abgelegt – sofern sie nicht existiert: kopiert, gegen Größe und SHA-256 aus app-manifest.json geprüft (Code 42 bei Abweichung), die Markierung „aus dem Internet“ entfernt; die INI-Datei geschrieben.
5. Die Komponenten: Eine vorhandene Registrierung, die nicht vom Starter stammt (die der IT für den Computer, HKLM, oder die eigene des Release-Pakets für den Benutzer) und auf eine vorhandene DLL eines Release zeigt, das mindestens so hoch ist, wie die Anwendung verlangt (requires aus app-manifest.json), wird unverändert verwendet – erneutes Registrieren würde sie verdoppeln, und COM würde die Registrierung des Benutzers einer neueren des Computers vorziehen. Andernfalls entscheidet die Release-Regel; ein zu registrierender Release-Ordner wird kopiert (nur fehlende Dateien; eine verwendete DLL wird nie ersetzt) und die Registrierung aus registration.json geschrieben.
6. Die ODBC-Treiber der Auslieferung, jeder mit seiner Datenquelle (siehe ODBC-Treiber).
7. Der vertrauenswürdige Speicherort und der Eintrag unter „Apps“ werden geschrieben oder aktualisiert (DisplayVersion).
8. Die Transaktion wird abgeschlossen.

Danach werden in einer eigenen Transaktion die Versionen über keepVersions hinaus entfernt (nie die Version, die gerade gestartet wird, und nie die zuletzt funktionierende), und dann startet Access. Eine erfolgreich gestartete Version wird zur zuletzt funktionierenden.

Bei einem Fehler wird jeder bis dahin ausgeführte Schritt in umgekehrter Reihenfolge rückgängig gemacht, der PC ist wie vor dem Start, und das Fenster meldet den Code:

Dateischritte warten kurz und versuchen es erneut, solange ein anderes Programm (ein Virenscanner, die Indizierung) eine Datei festhält.

Beispiel: Die IT hat die Komponenten für den Computer registriert. Die WKL Forms Object Library 1.56 ist unter HKLM registriert, mit der DLL in C:\Program Files (x86)\WKL\Access Components; die Anwendung verlangt 1.51, und die Auslieferung bringt 1.56.1 mit. Der Starter registriert nichts, kopiert keine Komponenten und verzeichnet keine Komponente components/...; das Protokoll enthält die Zeile components using the existing registration 1.56 for the computer: C:\Program Files (x86)\WKL\Access Components\Wkl.Access.Components.dll. Wäre die Registrierung für den Computer 1.48, würde das ausgelieferte 1.56.1 für den Benutzer registriert, und die Registrierung des Benutzers hätte von da an Vorrang vor der des Computers.

Je Benutzer und Bitbreite ist jeweils ein Release der WKL Forms Object Library registriert: Die Klassenschlüssel sind in jedem Release dieselben, daher entscheidet die letzte Registrierung für jede Anwendung des Benutzers. Jede Produktversion verzeichnet das Release, das ihre Anwendung verlangt (requires in app-manifest.json). Der Starter registriert das ausgelieferte Release, sofern er damit keinem anderen Produkt ein Release wegnimmt:

Nur andere Produkte zählen. Versionen desselben Produkts, die neben der gestarteten aufbewahrt werden (keepVersions), zählen nicht: Die Rückkehr zu einer früheren Version innerhalb eines Produkts registriert das Release, mit dem diese Version ausgeliefert wurde, und der Schritt nach vorn registriert wieder das neuere. Beispiel: Produkt A 1.4.0 verlangt 1.56 und wurde mit 1.56.1 ausgeliefert, A 1.5.0 verlangt 1.57 und wurde mit 1.57.0 ausgeliefert.

Zwei Produkte mit verschiedenen Releases laufen deshalb beide auf dem höheren: Ein laufendes Access behält die DLL, die es geladen hat, wenn sich die Registrierung ändert, und danach gestartete Access-Prozesse laden das neu registrierte Release.

Das Release einer Auslieferung ist das release ihrer registration.json, das Export-Registration.ps1 aus der Produktversion von Wkl.Forms.ObjectLibrary.Managed.dll übernimmt (bis Release 1.68: Wkl.Access.Components.Managed.dll; zum Beispiel 1.56.1). Die Versionsressource des nativen Startmoduls (Wkl.Forms.ObjectLibrary.dll, bis 1.68 Wkl.Access.Components.dll) trägt nur Haupt- und Nebenversion (1.56.0 in 1.56.1) und wird nicht verwendet; der Starter 1.0 hat sie verwendet, daher können seine Ordner unterhalb von Components diese Nummer tragen.

Eine Auslieferung kann ODBC-Treiber für den Benutzer mitbringen, sodass kein Administrator sie installieren muss. Jeder Treiber liegt in der Auslieferung als odbc\<driver>\x86 und odbc\<driver>\x64 und wird in bootstrapper.json genannt:

{
  "format": 1,
  "product": "Kunden",
  "source": "\\\\server\\apps\\kunden\\production",
  "components": "components",
  "odbcDataSources": [ "WklGateway" ],
  "odbc": [
    { "driver": "Wkl OData", "folder": "odbc\\Wkl OData", "dll": "Wkl.Data.OData.Odbc.dll", "dataSource": "WklGateway" }
  ]
}

Der Starter kopiert den Unterordner nach %LOCALAPPDATA%\WKL\Drivers\<driver>\<release>\<bitness>, wobei <release> die Produktversion der DLL ohne Build-Kennung ist, und schreibt die Datenquelle für den Benutzer (32-Bit-Ansicht der Registrierungsdatenbank für x86):

Ein Eintrag unter ODBCINST.INI wird nicht geschrieben; Access öffnet verknüpfte Tabellen und Pass-Through-Abfragen über eine Datenquelle, deren Driver der Pfad der DLL ist. Alles andere – die Adresse des Dienstes, die Datenbank – gehört in die Verbindungszeichenfolge der Verknüpfungen der Anwendung, nicht in die Datenquelle. Eine in odbc genannte Datenquelle muss vor dem Start nicht existieren, anders als die übrigen Einträge von odbcDataSources.

Der Treiber ist eine gezählte Komponente wie die WKL-Komponenten: Ein später ausgeliefertes neueres Release wird neben das alte gelegt, und die Datenquelle zeigt darauf; eine Deinstallation entfernt den Release-Ordner und die Datenquelle mit der letzten Produktversion, die sie verwendet. Eine Datenquelle dieses Namens, die schon existierte, bevor der Starter sie schrieb, wird auf ihre vorherigen Werte zurückgesetzt.

Anders als für die WKL-Komponenten gilt für die Datenquelle keine Release-Regel: Jeder Start schreibt sie für die gestartete Version. Die Rückkehr zu einer Version, die mit einem älteren Treiber-Release ausgeliefert wurde, lässt die Datenquelle wieder auf dieses ältere Release zeigen. Liefern zwei Produkte dieselbe dataSource mit verschiedenen Treiber-Releases aus, entscheidet das zuletzt gestartete Produkt; es wird kein Code gemeldet, und beide Release-Ordner bleiben, solange eine Version sie verwendet. Geben Sie jedem Produkt eine eigene dataSource, wenn sie sich kein Treiber-Release teilen dürfen.

Der Start einer älteren Version – eine Quelle, die wieder eine niedrigere Version ausliefert – installiert diese Version erneut: ihre Kopie (falls noch vorhanden), ihre Treiber (die Datenquelle zeigt wieder auf das ältere Treiber-Release) und ihr Komponenten-Release nach der Release-Regel. Neuere Versionen bleiben, bis keepVersions oder die Deinstallation sie entfernt, sodass der Benutzer wieder nach vorn wechseln kann.

Mit deliveryKey in der Projektdatei liefert eine Quelle eine niedrigere Version nur aus, wenn der Herausgeber die höhere in der signierten Auslieferung zurückgezogen hat (/publish /withdraw); sonst behält der Starter die installierte Version und meldet Code 52. Siehe Signierte Auslieferung veröffentlichen.

Zurück, während die Quelle bereits eine neuere Version ausliefert, geht es über das Einstellungsfenster (Wkl.Bootstrapper.exe /settings). Seine drei Aktionen arbeiten über den Installer, jede als eine Transaktion mit ihrem Rollback:

Diese Version starten bringt das Komponenten-Release zurück, das die Version verwendet hat, nicht das, das ihre Auslieferung enthielt. Eine Version, die auf einem neueren Release blieb, weil ein anderes Produkt es brauchte, bleibt auf diesem neueren Release.

Ein Produkt, das nur der Bootstrapper 1.0 abgelegt hat, behält für seine Ordner die Aktionen von 1.0, bis sein nächster Start es übernimmt.

Wkl.Bootstrapper.exe /repair führt die Installation der aktuellen Version aus, ohne Access zu starten: Was fehlt, wird aus der Auslieferung wiederhergestellt – die Kopie, falls gelöscht, Dateien der Komponenten, gelöschte oder geänderte Werte in der Registrierungsdatenbank, der vertrauenswürdige Speicherort, der Eintrag unter „Apps“. Was vorhanden ist, bleibt unberührt; eine vorhandene Kopie behält die Daten des Benutzers.

Wkl.Bootstrapper.exe /uninstall (auch der Befehl, den Windows unter Einstellungen › Apps ausführt) entfernt als eine Transaktion:

• jede Version des Produkts: die Versionsordner mit allem, was darin liegt;
• jede Komponente, die keine andere Produktversion des Benutzers mehr verwendet: Dateien, Ordner sowie Schlüssel und Werte der Registrierungsdatenbank, die der Starter angelegt hat;
• Werte der Registrierungsdatenbank, die schon existierten, bevor der Starter sie schrieb, werden auf ihren vorherigen Inhalt zurückgesetzt, nie gelöscht;
• den vertrauenswürdigen Speicherort und den Eintrag unter „Apps“.

Komponenten, die ein anderes Produkt des Benutzers noch verwendet, bleiben, und mit ihnen die Klassenschlüssel, die sie gemeinsam haben; hat das entfernte Produkt das registrierte Release verwendet, wird das neueste verbleibende Release derselben Bitbreite wieder registriert. Ist eine Kopie in Access geöffnet, wird nichts entfernt, und der Code ist 41 mit dem genannten Programm; schließen Sie Access und führen Sie den Befehl erneut aus.

Die Verknüpfungen der Liste shortcuts des Projekts werden mit dem Produkt entfernt, auch die, deren Ziel der Starter selbst ist.

Unberührt bleiben: der Ordner, aus dem der Starter läuft, mit seiner bootstrapper.json, Verknüpfungen, die nicht aus dem Projekt stammen, die Installer-Datenbank selbst und die Protokolle unterhalb von %LOCALAPPDATA%\WKL\<product>\Logs.

Die Codes sind die der Fehlercodes des Starters. /list /json gibt ein Objekt aus:

{
  "versions": [
    { "product": "Kunden", "displayName": "Kunden", "version": "1.4.0", "lastWorking": true }
  ],
  "components": [
    { "id": "components/1.56.1/x86", "keyPath": "C:\\Users\\<user>\\AppData\\Local\\WKL\\Components\\1.56.1\\x86\\Wkl.Access.Components.dll", "clients": 2, "present": true }
  ]
}

Ist nichts installiert, sind die Arrays leer.

Um auf einem Test-PC ein Rollback zu sehen, lassen Sie das Kopieren scheitern, nachdem die Version verzeichnet wurde:

1. Führen Sie /list /json aus und bewahren Sie die Ausgabe auf.
2. Legen Sie eine neue Version in die Quelle und ändern Sie ein Byte ihrer Datenbankdatei, nachdem app-manifest.json geschrieben wurde.
3. Starten Sie den Starter. Er meldet Code 42.
4. Führen Sie /list /json erneut aus: Die Ausgabe gleicht der aus Schritt 1, und unterhalb von Frontends existiert kein Ordner der neuen Version.

Um zu sehen, dass auch die Registrierung der Komponenten und die Datenquelle zurückgenommen werden, lassen Sie einen Schritt nach ihnen scheitern. Der Treiber wird nach den Komponenten abgelegt (Schritt 6 nach Schritt 5), daher eignet sich eine Auslieferung mit einem Eintrag odbc:

1. Führen Sie /list /json aus und notieren Sie die Werte des Klassenschlüssels der Komponenten (zum Beispiel HKCU\Software\Classes\WklForms.Application\CLSID, bis Release 1.68 WklComponents.Application, und sein InprocServer32) und von HKCU\Software\ODBC\ODBC.INI\<dataSource>.
2. Legen Sie eine neue Version in die Quelle, deren Auslieferung ein neueres Komponenten-Release und den Treiber mitbringt.
3. Halten Sie die ausgelieferte Treiber-DLL geöffnet, sodass sie sich nicht lesen lässt, zum Beispiel in PowerShell: $f = [System.IO.File]::Open('<source>\odbc\<driver>\x86\<dll>', 'Open', 'Read', 'None').
4. Starten Sie den Starter. Nach einigen Sekunden erneuter Versuche meldet er Code 41.
5. Vergleichen Sie: /list /json, der Klassenschlüssel und die Datenquelle gleichen Schritt 1; unterhalb von %LOCALAPPDATA%\WKL\Components und %LOCALAPPDATA%\WKL\Drivers existiert kein Ordner des neuen Release.
6. Geben Sie die Datei frei ($f.Dispose()) und starten Sie erneut: Die neue Version wird installiert.

Eine Richtlinie gegen vertrauenswürdige Speicherorte eignet sich dafür nicht: Der Starter prüft sie, bevor etwas installiert wird (Code 50 ohne Transaktion), und die Richtlinienschlüssel unterhalb von HKCU\Software\Policies lassen sich ohne Administratorrechte nicht schreiben.

Um zu sehen, dass eine Deinstallation kein Produkt zur Hälfte entfernt, öffnen Sie die installierte Kopie in Access und führen Sie /uninstall /quiet aus: Code 41 nennt MSACCESS.EXE, und /list zeigt weiterhin jede Version und jede Komponente.

Wenn 2.0 zum ersten Mal auf ein Produkt trifft, verzeichnet es als sein eigenes, was der Starter 1.0 hinterlassen hat: die Versionsordner unterhalb von Frontends (die zuletzt funktionierende Version aus State\provisioning.json), den vertrauenswürdigen Speicherort, den 1.0 geschrieben hat (seine Beschreibung endet auf (Wkl.Bootstrapper)), und die Registrierung, die 1.0 mit regsvr32 aus %LOCALAPPDATA%\WKL\Components vorgenommen hat. Danach werden sie wie von 2.0 abgelegte Teile aufgeräumt und deinstalliert. Registrierungen von anderen Orten werden nicht übernommen.

• Zwei Starter desselben Windows-Benutzers, die im selben Moment installieren, werden nicht nacheinander ausgeführt: Die Installer-Datenbank gibt es einmal je Benutzer, und ein Starter, der eine unvollendete Installation vorfindet, rollt sie zurück – auch eine, die gerade ein anderer Starter ausführt. Starten Sie jeweils nur einen (Format 1 ohne registration.json arbeitet je Produkt nacheinander).
• Eine Datei im Format 1 liefert die .NET Desktop Runtime nicht aus: Der Starter prüft sie (Code 33). Ein Projekt im Format 2 kann eine private Runtime ausliefern; siehe Private .NET-Runtime ausliefern.
• WKL JSON wird von einer Datei im Format 1 nicht ausgeliefert: Eine Anwendung, die es verwendet, braucht es vorab registriert, zum Beispiel durch die IT. Ein Projekt im Format 2 liefert es als Eintrag registerCom aus wie jeden COM-Server.
• Computer, die Programme im Benutzerprofil mit AppLocker oder Windows Defender Application Control einschränken, werden nicht unterstützt.
• Eine Quelle über HTTP/HTTPS wird nicht unterstützt; die Quelle ist ein Ordner oder eine Freigabe.

• Die Projektdatei (Format 2)
• Signierte Auslieferung veröffentlichen
• Projekt aus Vorlagen erstellen
• Private .NET-Runtime ausliefern
• Was der Starter schreibt und meldet (1.0.1)
• Anwendung von einem PC entfernen (1.0.1, von Hand)
• Fehlercodes des Starters