Advanced MSI

Beyond files and features, MSI supports custom actions, custom tables, install sequence control, merge modules, patches, and transforms. This tutorial covers the advanced authoring features.

Custom Actions

Custom actions let you run code during installation. FalkForge supports several types: DLL entry points, embedded EXEs, and property-setting actions. Each type serves a different purpose.

SetProperty actions

The simplest custom action sets a property value. Use it to pass data between installation phases or configure behavior based on conditions.

package.CustomAction("SetInstallMode", ca =>
{
    ca.SetProperty("INSTALL_MODE", "standard");
    ca.Condition = Condition.IsInstalling.ToString();
});

The Condition property controls when the action runs. Here it fires only during a fresh install, not during repair or uninstall.

DLL custom actions

For complex logic, embed a native DLL and call a C entry point. First, register the binary. Then reference it in the custom action.

// Embed the DLL as a binary resource
package.Binary("CustomActionsDll", "payload/CustomActions.dll");

// Call a C entry point from the embedded DLL
package.CustomAction("CheckSystemRequirements", ca =>
{
    ca.DllFromBinary("CustomActionsDll", "CheckRequirements");
    ca.After = "CostFinalize";
    ca.Condition = Condition.IsInstalling.ToString();
});

The first argument to DllFromBinary is the binary name. The second is the exported function name in the DLL.

EXE custom actions

You can also run an embedded executable. Pass command-line arguments via the Target property.

package.CustomAction("RunSetupTool", ca =>
{
    ca.ExeFromBinary("CustomActionsDll");
    ca.Target = "--setup --silent";
    ca.Deferred();
    ca.NoImpersonate();
    ca.After = "InstallFiles";
});

Deferred, rollback, and commit actions

Actions that modify the system must be deferred. Pair them with a rollback action to undo changes on failure. A commit action runs only after successful completion.

// Deferred action — runs during the execution phase
package.CustomAction("ConfigureApp", ca =>
{
    ca.SetProperty("CONFIGURE_CMD", "[ProgramFilesFolder]Demo\\app.exe --configure");
    ca.Deferred();
    ca.NoImpersonate();
    ca.After = "InstallFiles";
});

// Rollback action — undoes ConfigureApp on failure
package.CustomAction("UndoConfigureApp", ca =>
{
    ca.SetProperty("UNDO_CMD", "[ProgramFilesFolder]Demo\\app.exe --unconfigure");
    ca.Rollback();
    ca.NoImpersonate();
    ca.Before = "ConfigureApp";
});

// Commit action — runs only on success
package.CustomAction("NotifySuccess", ca =>
{
    ca.SetProperty("NOTIFY_CMD", "[ProgramFilesFolder]Demo\\app.exe --notify-complete");
    ca.Commit();
    ca.NoImpersonate();
    ca.After = "ConfigureApp";
});

Schedule the rollback action before the deferred action it protects. Windows Installer records rollback actions in reverse order so they run correctly during a rollback.

ContinueOnError

For non-critical actions like telemetry, call ContinueOnError(). The installer proceeds even if the action fails.

package.CustomAction("OptionalTelemetry", ca =>
{
    ca.SetProperty("TELEMETRY_CMD", "...");
    ca.Deferred();
    ca.ContinueOnError();
});

Custom Tables

Custom tables store structured data inside the MSI database. Custom actions can read them at install time. They are also useful for embedding metadata that external tools query after deployment.

Defining a schema

Define columns with types and constraints. Mark at least one column as the primary key.

package.CustomTable(ct => ct
    .Name("AppConfig")
    .Column("Key", CustomTableColumnType.String, col => col.PrimaryKey().Width(72))
    .Column("Value", CustomTableColumnType.String, col => col.Width(255))
    .Column("Priority", CustomTableColumnType.Int32)

Supported column types: String, Int16, Int32. Use Nullable() for optional columns and Width() to set the maximum string length.

Adding rows

Chain Row() calls to populate the table with data.

    .Row(row => row
        .Set("Key", "Theme")
        .Set("Value", "Dark")
        .Set("Priority", 1))
    .Row(row => row
        .Set("Key", "Language")
        .Set("Value", "en-US")
        .Set("Priority", 2))
);

When to use custom tables

Use custom tables when you need to:

• Store configuration data that custom actions read at install time.
• Embed deployment metadata (environment names, health-check endpoints, feature flags).
• Drive install-time logic from data rather than hard-coded conditions.

forge inspect output.msi

Sequence Scheduling

MSI runs actions in a defined order called a sequence. FalkForge lets you position custom actions relative to built-in actions using Before() and After().

ExecuteSequence

The execute sequence runs during the actual installation — file copies, registry writes, service operations. Schedule custom actions here when they modify the system.

package.ExecuteSequence(seq => seq
    .Action("SetInstallMode")
        .After("CostFinalize")
        .Condition("NOT Installed")
    .Action("RollbackDatabase")
        .Before("ConfigureDatabase")
        .Condition("NOT Installed")
    .Action("ConfigureDatabase")
        .After("InstallFiles")
        .Condition("NOT Installed")
);

Each Action() call references a previously defined custom action by name. The Condition() call is optional and controls whether the action runs for a given install scenario.

UISequence

The UI sequence runs during the user interaction phase — dialogs, property collection, validation. Use it for actions that gather or display information without modifying the system.

package.UISequence(seq => seq
    .Action("PostInstallCleanup")
    .After("ExecuteAction")
    .Condition(Condition.IsInstalling)
);

Sequence tables

MSI defines four sequence tables:

• InstallExecuteSequence — the main installation sequence. File copies, registry, services.
• InstallUISequence — the UI phase. Dialogs and property validation.
• AdminExecuteSequence — administrative installations (network image creation).
• AdvtExecuteSequence — advertised installations (shortcuts and file associations without files).

FalkForge exposes ExecuteSequence() and UISequence() for the two most common tables. The admin and advertise sequences are rarely needed.

Merge Modules

A merge module (.msm) packages reusable components that multiple MSI installers can consume. It is the MSI equivalent of a shared library.

Creating a merge module

Use Installer.BuildMergeModule() as the entry point. The API mirrors Installer.Build() but targets the MSM format.

return Installer.BuildMergeModule(args, module =>
{
    module.Version(new Version(1, 0, 0));
    module.Manufacturer("Demo");
    module.Language(1033);
    module.Description("Shared components merge module");

    // A merge module must include at least one component
    module.Component("SharedRuntime");

    module.Dependency("SharedRuntime_1.0");
}, (model, outputPath) => new MsmCompiler().Compile(model, outputPath));

The second argument is a compile delegate. MsmCompiler generates the .msm file. The Dependency() call declares a module dependency identifier that consuming MSIs can verify.

Patches

A patch (.msp) updates an installed MSI without requiring a full reinstall. It contains only the differences between two MSI versions.

Creating a patch

Use Installer.BuildPatch(). Provide the baseline MSI (what the user has installed) and the target MSI (the updated version).

return Installer.BuildPatch(args, patch =>
{
    patch.Manufacturer("Demo");
    patch.Description("Updates App from 1.0 to 1.1");
    patch.TargetMsi("payload/app-v1.msi");
    patch.UpdatedMsi("payload/app-v2.msi");
    patch.Classification(PatchClassification.Hotfix);
    patch.AllowRemoval();
}, (model, outputPath) => new PatchCompiler().Compile(model, outputPath));

TargetMsi() specifies the baseline. UpdatedMsi() specifies the new version. The compiler diffs the two and produces the patch. AllowRemoval() lets users uninstall the patch to revert to the baseline.

Transforms

A transform (.mst) modifies an MSI's properties and behavior without changing the MSI file itself. IT departments use transforms to customize vendor MSIs for their environment.

Creating a transform

Use Installer.BuildTransform(). Reference the base MSI and override properties as needed.

return Installer.BuildTransform(args, transform =>
{
    transform.BaseMsi("payload/base.msi");
    transform.Description("Enterprise Customization");

    // Override properties for enterprise deployment
    transform.SetProperty("ALLUSERS", "1");
    transform.SetProperty("INSTALLDIR", @"D:\Apps\MyApp");
    transform.SetProperty("REBOOT", "ReallySuppress");
}, (model, outputPath) => new TransformCompiler().Compile(model, outputPath));

BaseMsi() identifies the MSI to customize. SetProperty() overrides property values. Common overrides include install directory, per-user vs per-machine scope, and reboot suppression.

Applying transforms

Apply a transform during installation via the command line:

msiexec /i product.msi TRANSFORMS=enterprise.mst

Or via Group Policy by attaching the MST to the MSI deployment. The transform modifies the MSI's behavior without altering the original file.

Recap