Die Projektdatei (Format 2)

Ein JSON-Objekt mit "format": 2, UTF-8, Kommentare und nachgestellte Kommas erlaubt, im Ordner des Starters. Der Starter nimmt in dieser Reihenfolge:

1. die .json-Datei, die /RUNCFG <file> nennt (ein bloßer Dateiname im Ordner des Starters);
2. (ab Version 2.3.0) <name>.bootstrapper.json, benannt nach der EXE-Datei des Starters, sofern vorhanden – demo.bootstrapper.json für demo.exe, so wie in .NET demo.exe.config zu demo.exe gehört;
3. bootstrapper.json.

Der Starter darf umbenannt werden (demo.exe): Er liest seinen Ordner unabhängig von seinem Namen, und die Verknüpfungen ([Starter]) und der Eintrag unter „Apps“ nennen die umbenannte Datei: Installieren, Aktualisieren, Starten ohne Quelle, /list und /uninstall verhalten sich gleich. Ab Version 2.3.0 teilen sich mehrere umbenannte Starter einen Ordner, einer je Profil, jeder mit eigener Projektdatei und ohne /RUNCFG in einer Verknüpfung:

Jedes Profil braucht ein eigenes product; zwei Projektdateien mit demselben Produktschlüssel ersetzen auf dem PC eines Benutzers gegenseitig ihre Installation. Der Eintrag unter „Apps“ entfernt das Produkt über den Starter unter dem Pfad, von dem aus er gestartet wurde; ein Starter auf einer Freigabe, die nicht mehr erreichbar ist, kann es von dort nicht entfernen – starten Sie /uninstall aus einer erreichbaren Kopie des Starters.

Format 1 und Format 2 sind Formate nur dieser Datei. Die Projektdatei des Build-Werkzeugs der WKL Forms Object Library (access-app.json) ist eine andere Datei mit eigenem Format, und der Starter liest sie nie; von einem Build liest der Starter nur die app-manifest.json, die das Build-Werkzeug in jeden Auslieferungsordner schreibt (version.from); ihr eigenes Feld format ist die Version des Schemas des Manifests, nicht eines der Formate dieser Datei. Ob eine Anwendung über Format 1 oder Format 2 läuft, entscheidet die bootstrapper.json, die ihr Administrator neben den Starter legt, nicht die Anwendung.

{
  "format": 2,
  "product": "Kasse",
  "display": { "name": "Kasse Pro", "publisher": "Contoso", "copyright": [ "(c) 2026 Contoso" ], "logo": "logo.png" },
  "version": { "value": "3.2.1" },
  "source": "\\\\server\\share\\kasse",
  "deliveryKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
  "files": [
    { "id": "bin", "source": "bin", "target": "[VersionDir]" },
    { "source": "com\\x86", "target": "[AppDir]\\com", "action": "registerCom", "bitness": "x86" }
  ],
  "registry": [ { "key": "Software\\Contoso\\Kasse", "values": [ { "name": "Home", "data": "[Dir:bin]" } ] } ],
  "shortcuts": [ { "folder": "[Programs]\\Contoso", "name": "Kasse", "target": "[Starter]", "arguments": "[RunConfig]" } ],
  "fileTypes": [ { "extension": ".kasse", "progId": "Contoso.Kasse", "description": "Kassenbeleg", "command": "\"[Starter]\" [RunConfig] \"%1\"" } ],
  "actions": [ { "when": "beforeInstall", "program": "setup\\vc_redist.x86.exe", "arguments": "/install /quiet /norestart", "successCodes": [ 0, 3010 ] } ],
  "conditions": [ { "kind": "dotnet", "value": "Microsoft.WindowsDesktop.App 10.0", "message": ".NET 10 is missing.", "link": "https://dot.net" } ],
  "start": { "file": "[VersionDir]\\Kasse.exe", "arguments": "/mode kiosk" },
  "keepVersions": 2
}

Was der Starter für den Windows-Benutzer installiert, was er registriert, welche Bedingungen er prüft, welche Programme er ausführt und was er startet – jedes beliebige Programm oder jede Datei; eine Access-Anwendung ist ein Fall unter anderen. Der Starter führt das ohne Administratorrechte aus, als eine Transaktion mit Rollback, gezählt und entfernbar unter Einstellungen › Apps.

Jedes Ziel, in das der Starter schreibt (appDir, versionDir, ein files-Ziel, ein Verknüpfungsordner, die INI-Datei), ist ein Platzhalterpfad unterhalb eines Ordners des Benutzers; ein Ziel außerhalb davon, .. in einem Pfad, ein Schlüssel der Registrierungsdatenbank, der einen anderen Stamm nennt, und ein unbekannter Platzhalter werden abgelehnt, bevor etwas ausgeführt wird (Code 11).

Ordner des Benutzers – dürfen ein Ziel einleiten. Vor 2.3.0 gab es nur [LocalAppData], [AppData], [Documents], [Desktop], [Programs] und [Startup].

Die Bibliotheken sowie [Downloads], [LocalAppDataLow] und [UserPrograms] werden als bekannte Ordner von Windows gelesen; ein Ordner, den Windows auf diesem PC nicht benennen kann, bleibt ohne Wert, und ein Ziel darunter wird wie ein unbekannter Platzhalter abgelehnt.

Ordner des Computers – werden überall aufgelöst, wo ein Platzhalter stehen darf, der kein Ziel ist: start (Datei, Argumente, Ordner, Umgebung), actions, conditions und Daten in der Registrierungsdatenbank. Sie leiten nie ein Ziel ein: Dort zu schreiben erfordert Administratorrechte.

Platzhalter des Projekts:

Dateien unterhalb von [VersionDir] gehören zu ihrer Version: einmal abgelegt, nie ersetzt (ein Programm, das in seinen Ordner schreibt, behält seine Daten), mit der Version entfernt. Dateien an jeder anderen Stelle sind gemeinsam genutzt und werden gezählt: Derselbe Ordner, den zwei Produkte verwenden, bleibt, bis das letzte davon entfernt wird; eine Datei, die in einer späteren Auslieferung geändert ist, wird ersetzt.

Jeder Start liest das Projekt, prüft die Bedingungen und installiert die ausgelieferte Version, wenn sie neu oder unvollständig ist: Dateien, Werte in der Registrierungsdatenbank, Dateitypen, Verknüpfungen, die INI-Datei, den vertrauenswürdigen Speicherort (nur wenn start.file eine Access-Datenbank ist) und den Eintrag unter „Apps“; danach führt er die afterInstall-Aktionen aus, alles in einer Transaktion. Anschließend entfernt er Versionen über keepVersions hinaus (nie die gestartete und nie die zuletzt funktionierende) und startet start.file. Ein Fehler auf diesem Weg rollt alles zurück; die Codes sind die der Fehlercodes des Starters.

Ist die Quelle nicht erreichbar (Code 12) oder ihre Auslieferung nicht vertrauenswürdig (Code 51), startet die installierte Version – die zuletzt funktionierende, sonst die neueste –, und das Update wartet bis zum nächsten Start. Eine Diagnose (/diagnose) meldet die Quelle so, wie sie ist.

delivery.json in der Quelle listet jede Datei der ausgelieferten Version mit Größe und SHA-256 auf; delivery.json.sig daneben ist ihre Signatur mit dem Lieferschlüssel des Herausgebers (ECDSA P-256). /publish schreibt beide.

Jede Kopie wird nach dem Kopieren gegen das Manifest geprüft, sodass auch eine Datei, die zwischen Prüfung und Kopieren geändert wurde, nicht installiert wird.

Rückkehr zu einer früheren Version. Mit deliveryKey vergleicht der Starter die ausgelieferte Version mit der höchsten, die der Benutzer von dem Produkt je installiert hat (auch nach einer Bereinigung oder Deinstallation), in der Reihenfolge unter Versionen. Eine niedrigere Version wird nur installiert, wenn withdrawn in delivery.json diese höchste Version nennt; /publish /withdraw schreibt das Feld (siehe Signierte Auslieferung veröffentlichen). Ohne deliveryKey wird eine niedrigere Version wie bisher installiert.

Nicht abgedeckt. Die Signatur deckt die Dateien von files ab. Programme von actions laufen direkt aus der Quelle und werden nicht gegen delivery.json geprüft: Wer in die Quelle schreiben kann, kann sie ändern, und sie laufen mit den Rechten jedes Benutzers, der die Anwendung startet. Eine früher signierte Auslieferung bleibt gültig; ein Starter, der eine höhere Version installiert hatte, weist sie ab (Code 52), ein Benutzer ohne höhere Version installiert sie aber. Schützen Sie den Schreibzugriff auf die Quelle. Der Vertrauensanker ist der Ordner des Starters mit seiner Projektdatei: Der Lieferschlüssel schützt eine Auslieferung nur, solange Benutzer bootstrapper.json nicht ändern können, etwa wenn die IT den Starter mit dem MSI unter „Programme“ installiert. Ein Starter samt Projektdatei auf der Freigabe oder im Profil lässt sich zusammen mit dem Schlüssel ändern.

Der Lieferschlüssel gehört dem Herausgeber selbst; er kostet keine Codesignatur. Die Anwendungssteuerung von Windows prüft nur Authenticode-Signaturen von Programmen und Bibliotheken, die der Herausgeber wie bisher mit dem Firmenzertifikat signiert.

Der Starter führt auf dem Computer eines Benutzers nie die eigene Registrierung eines Servers aus (DllRegisterServer, regsvr32): Er schreibt die Registrierung aus registration.json, die tools\Export-ComRegistration.ps1 auf dem Computer des Herausgebers erfasst. Bringen zwei Produkte denselben Server in verschiedenen Releases mit, bleibt das neuere registriert; wird es entfernt, wird das verbleibende wieder registriert. Siehe Signierte Auslieferung veröffentlichen.

Ein Programm läuft mit den Rechten des Benutzers; ein Setup, das Administratorrechte braucht, scheitert mit seinem Exitcode (Code 43). Solche Voraussetzungen gehören in die Erstinstallation durch die IT.

beforeUninstall-Aktionen laufen einmal je Deinstallation, unabhängig von once, bevor etwas entfernt wird. Ihre Platzhalter werden für die Version aufgelöst, die der Starter zuletzt starten würde ([VersionDir] ist diese installierte Version). Ein relatives program wird aus der Quelle genommen, die bis dahin verschwunden sein kann (eine Freigabe, die nicht mehr erreichbar ist, eine entfernte Auslieferung): Das Programm kann nicht starten, die Deinstallation hält mit Code 43 an, und nichts wird entfernt. Lassen Sie solche Programme stattdessen auf die installierte Kopie zeigen ([VersionDir]\...).

message und link der Bedingung erscheinen in den Diagnosedetails.

Eine Datei mit "format": 1 (eine Access-Anwendung, der Starter 1.0) wird als Projekt gelesen: die Datenbank aus app-manifest.json nach [VersionDir] (der Ordner, den 1.0 verwendet hat), die WKL-Komponenten und ODBC-Treiber je Release und Bitbreite unterhalb von [WklRoot], die Datenquelle jedes Treibers, die Prüfungen der Einstellungen als Bedingungen, die Datenbank als Startziel. Dateien im Format 1 funktionieren unverändert weiter; ein vom WKL Bootstrapper Manager geschriebenes Projekt im Format 2 ersetzt eine solche Datei bei Bedarf. Ob der Installer von 2.0 eine Auslieferung im Format 1 übernimmt oder ob sie auf dem Weg von 1.0 läuft, hängt von ihrem Komponentenordner ab: mit registration.json neben der DLL (oder ohne Komponenten) der Installer, sonst der Weg von 1.0 – siehe Wann 2.0 installiert und wann 1.0 läuft.

Eine Datei im Format 1:

{
  "format": 1,
  "product": "INSTRA",
  "displayName": "INSTRA Verwaltung",
  "source": "\\\\server\\apps\\INSTRA\\production",
  "components": "components",
  "ini": { "file": "TECCUsr.ini", "values": [ { "section": "Properties", "key": "SRV", "value": "sql01" } ] },
  "branding": { "logo": "logo.png", "company": "Contoso", "preparing": "Die neue Version wird eingerichtet ..." },
  "command": "mandant=2",
  "odbcDrivers": [ "ODBC Driver 18 for SQL Server" ],
  "language": "",
  "colorScheme": "automatic",
  "keepVersions": 2
}

Ein Programm, das keine Access-Anwendung ist, in einem eigenen Ordner je Version, gestartet mit Argumenten:

{
  "format": 2,
  "product": "Lager",
  "display": { "name": "Lagerverwaltung", "publisher": "Contoso" },
  "version": { "from": "bin\\Lager.exe" },
  "source": "\\\\server\\share\\lager",
  "files": [ { "source": "bin", "target": "[VersionDir]" } ],
  "shortcuts": [ { "folder": "[Desktop]", "name": "Lager", "target": "[Starter]", "arguments": "[RunConfig]" } ],
  "start": { "file": "[VersionDir]\\Lager.exe", "arguments": "/user \"[Product]\"" }
}

• Der Installer des Bootstrappers 2.0 – Transaktion, Zählung, Befehle
• Signierte Auslieferung veröffentlichen
• Projekt aus Vorlagen erstellen
• Beliebiges Programm mit dem Starter starten
• Private .NET-Runtime ausliefern
• Fehlercodes des Starters