Die Installer-Einstellungen (<name>.msi.json)

Die Installer-Einstellungen beschreiben das Windows-Installer-Paket (MSI), das die IT einmal installiert und das den Starter auf einem Computer ablegt: die Daten des Pakets, ob es je Computer und/oder je Benutzer installiert, die Dialoge, die die installierende Person sieht, und deren Texte je Sprache. Sie liegen neben der Projektdatei und werden nur beim Bau des MSI gelesen; der Starter liest sie nie, wenn er startet, und sie gelangen nie über eine Auslieferung auf die PCs der Benutzer.

Voraussetzungen: WKL Bootstrapper 2.3.0 oder höher. /check prüft die Datei, /msi-sources schreibt daraus die WiX-Quellen, und tools/New-StarterMsi.ps1 baut die Pakete.

Die Datei ist nach der Projektdatei benannt und liegt im selben Ordner:

Pfade in der Datei (Symbol, Lizenz, Banner, Dialogbild, Fragmente) sind relativ zum Ordner der Datei und dürfen ihn nicht verlassen (..).

tools\New-StarterMsi.ps1 -Project <project file> baut ein Paket je Bereich und Sprache:

Die WiX-Quellen bleiben in <output folder>\<product>.wix (machine.wxs, user.wxs, ui.wxs, eine .wxl je Kultur), wo sie sich lesen oder von Hand bauen lassen; -SourcesOnly schreibt nur sie. Das Paket je Computer behält den Upgradecode der vor 2.3.0 gebauten Pakete, sodass ein neues Paket ein altes ersetzt; das Paket je Benutzer hat einen eigenen Code, sodass sich die beiden nie gegenseitig ersetzen.

Das Paket legt den Starter, seine Projektdatei, die INI-Datei der Dialogwerte und das Logo ab und erstellt die Verknüpfungen. Alles je Benutzer – die Anwendung kopieren, Komponenten, vertrauenswürdiger Speicherort, Start – bleibt Aufgabe des Starters bei jedem Start (siehe Der Installer). Werte, die auf einer eigenen Seite eingegeben werden, werden in die INI-Datei neben dem Starter geschrieben, wo die Anwendung sie liest; der Starter selbst wertet sie nicht aus.

{
  "format": 1,
  "package": { "name": "Demo", "manufacturer": "Contoso", "license": "installer\\license.rtf", "banner": "installer\\banner.png" },
  "scopes": [ "machine", "user" ],
  "shortcuts": { "startMenu": true, "desktop": true },
  "languages": [ "de-DE", "en-US" ],
  "texts": { "de-DE": { "WelcomeDlgTitle": "Willkommen bei Demo" } },
  "dialogs": { "install": [ "welcome", "license", "folder", "page:server", "verify" ], "exit": { "launch": true } },
  "pages": [
    { "id": "server", "title": { "de-DE": "Datendienst", "en-US": "Data service" }, "description": "URL",
      "controls": [
        { "type": "text", "label": "Where the application finds its data." },
        { "type": "edit", "property": "SERVER", "label": "URL", "default": "https://", "required": true, "maxLength": 200 },
        { "type": "radio", "property": "MODE", "label": "Mode", "default": "live",
          "options": [ { "value": "live", "text": "Live" }, { "value": "test", "text": "Test" } ] }
      ] }
  ],
  // The values go to demo.ini beside demo.exe, section [Settings].
  "ini": { "section": "Settings" },
  "fragments": [ "installer\\extra.wxs" ]
}

Kommentare (//) und nachgestellte Kommas sind erlaubt. Unbekannte Schlüssel werden abgelehnt, damit ein falsch geschriebener Schlüssel nie ein Paket baut, dem stillschweigend ein Dialog fehlt.

• Jeder Wert einer eigenen Seite wird in die INI-Datei neben dem Starter geschrieben (demo.ini neben demo.exe, Abschnitt [Settings]): KEY=value, ein Kontrollkästchen als 1 oder 0. Die Anwendung liest die Datei, der Starter nicht. Damit die Anwendung weiß, wo die Datei liegt, übergeben Sie ihren Pfad in start.environment des Projekts, zum Beispiel "WKL_SETTINGS": "[StarterDir]\[StarterName].ini" (siehe Die Projektdatei); die Anwendung liest Environ("WKL_SETTINGS").
• Die IT kann jeden Wert ohne Dialoge in der Befehlszeile setzen, mit dem Namen der Eigenschaft: msiexec /i Demo-1.2.0-machine-de-DE.msi /qn SERVER=https://data.company.com MODE=test LOGGING=0. 0 leert ein Kontrollkästchen.
• Die Werte werden gespeichert (HKEY_LOCAL_MACHINE je Computer, HKEY_CURRENT_USER je Benutzer, Schlüssel Software\WKL\Starter\<product>\Settings). Ein späteres „Ändern“ aus dem Wartungsdialog oder aus „Apps“ geht von ihnen aus und schreibt die INI-Datei neu; eine Reparatur behält sie.
• Reihenfolge: Ein Wert aus der Befehlszeile hat Vorrang vor dem gespeicherten, der gespeicherte vor dem Standardwert.

Jeder Text, den die installierende Person liest (title, description, label, hint, text einer Option, launchText), wird entweder als eine Zeichenfolge geschrieben, die für jede Sprache gilt, oder als Objekt mit einer Zeichenfolge je Kultur:

"title": "Server"
"title": { "de-DE": "Datendienst", "en-US": "Data service" }

Eine Kultur ohne eigenen Text erhält die Zeichenfolge für jede Sprache, sonst bleibt sie leer.

Eine eigene Seite erscheint im Rahmen der Standarddialoge (Banner mit Titel und Beschreibung, Zurück/Weiter/Abbrechen) und enthält Steuerelemente von oben nach unten.

Der Starter prüft diese Regeln mit /check <name>.msi.json (Exitcode 0 gültig, 11 Probleme; /json listet jedes Problem für den Bootstrapper Manager auf). Die erste verletzte Regel wird mit dem genannt, was sie verletzt:

• scopes nennt machine und/oder user, jedes einmal.
• dialogs.install beginnt mit welcome und endet mit verify, jedes einmal, und zeigt keinen Standarddialog zweimal: Die installierende Person bestätigt, bevor sich etwas ändert.
• installFolder beginnt mit einem Standardordner seines Bereichs (siehe die Schlüssel) und hat einen Pfad darunter.
• Jede Seite aus pages wird in dialogs.install angezeigt, und jedes page:<id> nennt eine Seite.
• license in dialogs.install erfordert package.license.
• Eigenschaften sind in Großbuchstaben geschrieben und werden einmal verwendet.
• Eine Eigenschaft oder ein INI-Schlüssel, der wie ein Kennwort aussieht (pass, pwd, secret, token, kennwort), wird abgelehnt: Die INI-Datei neben dem Starter ist für jeden Benutzer des Computers lesbar. Geheimnisse gehören in die eigene Anmeldung der Anwendung.
• Der Standard von radio und combo ist eine der Optionen; der Standard von checkbox ist 1 oder leer.
• maxLength gilt nur für edit.
• languages nennt nur Kulturen aus der Liste; texts nur Kulturen aus languages.
• package.version besteht aus zwei oder drei Zahlen, package.upgradeCode ist eine GUID.
• Dateien haben die richtige Endung (.ico, .rtf, .bmp/.png, .wxs), sind relativ und ohne ..; ist die Datei gültig, nennt /check außerdem jede Datei, die daneben fehlt.
• ini.file ist ein bloßer Dateiname, der auf .ini endet; ini.section hat keine Klammern.
• Unbekannte Schlüssel werden abgelehnt.
• Der Bau der Quellen (/msi-sources) lehnt eine eigene Seite ab, deren Steuerelemente nicht in jeder Sprache in den Dialog passen; er nennt, wie viele Dialogeinheiten die Seite braucht. Teilen Sie sie auf zwei Seiten auf oder kürzen Sie die Texte.

• Die Projektdatei: die Datei, nach der die Installer-Einstellungen benannt sind.
• Der Installer: was der Starter je Benutzer tut, nachdem das Paket ihn abgelegt hat.
• Starter per MSI verteilen: die Pakete bauen und übergeben.