JSON Configuration

Not every team writes C#. For simple, data-driven installers FalkForge can build from JSON configuration files instead — no code required. Define your product, files, and features in JSON; run forge build config.json to produce an MSI. (JSON also authors the Firewall, IIS, and SQL extensions — see sections 5 and 6.)

1. Minimal JSON Installer

Open demo/json/01-minimal.json. This is the simplest possible JSON installer — 17 lines.

{
  "product": {
    "name": "MinimalApp",
    "manufacturer": "Contoso",
    "version": "1.0.0"
  },
  "ui": "Minimal",
  "features": [
    {
      "id": "Complete",
      "title": "Complete",
      "files": [
        { "source": "payload/MinimalApp.exe" }
      ]
    }
  ]
}

Three things make up every JSON installer:

• product — name, manufacturer, and version. These appear in Programs & Features.
• ui — the dialog template. "Minimal" shows a single Install button.
• features — at least one feature containing the files to install.

Build it:

forge build demo/json/01-minimal.json

FalkForge reads the JSON, validates the structure, and produces an MSI. No C# project, no compilation step.

2. Install Directory Selection

Open demo/json/02-installdir.json. This adds directory selection and upgrade handling.

{
  "product": {
    "name": "NotepadClone",
    "manufacturer": "Contoso",
    "version": "2.1.0",
    "description": "A simple text editor",
    "upgradeCode": "12345678-1234-1234-1234-123456789012"
  },
  "ui": "InstallDir",
  "installDirectory": "Contoso/NotepadClone",
  "majorUpgrade": {},
  "features": [ ... ],
  "downgrade": {
    "message": "A newer version is already installed."
  }
}

Key additions over the minimal example:

• ui: "InstallDir" — shows a directory chooser dialog so users can pick where files go.
• installDirectory — the default install path under Program Files. "Contoso/NotepadClone" becomes C:\Program Files\Contoso\NotepadClone.
• majorUpgrade — enables automatic upgrade detection. Windows removes the old version before installing the new one. Takes an optional schedule field naming the MSI RemoveExistingProducts schedule; an empty object uses the builder's default.
• downgrade — a separate top-level object (not nested inside majorUpgrade) with allow (bool) and message (block message shown when a newer version is already installed and allow is false, the default).
• upgradeCode — a fixed GUID that ties all versions together. Set this once and never change it.

Features can also contain registry entries and shortcut definitions on files:

"files": [
  {
    "source": "payload/NotepadClone.exe",
    "shortcut": {
      "name": "NotepadClone",
      "location": "Desktop",
      "description": "Launch NotepadClone"
    }
  }
],
"registry": [
  {
    "root": "HKCU",
    "key": "Software\\Contoso\\NotepadClone",
    "name": "Version",
    "value": "2.1.0"
  }
]

3. Feature Trees

Open demo/json/03-featuretree.json. This installer defines a tree of selectable features.

"features": [
  {
    "id": "CoreTools",
    "title": "Core Tools",
    "description": "Essential developer tools",
    "required": true,
    "files": [ ... ]
  },
  {
    "id": "Plugins",
    "title": "Plugins",
    "features": [
      { "id": "GitPlugin", "title": "Git Integration", ... },
      { "id": "DockerPlugin", "title": "Docker Support", "default": false, ... }
    ]
  },
  {
    "id": "BackgroundService",
    "title": "Background Service",
    "default": false,
    "services": [ ... ]
  }
]

Feature properties:

• required: true — always installed; the user cannot deselect it.
• default: true (the default) — selected by default but the user can turn it off.
• default: false — not selected by default; the user opts in.
• Nested features — child features appear indented in the tree. Deselecting the parent deselects all children.

The "services" array on the BackgroundService feature installs a Windows service:

"services": [
  {
    "name": "DevToolkitSvc",
    "displayName": "DevToolkit File Watcher",
    "executable": "[INSTALLDIR]devtoolkit-svc.exe",
    "startType": "Manual",
    "account": "LocalService"
  }
]

Use ui: "FeatureTree" to show the selection dialog.

"launchConditions": [
  {
    "condition": "VersionNT64",
    "message": "This application requires a 64-bit operating system."
  }
]

4. Advanced Configuration

Open demo/json/05-advanced.json. This demo exercises most JSON features: registry, shortcuts, services, environment variables, license files, and multiple launch conditions.

Registry entries

"registry": [
  {
    "root": "HKLM",
    "key": "Software\\Contoso\\AdvancedDemo",
    "name": "InstallDir",
    "value": "[INSTALLDIR]"
  }
]

The root accepts HKLM, HKCU, HKCR, HKU, and HKMU. Values can reference MSI properties like [INSTALLDIR].

Environment variables

"environmentVariables": [
  {
    "name": "ADVANCED_HOME",
    "value": "[INSTALLDIR]",
    "action": "Set",
    "system": true
  },
  {
    "name": "PATH",
    "value": "[INSTALLDIR]bin",
    "action": "Append",
    "system": true
  }
]

Actions: Set (overwrite), Append (add to existing), Remove (delete on install). Set system: false for per-user variables.

Services and nested features

The advanced config defines two services under a parent "Background Services" feature, each with its own startType: "Automatic", "DelayedAutomatic", or "Manual". Services are cleanly removed on uninstall.

License and UI template

"ui": "Advanced",
"license": "payload/eula.rtf"

The "Advanced" template adds typical/custom/complete install types. The license file is shown in a scrollable panel before the user can proceed.

5. Web Server Installer

Open demo/json/06-web-server.json. It installs a web app and authors a firewall rule plus an IIS application pool and web site — all from JSON, emitted into the compiled MSI.

Firewall rules

"extensions": {
  "firewall": [
    {
      "id": "HttpRule",
      "name": "WebServerApp HTTP",
      "protocol": "Tcp",
      "port": "80",
      "direction": "Inbound",
      "action": "Allow",
      "profile": "All"
    }
  ]
}

Each rule gets a unique id and must specify port or program. Supported profiles: All, Domain, Private, Public. The rule is authored into the MSI's WixFirewallException table, which creates the rule on install and removes it on uninstall — the same output the C# Firewall extension produces.

IIS app pools and web sites

"iis": {
  "appPools": [
    {
      "id": "WebAppPool",
      "name": "WebServerAppPool",
      "runtimeVersion": "v4.0",
      "pipelineMode": "Integrated",
      "identity": "ApplicationPoolIdentity"
    }
  ],
  "webSites": [
    {
      "id": "WebSite",
      "description": "WebServerApp Site",
      "directory": "[INSTALLDIR]",
      "appPool": "WebAppPool",
      "bindings": [
        { "protocol": "http", "port": 80, "host": "localhost" },
        { "protocol": "https", "port": 443, "host": "localhost" }
      ]
    }
  ]
}

The appPool field on a web site references an app pool by its id in the JSON document. Bindings support http and https protocols with configurable port and host header. The app pool and web site are authored into the MSI's IIsAppPool and IIsWebSite tables — the same output the C# IIS extension produces.

6. Database Application

Open demo/json/07-database-app.json. It installs a database app and provisions a SQL database with an install script — authored from JSON and emitted into the compiled MSI.

SQL database creation

"extensions": {
  "sql": [
    {
      "id": "AppDatabase",
      "server": "[SQLSERVER]",
      "database": "ContosoDb",
      "createOnInstall": true,
      "dropOnUninstall": false,
      "scripts": [
        {
          "id": "CreateSchema",
          "sourceFile": "payload/sql/create-schema.sql",
          "executeOnInstall": true,
          "sequence": 1
        },
        {
          "id": "SeedData",
          "sourceFile": "payload/sql/seed-data.sql",
          "executeOnInstall": true,
          "sequence": 2
        }
      ]
    }
  ]
}

Key fields:

• server — the SQL Server instance. [SQLSERVER] is an MSI property the user sets at install time (via the UI or command line: msiexec /i app.msi SQLSERVER=.\SQLEXPRESS).
• createOnInstall — creates the database if it doesn't exist.
• dropOnUninstall — set to false to preserve data after uninstall. Use true only for development or disposable databases.
• scripts — SQL files executed in sequence order. Schema first, then seed data.

.NET runtime detection (MSI-native)

"dotnet": [
  {
    "runtimeType": "Runtime",
    "platform": "X64",
    "minimumVersion": "8.0.0",
    "variableName": "DOTNET8_INSTALLED",
    "message": ".NET 8 Runtime is required to run this application."
  }
]

The JSON dotnet block reaches the compiled installer via the same DotNetExtension the C# API attaches, emitting real MSI-native detection — a Signature (sentinel-file version) plus a DrLocator search over the platform-appropriate shared-framework directory, bound to variableName via AppSearch (see Reference Docs §10.5 .NET Extension). runtimeType, platform, minimumVersion, and variableName are required (JSN014 if any is missing); message is optional. variableName must be an all-uppercase public MSI property identifier (NET005 otherwise); runtimeType: "Sdk" is not supported for MSI-native detection because the SDK has no shared-framework sentinel to search for (NET004). Because the JSON path has no separate call like the C# fluent API's package.Require(...), DotNetExtension always emits its own LaunchCondition gate using message — or, if message is omitted, a generated default naming the exact requirement.

msiexec /i DatabaseApp.msi /qn SQLSERVER=dbserver\SQLEXPRESS

7. Signed Bundle Output (signing section)

An optional top-level "signing" section makes forge build wrap the compiled MSI in a single-package EXE bundle whose integrity manifest is ECDSA-signed through the ISignatureProvider seam (optionally hybrid post-quantum — see below). Without a signing section the build keeps its normal MSI-only output.

No secrets ever go in the JSON file. Keys and credentials are referenced by file path or by environment variable name (the *Env fields); the values are read from the environment at build time. The loader rejects inline secret material (JSN016), and any referenced environment variable that is unset at build time fails the build (JSN019) — it never falls back to unsigned output or an unauthenticated signing request.

Local PEM key

"signing": {
  "provider": "pem",
  "keyPath": "keys/release.pem"
}

Exactly one key source is required: keyPath (an ECDSA private-key PEM file, relative paths resolve against the config file) or keyEnv (the name of an environment variable whose value is the PEM, so the key never touches the config or the repo).

Hybrid post-quantum signing (pem provider only)

"signing": {
  "provider": "pem",
  "keyPath": "keys/release.pem",
  "pqKeyPath": "keys/release-mldsa.pem"
}

Adding pqKeyPath or pqKeyEnv to the pem provider turns the build hybrid: the manifest is signed by both the classical ECDSA key and an ML-DSA (FIPS 204, post-quantum) companion key — the field's presence is the switch, there is no separate flag. The PQ key follows the exact same secret rules as the classical key: pqKeyPath is a PEM file path and pqKeyEnv is an environment variable name holding the PEM — never paste key material into the config (JSN016), use at most one of the two (JSN017), and an unset environment variable fails the build (JSN019); the build never silently falls back to a classical-only bundle.

pqKeyPath/pqKeyEnv are rejected on the signserver provider (JSN018): SignServer cannot yet produce the context-bound ML-DSA signature FalkForge requires, and failing loud beats emitting a bundle the author believes is hybrid-signed but is not. See the manual's “Post-Quantum Hybrid Signing” section and Demo 63 (hybrid-pq-signing) for the trust-pinning half (the engine-side companion pin that makes stripping the PQ signature a hard failure).

Keyfactor SignServer (remote signing)

"signing": {
  "provider": "signserver",
  "baseUrl": "https://signserver.example.com:8443",
  "worker": "PlainSigner",
  "authMode": "bearer",
  "bearerTokenEnv": "SIGNSERVER_TOKEN"
}

authMode is one of none, basic (usernameEnv + passwordEnv), bearer (bearerTokenEnv), or clientcert (clientCertPathEnv naming an env var that holds a PFX path, plus optional clientCertPasswordEnv). An optional keyId labels the signature in the envelope. An http:// base URL or authMode: "none" builds with a warning — acceptable for local SignServer CE test containers only.

The bundle produced this way embeds the published NativeAOT engine as its self-extracting front, so it is a runnable installer. The compiler resolves the engine automatically: from the FALKFORGE_ENGINE_STUB environment variable, from an engine directory next to the forge executable, or from the repository’s artifacts/publish/engine output (run scripts/publish.ps1 once). If no engine can be found the build fails with an actionable message. To build a non-runnable design-time bundle anyway (signing/verification tooling, CI without an engine publish), pass --no-engine — the build then prints a “NOT a runnable installer” warning.

Recap: JSON vs C# decision guide

Start with JSON for straightforward installers and CI/CD pipelines — including those needing the Firewall, IIS, SQL, or .NET-detection extensions. Move to C# — the primary path — when you need custom actions, conditional features, or advanced MSI capabilities. For the fields JSON does support, both produce identical MSI output.