The installer settings (<name>.msi.json)

The installer settings describe the Windows Installer package (MSI) that the IT installs once and that places the starter on a computer: the data of the package, whether it installs per computer and/or per user, the dialogs the person installing sees and their texts per language. They lie beside the project file and are read only when the MSI is built; the starter never reads them when it starts, and they never reach the users' PCs through a delivery.

Requires WKL Bootstrapper 2.3.0 or later. /check checks the file, /msi-sources writes the WiX sources from it, and tools/New-StarterMsi.ps1 builds the packages.

The file is named after the project file, in the same folder:

Paths in the file (icon, license, banner, dialog picture, fragments) are relative to the file's folder and may not leave it (..).

tools\New-StarterMsi.ps1 -Project <project file> builds one package per scope and language:

The WiX sources stay in <output folder>\<product>.wix (machine.wxs, user.wxs, ui.wxs, one .wxl per culture), where they can be read or built by hand; -SourcesOnly writes only them. The per-computer package keeps the upgrade code of the packages built before 2.3.0, so a new package replaces an old one; the per-user package has its own code, so the two never replace each other.

The package places the starter, its project file, the INI file of the dialog values and the logo, and creates the shortcuts. Everything per user - copying the application, components, trusted location, start - stays the starter's work on each start (see The installer). Values entered in an own page are written to the INI file beside the starter, where the application reads them; the starter itself does not interpret them.

{
  "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" ]
}

Comments (//) and trailing commas are allowed. Unknown keys are refused, so a misspelt key never builds a package that silently lacks a dialog.

• Every value of an own page is written to the INI file beside the starter (demo.ini beside demo.exe, section [Settings]): KEY=value, a check box as 1 or 0. The application reads the file; the starter does not. To tell the application where the file lies, pass its path in the project's start.environment, for example "WKL_SETTINGS": "[StarterDir]\[StarterName].ini" (see The project file); the application reads Environ("WKL_SETTINGS").
• The IT can set every value without dialogs on the command line, with the property name: msiexec /i Demo-1.2.0-machine-de-DE.msi /qn SERVER=https://data.company.com MODE=test LOGGING=0. 0 clears a check box.
• The values are remembered (HKEY_LOCAL_MACHINE per computer, HKEY_CURRENT_USER per user, key Software\WKL\Starter\<product>\Settings). A later “Change” from the maintenance dialog or from Apps starts from them and writes the INI file again; a repair keeps them.
• Order: a value from the command line wins over the remembered one, the remembered one over the default.

Every text the person installing reads (title, description, label, hint, text of an option, launchText) is written either as one string, valid for every language, or as an object with one string per culture:

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

A culture without its own text takes the string for every language, else stays empty.

An own page appears in the frame of the standard dialogs (banner with title and description, Back/Next/Cancel) and holds controls from top to bottom.

The starter checks these rules with /check <name>.msi.json (exit code 0 valid, 11 problems; /json lists every problem for Bootstrapper Manager). The first broken rule is named with what breaks it:

• scopes names machine and/or user, each once.
• dialogs.install begins with welcome and ends with verify, each once, and shows no standard dialog twice: the person installing confirms before anything changes.
• installFolder begins with a standard folder of its scope (see the keys) and has a path below it.
• Every page of pages is shown in dialogs.install, and every page:<id> names a page.
• license in dialogs.install needs package.license.
• Properties are upper-case and used once.
• A property or INI key that looks like a password (pass, pwd, secret, token, kennwort) is refused: the INI file beside the starter is readable by every user of the computer. Secrets belong in the application's own sign-in.
• The default of radio and combo is one of the options; the default of checkbox is 1 or empty.
• maxLength applies to edit only.
• languages names only cultures of the list; texts only cultures of languages.
• package.version is two or three numbers, package.upgradeCode a GUID.
• Files have the right ending (.ico, .rtf, .bmp/.png, .wxs), are relative and without ..; when the file is valid, /check also names every file that is missing beside it.
• ini.file is a plain file name ending in .ini; ini.section has no brackets.
• Unknown keys are refused.
• Building the sources (/msi-sources) refuses an own page whose controls do not fit into the dialog in every language; it names how many dialog units the page needs. Split it into two pages or shorten the texts.

• The project file: the file the installer settings are named after.
• The installer: what the starter does per user after the package has placed it.
• How to: Roll out the starter with an MSI: building and handing over the packages.