EXE Bundles

An MSI installs one product. A bundle installs several — multiple MSIs, EXEs, patches, and prerequisites — in a single self-extracting EXE. FalkForge's bundle engine is NativeAOT compiled, so it runs without a .NET runtime.

1. Your First Bundle

Open demo/35-bundle-simple/Program.cs. The entire bundle definition fits in one screen.

Entry point

return Installer.BuildBundle(args, outputPath =>
{
    var bundle = new BundleBuilder()
        .Name("Simple Bundle")
        .Manufacturer("Demo")
        .Version("1.0.0")
        .BundleId(new Guid("..."))
        .UpgradeCode(new Guid("..."))
        .Scope(InstallScope.PerMachine)
        .UseBuiltInUI(themeColor: "#0078D4")
        .Chain(chain => chain
            .MsiPackage("MyApp.msi", p => p
                .Id("MyApp")
                .DisplayName("My Application")
                .Vital(true)))
        .Build();

    return new BundleCompiler().Compile(bundle, outputPath);
});

Installer.BuildBundle is the bundle counterpart to Installer.Build. Where an MSI uses PackageBuilder and MsiCompiler, a bundle uses BundleBuilder and BundleCompiler.

Key points:

• BundleId — uniquely identifies this specific build of the bundle.
• UpgradeCode — ties all versions together. Never change it after shipping.
• Chain — defines the ordered list of packages to install.
• Vital(true) — if this package fails, the entire bundle fails.

The demo also shows .RelatedBundle() and .DependencyProvider() for upgrade detection and dependency tracking. We cover those in section 9.

[PE stub] [Magic: "FALKBUNDLE"] [Manifest] [Compressed payloads] [TOC] [Footer]

2. Multi-Product Suite

Open demo/06-product-suite/suite-bundle/Program.cs. This bundle installs two MSI products — an application and a background service — with rollback boundaries between them.

Chaining multiple MSIs

.Chain(chain => chain
    .RollbackBoundary("Prerequisites")
    .MsiPackage(appMsiPath, p => p
        .Id("AcmeApp")
        .DisplayName("Acme Application")
        .Vital(true))
    .RollbackBoundary("Services")
    .MsiPackage(serviceMsiPath, p => p
        .Id("AcmeService")
        .DisplayName("Acme Background Service")
        .Vital(true)))

Order matters. The engine installs packages top-to-bottom and uninstalls bottom-to-top. Place prerequisites before the packages that need them.

The UseBuiltInUI call accepts an optional license file and theme color:

.UseBuiltInUI(licenseFile, themeColor: "#2563EB")

3. Package Types

Bundles support four package types beyond MSI. Each has a dedicated builder method on the chain.

EXE packages (demo 36)

.ExePackage("vcredist_x64.exe", p => p
    .Id("VCRedist")
    .DisplayName("Visual C++ Redistributable")
    .Vital(true)
    .ExitCode(0, ExitCodeBehavior.Success)
    .ExitCode(3010, ExitCodeBehavior.ScheduleReboot)
    .ExitCode(1638, ExitCodeBehavior.Success))

Unlike MSI packages, EXE packages have no standard exit codes. You map each code to a behavior: Success, Failure, ScheduleReboot, or RebootRequired.

MSU packages (demo 37)

.MsuPackage("windows-hotfix-kb123456.msu", p => p
    .Id("KB123456")
    .DisplayName("Windows Hotfix KB123456"))

MSU files are Windows Update packages. Use them to install required hotfixes before your application.

Nested bundles (demo 38)

.BundlePackage("ChildSetup.exe", p => p
    .Id("ChildBundle")
    .DisplayName("Child Application Bundle")
    .Vital(true))

A bundle can contain other bundles. The parent engine coordinates detection and installation with the child engine via the bundle protocol.

4. Variables & Conditions

Open demo/40-bundle-variables/Program.cs. Bundle variables store values that conditions can reference at install time.

Defining variables

.Variable("InstallOptionalTools", v => v
    .Numeric()
    .Default("0"))
.Variable("InstallPath", v => v
    .String()
    .Default(@"C:\Program Files\Demo")
    .Persisted())

Three variable types: String(), Numeric(), and Version(). Modifiers control behavior:

• Persisted — survives repair and modify sessions.
• Hidden — excluded from install logs.
• Secret — excluded from logs and persisted state. Implies Hidden.

Conditional package installation

.MsiPackage("OptionalTools.msi", p => p
    .Id("OptionalTools")
    .DisplayName("Optional Developer Tools")
    .Vital(false)
    .InstallCondition("InstallOptionalTools = 1"))

The InstallCondition is evaluated during the Plan phase. If it evaluates to false, the package is skipped. The custom UI can set variable values via SetProperty before planning begins.

5. Rollback Boundaries

Open demo/41-bundle-rollback/Program.cs. Rollback boundaries divide the chain into transaction groups.

.Chain(chain => chain
    .RollbackBoundary("Prerequisites")
    .MsiPackage("Runtime.msi", p => p
        .Id("Runtime")
        .DisplayName("Runtime Prerequisites")
        .Vital(true))
    .RollbackBoundary("Application")
    .MsiPackage("MyApp.msi", p => p
        .Id("MyApp")
        .DisplayName("My Application")
        .Vital(true)))

Each boundary starts a new transaction group. If MyApp.msi fails, only the packages after the "Application" boundary roll back. The runtime prerequisite stays installed.

6. Remote Payloads

Open demo/39-bundle-remote-payload/Program.cs. Instead of embedding a package in the EXE, you can download it at install time.

.MsiPackage("MyApp.msi", p => p
    .Id("MyApp")
    .DisplayName("My Application")
    .Vital(true)
    .RemotePayload(
        "https://releases.example.com/myapp/1.0.0/MyApp.msi",
        "e3b0c44298fc1c14...7852b855",  // SHA256 hash
        10485760))                       // Size in bytes

RemotePayload takes three arguments: the download URL, the expected SHA256 hash, and the file size. The engine downloads the file, verifies the hash, and caches it before installation.

7. Update Feeds

Open demo/42-bundle-update-feed/Program.cs. A single method call adds update checking.

.UpdateFeed("https://updates.example.com/myapp/feed.json")

The engine checks this URL during detection. If a newer version is available, the behavior depends on the UpdatePolicy:

• NotifyOnly — tells the UI an update exists. The user decides.
• DownloadAndPrompt — downloads the update, then asks the user to apply it.
• AutoUpdate — downloads and applies automatically.

Set the policy explicitly with UpdateFeed(url, UpdatePolicy.DownloadAndPrompt). The default is NotifyOnly.

8. Layout Mode

Open demo/43-bundle-layout/Program.cs. Containers group payloads for offline distribution.

.Chain(chain => chain
    .MsiPackage("Core.msi", p => p
        .Id("Core")
        .DisplayName("Core Components")
        .Vital(true)
        .Container("CoreContainer"))
    .MsiPackage("Extras.msi", p => p
        .Id("Extras")
        .DisplayName("Extra Components")
        .Vital(false)
        .Container("ExtrasContainer")))
.Container("CoreContainer")
.Container("ExtrasContainer")

Each Container becomes a separate compressed archive inside the bundle. When the bundle runs in layout mode (/layout <directory>), it extracts all containers to a folder. This folder can then be copied to an air-gapped machine and installed offline.

9. Advanced Bundles

Open demo/10-advanced-bundle/bundle/Program.cs. This demo combines every bundle feature into a single deployment suite.

Related bundles

.RelatedBundle(new Guid("C3D4E5F6-..."), rb => rb
    .Relation(RelatedBundleRelation.Upgrade))
.RelatedBundle(new Guid("D4E5F6A7-..."), rb => rb
    .Relation(RelatedBundleRelation.Detect))

Related bundles declare relationships with other installed bundles. The engine detects them during the Detect phase and factors them into the plan.

Typed references

var prereqs = bundleBuilder.DefineContainer("Prerequisites", c => c
    .DownloadUrl("https://cdn.northwind.example.com/prereqs/"));
var prereqBoundary = bundleBuilder.DefineRollbackBoundary("PrereqBoundary");

DefineContainer and DefineRollbackBoundary return typed references (ContainerRef, RollbackBoundaryRef). Pass them to .Container() and .RollbackBoundary() in the chain. The compiler validates that every reference is used.

Mixed package types

The advanced bundle chains an EXE prerequisite, an MSU hotfix, an MSI application, and an MSP patch — all with install conditions, exit code mappings, and container assignments. This pattern is typical for enterprise deployment suites.

10. Extracting Bundles

Sometimes you need to inspect or extract the packages inside a bundle without running the installer. FalkForge supports this from both the CLI and the bundle itself.

CLI extraction

# List packages in a bundle
forge extract suite.exe --list

# Extract all packages to a directory
forge extract suite.exe -o D:\Temp\output

# Extract a specific package by ID
forge extract suite.exe -o D:\Temp\output --package ServerMsi

The forge extract command also works on standalone MSI files:

forge extract myapp.msi -o D:\Temp\extracted

Bundle self-extraction

FalkForge bundles can extract themselves without the forge CLI tool. Pass --extract or --extract-list directly to the bundle EXE:

myapp.exe --extract-list
myapp.exe --extract D:\Temp\output
myapp.exe --extract D:\Temp\output --package ServerMsi

Self-extraction bypasses the installer UI entirely — no elevation, no detection, just extraction. This is useful for IT teams inspecting packages before deployment or for automated build verification pipelines.

11. Delta Updates

When your users update from v1 to v2, they don't need to re-download the entire bundle. FalkForge can generate a delta bundle that contains only the binary differences between versions. A 50 MB bundle update might shrink to 2 MB.

Generating a delta bundle

Build v2 with a reference to the v1 bundle. Use DeltaBundleCompiler instead of BundleCompiler:

var v2Bundle = new BundleBuilder()
    .Name("MyApp")
    .Version("2.0.0")
    .DeltaFrom(v1Path)
    .Chain(chain => chain
        .MsiPackage("MyApp.msi", p => p
            .Id("MyApp")
            .DisplayName("My Application")
            .Vital(true)))
    .Build();

var result = new DeltaBundleCompiler().Compile(v2Bundle, outputPath, v1Path);

FalkForge extracts the v1 payloads, computes binary diffs using Octodiff, and embeds only the changed bytes. If a payload is new or the delta is larger than the full file, the full payload is included instead.

Update feed with delta URL

Add the delta bundle URL to your JSON update feed alongside the full bundle:

{
  "version": "2.0.0",
  "url": "https://releases.example.com/myapp-2.0.0.exe",
  "deltaUrl": "https://releases.example.com/myapp-2.0.0-delta.exe",
  "deltaSha256": "A1B2C3...",
  "deltaSize": 2048000
}

The engine downloads the delta first. If anything fails — corrupted delta, missing cached payload, hash mismatch — it falls back to the full bundle URL automatically.

Recap