8. MSI Builder API

FalkForge uses a fluent builder API to define MSI installer packages. The entry point is Installer.Build(), which configures a PackageBuilder, validates the resulting model, and optionally compiles it to an MSI file. Additional entry points exist for merge modules, patches, and transforms.

8.1 Entry Points

The static Installer class (src/FalkForge.Core/Installer.cs) provides four entry points for building different output types:

All entry points support -o / --output command-line arguments to specify the output path.

// Minimal MSI package
return Installer.Build(args, p =>
{
    p.Name = "My Application";
    p.Manufacturer = "Contoso Ltd";
    p.Version = new Version(1, 0, 0);

    p.Files(f => f
        .Add("bin/MyApp.exe")
        .Add("bin/MyApp.dll")
        .To(KnownFolder.ProgramFiles / "Contoso" / "MyApp"));
}, new MsiCompiler());

8.2 PackageBuilder

The central orchestrator for MSI package definition. All sub-builders are accessed through its fluent methods. Located at src/FalkForge.Core/Builders/PackageBuilder.cs.

Properties

Fluent Methods

MsiDialogSet Enum

None and Minimal have no license page. Setting LicenseFile with one of those two active does not fail the build — the license is simply not shown — but it logs a DLG004 warning (via the optional IFalkLogger passed to MsiAuthoring.Compile) so the mismatch is not silent. Use InstallDir, FeatureTree, Mondo, or Advanced to actually render the license.

// Full-featured MSI package
return Installer.Build(args, p =>
{
    p.Name = "Enterprise Suite";
    p.Manufacturer = "Contoso Ltd";
    p.Version = new Version(2, 1, 0);
    p.Architecture = ProcessorArchitecture.X64;
    p.Scope = InstallScope.PerMachine;
    p.Description = "Enterprise productivity suite";
    p.LicenseFile = "assets/license.rtf";
    p.DefaultInstallDirectory = KnownFolder.ProgramFiles / "Contoso" / "Suite";

    p.UseDialogSet(MsiDialogSet.FeatureTree);

    p.MajorUpgrade(mu => mu
        .Schedule(RemoveExistingProductsSchedule.AfterInstallValidate));

    p.Downgrade(d => d.Block("A newer version is already installed."));

    p.Require(Condition.IsWindows10OrLater, "Windows 10 or later is required.");

    p.Feature("Core", f =>
    {
        f.Title = "Core Components";
        f.IsRequired = true;
        f.Files(fs => fs.Add("bin/app.exe").To(KnownFolder.ProgramFiles / "Contoso" / "Suite"));
    });

    p.Feature("Plugins", f =>
    {
        f.Title = "Optional Plugins";
        f.Description = "Additional plugin modules";
        f.Files(fs => fs.FromDirectory("plugins/").To(KnownFolder.ProgramFiles / "Contoso" / "Suite" / "Plugins"));
    });

    p.Shortcut("Enterprise Suite", "bin/app.exe")
        .WithIcon("assets/app.ico")
        .WithDescription("Launch Enterprise Suite")
        .OnDesktop()
        .OnStartMenu("Contoso");

    p.Registry(r => r.Key(RegistryRoot.LocalMachine, @"SOFTWARE\Contoso\Suite", k =>
    {
        k.Value("InstallDir", MsiProperty.InstallFolder);
        k.Value("Version", "2.1.0");
        k.DWord("Installed", 1);
    }));

    p.EnvironmentVariable("CONTOSO_HOME", MsiProperty.InstallFolder);

    p.Signing(s => s
        .Thumbprint("A1B2C3D4E5F6...")
        .Timestamp("http://timestamp.digicert.com")
        .Algorithm("sha256"));
}, new MsiCompiler());

8.3 FeatureBuilder

Defines a node in the MSI feature tree. Created via PackageBuilder.Feature() or FeatureBuilder.Feature() for nested sub-features. Located at src/FalkForge.Core/Builders/FeatureBuilder.cs.

Properties

Methods

p.Feature("Server", f =>
{
    f.Title = "Server Components";
    f.IsRequired = true;
    f.Files(fs => fs
        .Add("bin/server.exe")
        .Add("bin/server.dll")
        .To(KnownFolder.ProgramFiles / "Contoso" / "Server"));

    f.Feature("Docs", sub =>
    {
        sub.Title = "Documentation";
        sub.Description = "API reference and user guide";
        sub.IsDefault = false;
        sub.Files(fs => fs.FromDirectory("docs/").To(KnownFolder.ProgramFiles / "Contoso" / "Server" / "Docs"));
    });

    f.Condition(Condition.Is64BitOS, 1);  // Only enabled on 64-bit systems
});

8.4 FileSetBuilder

Defines a set of files to install to a target directory. Created via PackageBuilder.Files() or FeatureBuilder.Files(). Located at src/FalkForge.Core/Builders/FileSetBuilder.cs.

KnownFolder Reference

p.Files(f => f
    .Add("bin/MyApp.exe")
    .Add("bin/MyApp.dll")
    .Add("bin/config.json")
    .To(KnownFolder.ProgramFiles / "Contoso" / "MyApp")
    .ComponentCondition("NOT REMOVE"));

Preserving Files Across Upgrades

Use NeverOverwrite() and Permanent() to protect configuration files and user data during upgrades and uninstalls:

// Config file: keep user edits on upgrade, leave on uninstall
p.Files(f => f
    .Add("defaults/appsettings.json")
    .To(KnownFolder.CommonAppData / "Contoso" / "MyApp")
    .NeverOverwrite()
    .Permanent());

8.5 ShortcutBuilder

Creates shortcuts to installed files on the desktop, Start Menu, or Startup folder. Created via PackageBuilder.Shortcut(). Located at src/FalkForge.Core/Builders/ShortcutBuilder.cs.

p.Shortcut("My Application", "bin/MyApp.exe")
    .WithIcon("assets/app.ico")
    .WithDescription("Launch My Application")
    .WithArguments("--startup")
    .OnDesktop()
    .OnStartMenu("My Company");

8.6 ServiceBuilder

Defines a Windows service to install. Created via PackageBuilder.Service(). Located at src/FalkForge.Core/Builders/ServiceBuilder.cs.

Properties

Methods

p.Service("MyWorkerService", svc =>
{
    svc.DisplayName = "My Worker Service";
    svc.Description = "Background processing service";
    svc.Executable = "bin/WorkerService.exe";
    svc.StartMode = ServiceStartMode.DelayedAutomatic;
    svc.Account = ServiceAccount.NetworkService;
    svc.Arguments = "DSN=[ODBCNAME] --mode production";

    svc.DependsOn("Tcpip");
    svc.DependsOnGroup("NetworkProvider");

    svc.FailureActions(fa =>
    {
        fa.OnFirstFailure = FailureAction.Restart;
        fa.OnSecondFailure = FailureAction.Restart;
        fa.OnSubsequentFailures = FailureAction.RunCommand;
        fa.ResetPeriod = TimeSpan.FromDays(1);
        fa.RestartDelay = TimeSpan.FromMinutes(2);
        fa.Command = @"C:\Tools\notify.exe --service-failed";
    });
});

Advanced Service Configuration

The following example shows dynamic account selection via MSI properties, conditional installation, and service permissions:

p.Service("DataSync", svc =>
{
    svc.DisplayName = "Data Sync Agent";
    svc.Executable = "bin/DataSync.exe";
    svc.StartMode = ServiceStartMode.Automatic;

    // Account resolved at install time from an MSI property
    svc.AccountProperty("[SERVICEACCOUNT]");

    // Only install if the user chose "service mode"
    svc.Condition("ASSERVICE ~= \"true\"");

    // Grant specific permissions on the service object
    svc.Permission(perm =>
    {
        perm.User = "NT AUTHORITY\\Authenticated Users";
        perm.GenericRead = true;
    });
});

8.7 ServiceControlBuilder

Controls service lifecycle during install and uninstall. Created via PackageBuilder.ServiceControl(). Located at src/FalkForge.Core/Builders/ServiceControlBuilder.cs.

p.ServiceControl(sc => sc
    .Id("StopMyService")
    .ServiceName("MyWorkerService")
    .StopOnInstall()
    .StopOnUninstall()
    .DeleteOnUninstall()
    .Wait(true));

p.ServiceControl(sc => sc
    .Id("StartMyService")
    .ServiceName("MyWorkerService")
    .StartOnInstall()
    .Arguments("--mode production"));

8.8 ServiceFailureActionsBuilder

Configures recovery actions when a service crashes. Used within ServiceBuilder.FailureActions(). Located at src/FalkForge.Core/Builders/ServiceFailureActionsBuilder.cs.

8.9 RegistryBuilder & RegistryKeyBuilder

Writes registry values during installation. RegistryBuilder organizes entries by key; RegistryKeyBuilder adds values within a key. Located at src/FalkForge.Core/Builders/RegistryBuilder.cs and src/FalkForge.Core/Builders/RegistryKeyBuilder.cs.

RegistryBuilder

RegistryKeyBuilder

RegistryRoot Enum

p.Registry(r =>
{
    r.Key(RegistryRoot.LocalMachine, @"SOFTWARE\Contoso\MyApp", k =>
    {
        k.Value("InstallPath", MsiProperty.InstallFolder);
        k.Value("Version", "2.0.0");
        k.DWord("LaunchCount", 0);
        k.Value("Config", @"%CONTOSO_HOME%\config.xml", RegistryValueType.ExpandString);
        k.DefaultValue("My Application");
    });

    r.Key(RegistryRoot.CurrentUser, @"SOFTWARE\Contoso\MyApp\Preferences", k =>
    {
        k.Value("Theme", "dark");
        k.DWord("AutoUpdate", 1);
    });
});

8.10 RemoveRegistryBuilder

Removes registry keys or individual values during installation. Located at src/FalkForge.Core/Builders/RemoveRegistryBuilder.cs.

p.RemoveRegistry(rr => rr
    .Id("RemoveLegacyKey")
    .Root(RegistryRoot.LocalMachine)
    .Key(@"SOFTWARE\Contoso\OldApp")
    .RemoveKey());

p.RemoveRegistry(rr => rr
    .Id("RemoveObsoleteValue")
    .Root(RegistryRoot.CurrentUser)
    .Key(@"SOFTWARE\Contoso\MyApp")
    .Name("DeprecatedSetting")
    .RemoveValue());

8.11 CustomActionBuilder

Defines custom actions that execute during installation. Supports DLL, EXE, and property-setting actions with execution flags for deferred, rollback, and commit scheduling. Located at src/FalkForge.Core/Builders/CustomActionBuilder.cs.

Properties

Source Type Methods

Execution Flag Methods

Simplified Overload

The PackageBuilder.CustomAction(string binaryPath, string entryPoint, Action<CustomActionBuilder>?) overload auto-registers the binary from the file system and creates a DllFromBinary action, eliminating the need to call Binary() separately:

// Explicit approach: register binary + define action
p.Binary("MyCustomDll", "lib/CustomActions.dll");
p.CustomAction("RunSetup", ca =>
{
    ca.DllFromBinary("MyCustomDll", "InitializeDatabase");
    ca.After = "InstallFiles";
    ca.Deferred();
    ca.NoImpersonate();
});

// Simplified approach: auto-registers binary
p.CustomAction("lib/CustomActions.dll", "InitializeDatabase", ca =>
{
    ca.After = "InstallFiles";
    ca.Deferred();
    ca.NoImpersonate();
});

// Set-property custom action
p.CustomAction("SetInstallMode", ca =>
{
    ca.SetProperty("INSTALL_MODE", "advanced");
    ca.Condition = "ADVANCED_MODE";
});

8.12 CustomTableBuilder

Defines custom MSI database tables with schema and data rows. Used for storing application-specific configuration that custom actions can query at install time. Located at src/FalkForge.Core/Builders/CustomTableBuilder.cs.

CustomTableBuilder

ColumnOptions

RowBuilder

CustomTableColumnType Enum

p.CustomTable(ct =>
{
    ct.Name("DatabaseConfig");
    ct.Column("Id", CustomTableColumnType.String, o => o.PrimaryKey().Width(72));
    ct.Column("Server", CustomTableColumnType.String, o => o.Width(255));
    ct.Column("Port", CustomTableColumnType.Int32, o => o.Nullable());
    ct.Column("Description", CustomTableColumnType.String, o => o
        .Nullable()
        .LocalizedDescription("Database connection description"));

    ct.Row(r => r
        .Set("Id", "Primary")
        .Set("Server", "db-prod.contoso.com")
        .Set("Port", 1433)
        .Set("Description", "Production database"));

    ct.Row(r => r
        .Set("Id", "Backup")
        .Set("Server", "db-backup.contoso.com")
        .Set("Port", 1433)
        .Set("Description", "Failover database"));
});

8.13 SequenceBuilder

Inserts custom actions or standard actions into MSI sequence tables. Used via PackageBuilder.ExecuteSequence() (InstallExecuteSequence) or PackageBuilder.UISequence() (InstallUISequence). Located at src/FalkForge.Core/Builders/SequenceBuilder.cs.

p.ExecuteSequence(seq => seq
    .Action("InitializeDatabase")
        .After("InstallFiles")
        .Condition("NOT Installed")
    .Action("CleanupTempFiles")
        .Before("InstallFinalize"));

p.UISequence(seq => seq
    .Action("ValidateLicense")
        .At(1200)
        .Condition("NOT Installed"));

8.14 MajorUpgradeBuilder

Configures standard major upgrade behavior for replacing previous product versions. Located at src/FalkForge.Core/Builders/MajorUpgradeBuilder.cs.

RemoveExistingProductsSchedule Enum

Downgrade blocking is configured separately via PackageBuilder.Downgrade(), not through MajorUpgradeBuilder. Located at src/FalkForge.Core/Builders/DowngradeBuilder.cs.

DowngradeBuilder

p.MajorUpgrade(mu => mu
    .Schedule(RemoveExistingProductsSchedule.AfterInstallValidate)
    .AllowSameVersionUpgrades()
    .MigrateFeatures(true));

p.Downgrade(d => d.Block("A newer version of [ProductName] is already installed."));

8.15 UpgradeBuilder

Configures legacy upgrade detection with version ranges. Used for fine-grained control over which previous versions to detect. For standard major upgrades, prefer MajorUpgradeBuilder. Located at src/FalkForge.Core/Builders/UpgradeBuilder.cs.

8.16 EnvironmentVariableBuilder

Configures environment variable operations during installation. Located at src/FalkForge.Core/Builders/EnvironmentVariableBuilder.cs.

// Set a new environment variable
p.EnvironmentVariable("APP_HOME", MsiProperty.InstallFolder);

// Append to PATH
p.EnvironmentVariable("PATH", MsiProperty.InstallFolder / "bin", ev =>
{
    ev.Action = EnvironmentVariableAction.Append;
    ev.Separator = ";";
});

8.17 PropertyBuilder

Defines MSI properties with optional security and visibility flags. Located at src/FalkForge.Core/Builders/PropertyBuilder.cs.

p.Property("INSTALL_MODE", "standard");

p.Property("DB_CONNECTION", "Server=localhost", prop =>
{
    prop.IsSecure = true;   // must be ALL-UPPERCASE, or PRP001 fails the build
    prop.IsHidden = true;   // Redact from install logs
});

8.18 PermissionBuilder

Sets NTFS or registry permissions on installed objects. Located at src/FalkForge.Core/Builders/PermissionBuilder.cs.

p.Permission("INSTALLFOLDER", perm =>
{
    perm.User = "Users";
    perm.Permission = 0x1F01FF;  // Full control
    perm.ForTable("CreateFolder");
});

8.19 MediaTemplateBuilder

Configures cabinet file generation and media layout. Located at src/FalkForge.Core/Builders/MediaTemplateBuilder.cs.

p.MediaTemplate(mt => mt
    .CabinetTemplate("data{0}.cab")
    .MaxCabinetSizeMB(100)
    .CompressionLevel(CompressionLevel.Medium)
    .EmbedCabinet(false));  // External cabinet files

8.20 SigningOptionsBuilder

Configures Authenticode code signing for the output MSI. Located at src/FalkForge.Core/Builders/SigningOptionsBuilder.cs.

Properties (Direct Access)

p.Signing(s => s
    .Thumbprint("A1B2C3D4E5F60011223344556677889900AABBCC")
    .Store("My")
    .Timestamp("http://timestamp.digicert.com")
    .Algorithm("sha256")
    .WithDescription("Contoso Enterprise Suite", "https://contoso.com"));

8.21 FileAssociationBuilder

Registers file type associations. Created via PackageBuilder.FileAssociation(). Located at src/FalkForge.Core/Builders/FileAssociationBuilder.cs.

Properties

Methods

VerbBuilder

p.FileAssociation(".cproj", fa =>
{
    fa.ProgId("Contoso.Project");
    fa.Description = "Contoso Project File";
    fa.IconFile = "assets/project.ico";
    fa.ContentType = "application/x-contoso-project";

    fa.Verb("open", @"""%1""", v => { v.Command = "&Open"; v.Sequence = 1; });
    fa.Verb("edit", @"""%1""", v => { v.Command = "&Edit"; v.Sequence = 2; });
});

8.22 FontBuilder

Registers a font for installation. Created via PackageBuilder.Font(). Located at src/FalkForge.Core/Builders/FontBuilder.cs.

p.Font("fonts/ContosoSans-Regular.ttf");
p.Font("fonts/ContosoSans-Bold.ttf", f => f.Title = "Contoso Sans Bold");

8.23 IniFileBuilder

Creates or modifies INI file entries. Located at src/FalkForge.Core/Builders/IniFileBuilder.cs.

IniFileAction Enum

p.IniFile("config.ini", ini =>
{
    ini.Section("Database");
    ini.Key("Server");
    ini.Value("localhost");
    ini.Action(IniFileAction.CreateEntry);
});

8.24 AssemblyBuilder

Registers assemblies in the Global Assembly Cache (GAC). Created via PackageBuilder.GacAssembly(). Located at src/FalkForge.Core/Builders/AssemblyBuilder.cs.

p.GacAssembly(a => a
    .FileRef("Contoso.Shared.dll")
    .Name("Contoso.Shared")
    .Version("2.0.0.0")
    .Culture("neutral")
    .PublicKeyToken("b77a5c561934e089")
    .Architecture("msil"));

8.25 File Operation Builders

MoveFileBuilder

Moves or copies files during installation. Located at src/FalkForge.Core/Builders/MoveFileBuilder.cs.

DuplicateFileBuilder

Duplicates an installed file to another location. Located at src/FalkForge.Core/Builders/DuplicateFileBuilder.cs.

RemoveFileBuilder

Schedules file removal on install or uninstall. Located at src/FalkForge.Core/Builders/RemoveFileBuilder.cs.

CreateFolderBuilder

Creates empty folders during installation. Located at src/FalkForge.Core/Builders/CreateFolderBuilder.cs.

// Move a config template into place
p.MoveFile(mf => mf
    .Id("MoveConfig")
    .SourceDirectory("INSTALLFOLDER")
    .SourceFileName("config.template")
    .DestDirectory("INSTALLFOLDER")
    .DestFileName("config.xml")
    .AsCopy());

// Duplicate a DLL to a second location
p.DuplicateFile(df => df
    .Id("DupSharedLib")
    .FileRef("shared.dll")
    .DestDirectory("CommonFilesFolder")
    .DestFileName("ContosoShared.dll"));

// Clean up log files on uninstall
p.RemoveFile(rf => rf
    .Id("RemoveLogs")
    .Directory("INSTALLFOLDER")
    .FileName("*.log")
    .OnUninstall());

// Create an empty data directory
p.CreateFolder(cf => cf
    .Id("DataFolder")
    .Directory("INSTALLFOLDER_DATA"));

8.26 Output Type Builders

In addition to standard MSI packages, FalkForge supports building merge modules (.msm), patches (.msp), and transforms (.mst) through dedicated builders. Each builder validates its model before returning it.

MergeModuleBuilder

Defines a merge module for shared components. Entry point: Installer.BuildMergeModule(). Located at src/FalkForge.Core/Builders/MergeModuleBuilder.cs. Validates via MergeModuleValidator (error codes MSM001-MSM004).

return Installer.BuildMergeModule(args, msm =>
{
    msm.Id(Guid.Parse("12345678-1234-1234-1234-123456789012"));
    msm.Manufacturer("Contoso Ltd");
    msm.Version(new Version(1, 0, 0));
    msm.Description("Shared data access components");
    msm.Component("DataAccessLayer");
    msm.Component("ConnectionPooling");
    msm.Dependency("ContosoBase.msm");
}, (model, output) => new MsmCompiler().Compile(model, output));

MsmCompiler emits one row per Dependency(...) call into the standard Windows Installer ModuleDependency table (ModuleID, ModuleLanguage, RequiredID, RequiredLanguage, RequiredVersion). Because Dependency(string dependencyId) only accepts a single opaque identifier, the compiler fills in RequiredID with that string verbatim, defaults RequiredLanguage to the declaring module's own Language (same-language dependency assumed), and leaves RequiredVersion unset (no minimum-version constraint). Depending on a module published in a different language, or pinning a minimum required version, needs a richer overload on MergeModuleBuilder -- not available today.

PatchBuilder

Defines a patch package that upgrades an existing MSI installation. Entry point: Installer.BuildPatch(). Located at src/FalkForge.Core/Builders/PatchBuilder.cs. Validates via PatchValidator (error codes MSP001-MSP004).

return Installer.BuildPatch(args, patch =>
{
    patch.Id(Guid.Parse("AABBCCDD-1122-3344-5566-778899001122"));
    patch.Classification(PatchClassification.SecurityUpdate);
    patch.Description("Security fix for CVE-2026-1234");
    patch.Manufacturer("Contoso Ltd");
    patch.TargetProduct(Guid.Parse("11111111-2222-3333-4444-555555555555"));
    patch.TargetVersion("1.0.0");
    patch.UpdatedVersion("1.0.1");
    patch.TargetMsi("releases/v1.0.0/MyApp.msi");
    patch.UpdatedMsi("releases/v1.0.1/MyApp.msi");
    patch.AllowRemoval();
}, (model, output) => new PatchCompiler().Compile(model, output));

TransformBuilder

Defines a transform that modifies properties in an existing MSI at install time. Entry point: Installer.BuildTransform(). Located at src/FalkForge.Core/Builders/TransformBuilder.cs. Validates via TransformValidator (error codes MST001-MST002).

return Installer.BuildTransform(args, mst =>
{
    mst.Id("EnterpriseDefaults");
    mst.BaseMsi("releases/v2.0.0/MyApp.msi");
    mst.TargetMsi("releases/v2.0.0/MyApp.msi");
    mst.Description("Enterprise deployment defaults");
    mst.SetProperty("INSTALLLEVEL", "200");
    mst.SetProperty("INSTALL_MODE", "enterprise");
    mst.SetProperty("AGREETOLICENSE", "Yes");
}, (model, output) => new TransformCompiler().Compile(model, output));

8.27 Complete Example

The following example demonstrates a comprehensive MSI package definition using most builder APIs:

return Installer.Build(args, p =>
{
    // Package metadata
    p.Name = "Contoso Server";
    p.Manufacturer = "Contoso Ltd";
    p.Version = new Version(3, 0, 0);
    p.Architecture = ProcessorArchitecture.X64;
    p.Scope = InstallScope.PerMachine;
    p.Description = "Contoso Server application suite";
    p.LicenseFile = "assets/license.rtf";
    p.HelpUrl = "https://support.contoso.com";

    // Upgrade behavior
    p.MajorUpgrade(mu => mu
        .Schedule(RemoveExistingProductsSchedule.AfterInstallValidate));

    p.Downgrade(d => d.Block("A newer version is already installed."));

    // Launch conditions
    p.Require(Condition.IsWindows10OrLater, "Windows 10 or later is required.");
    p.Require(Condition.Is64BitOS, "A 64-bit operating system is required.");
    p.Require(Condition.IsPrivileged, "Administrator privileges are required.");

    // UI
    p.UseDialogSet(MsiDialogSet.FeatureTree);

    // Features
    p.Feature("Server", f =>
    {
        f.Title = "Server Components";
        f.IsRequired = true;
        f.Files(fs => fs
            .Add("bin/server.exe")
            .Add("bin/server.dll")
            .To(KnownFolder.ProgramFiles / "Contoso" / "Server"));

        f.Feature("WebUI", sub =>
        {
            sub.Title = "Web Dashboard";
            sub.Description = "Browser-based management interface";
            sub.Files(fs => fs
                .FromDirectory("wwwroot/")
                .To(KnownFolder.ProgramFiles / "Contoso" / "Server" / "wwwroot"));
        });
    });

    p.Feature("Tools", f =>
    {
        f.Title = "Command-Line Tools";
        f.IsDefault = false;
        f.Files(fs => fs
            .Add("tools/cli.exe")
            .To(KnownFolder.ProgramFiles / "Contoso" / "Server" / "Tools"));
    });

    // Windows service
    p.Service("ContosoServer", svc =>
    {
        svc.DisplayName = "Contoso Server";
        svc.Description = "Contoso application server";
        svc.Executable = "bin/server.exe";
        svc.StartMode = ServiceStartMode.DelayedAutomatic;
        svc.Account = ServiceAccount.NetworkService;
        svc.DependsOn("Tcpip");
        svc.FailureActions(fa =>
        {
            fa.OnFirstFailure = FailureAction.Restart;
            fa.OnSecondFailure = FailureAction.Restart;
            fa.OnSubsequentFailures = FailureAction.None;
            fa.RestartDelay = TimeSpan.FromSeconds(30);
        });
    });

    p.ServiceControl(sc => sc
        .Id("StopContosoServer")
        .ServiceName("ContosoServer")
        .StopOnInstall()
        .StopOnUninstall()
        .DeleteOnUninstall());

    p.ServiceControl(sc => sc
        .Id("StartContosoServer")
        .ServiceName("ContosoServer")
        .StartOnInstall());

    // Shortcuts
    p.Shortcut("Contoso Server", "bin/server.exe")
        .WithIcon("assets/server.ico")
        .OnStartMenu("Contoso");

    // Registry
    p.Registry(r => r.Key(RegistryRoot.LocalMachine, @"SOFTWARE\Contoso\Server", k =>
    {
        k.Value("InstallPath", MsiProperty.InstallFolder);
        k.Value("Version", "3.0.0");
        k.DWord("Port", 8443);
    }));

    // Environment
    p.EnvironmentVariable("CONTOSO_HOME", MsiProperty.InstallFolder);
    p.EnvironmentVariable("PATH", MsiProperty.InstallFolder / "bin", ev =>
    {
        ev.Action = EnvironmentVariableAction.Append;
        ev.Separator = ";";
    });

    // Properties
    p.Property("SERVER_PORT", "8443", prop => prop.IsSecure = true);

    // Custom action
    p.CustomAction("lib/ServerSetup.dll", "ConfigureDatabase", ca =>
    {
        ca.After = "InstallFiles";
        ca.Condition = "NOT Installed";
        ca.Deferred();
        ca.NoImpersonate();
    });

    // Sequence
    p.ExecuteSequence(seq => seq
        .Action("ConfigureDatabase")
            .After("InstallFiles")
            .Condition("NOT Installed"));

    // Create data directory
    p.CreateFolder(cf => cf
        .Id("DataDir")
        .Directory("INSTALLFOLDER_DATA"));

    // Clean up on uninstall
    p.RemoveFile(rf => rf
        .Id("RemoveLogs")
        .Directory("INSTALLFOLDER")
        .FileName("*.log")
        .OnUninstall());

    // Signing
    p.Signing(s => s
        .Thumbprint("A1B2C3D4E5F6...")
        .Timestamp("http://timestamp.digicert.com")
        .WithDescription("Contoso Server", "https://contoso.com"));

    p.EnableRestartManagerSupport();
}, new MsiCompiler());

Because the sample above selects MsiDialogSet.FeatureTree, calling EnableRestartManagerSupport() also authors the MsiRMFilesInUse dialog into that dialog set (see §14). FalkForge appends this dialog to every stock dialog set (Minimal, InstallDir, FeatureTree, Mondo, Advanced) when the flag is set; it is inert for MsiDialogSet.None, since a silent install has no dialog set to append to.

8.28 WinGet Manifest Generation

PackageBuilder.WinGet() attaches a WinGet manifest configuration to the MSI build. When configured, the compiler emits a three-file WinGet singleton manifest (version YAML, installer YAML, locale YAML) alongside the .msi output. The SHA-256 of the installer payload is computed during emission so the manifest is publishable as-is.

var compiler = new MsiCompiler();
Installer.Build(p =>
{
    p.Name("Acme Web App").Manufacturer("Acme")
     .Version("1.2.3").UpgradeCode(Guid.Parse("..."));

    // ... product configuration ...

    p.WinGet(w => w
        .PackageIdentifier("Acme.WebApp")        // "Publisher.PackageName"
        .License("MIT")                          // SPDX license identifier
        .ShortDescription("Sample web app")
        .InstallerUrl("https://acme.example/app.msi")
        .Tags("web", "sample"));
}, compiler);
// Produces: AcmeWebApp.msi
//   + manifests/Acme.WebApp.yaml
//   + manifests/Acme.WebApp.installer.yaml
//   + manifests/Acme.WebApp.locale.en-US.yaml

The CLI command forge winget <file.msi> --id ... --license ... --desc ... (see Section 14) generates the same three-file set from an existing MSI that was not built with PackageBuilder.WinGet() — useful for retrofitting legacy installers.

8.29 PackageCode Semantics

PackageModel.PackageCode (Guid?) is the MSI SummaryInformation RevisionNumber (PID 9). The Windows Installer specification requires every non-identical package to carry a unique PackageCode so that the installer service can distinguish cached packages at repair time (SECREPAIR / KB2918614). ProductCode encodes product identity; PackageCode encodes the specific package bytes. Two MSI files with the same ProductCode but different content must have different PackageCode values, or Windows Installer may use a stale cached copy during repair instead of the updated package.

How the compiler assigns PackageCode

Source: src/FalkForge.Core/Models/PackageModel.cs, src/FalkForge.Core/Builders/PackageBuilder.cs, src/FalkForge.Compiler.Msi/Recipe/PackageCodeDerivation.cs.

Why Reproducible Builds Matter

The table above explains what Reproducible() does mechanically; this is why you'd turn it on. "Reproducible" has one precise meaning here: the same source, built twice, produces byte-identical output. package.Reproducible(epochOverride = null) pins every timestamp the compiler would otherwise take from the wall clock to a fixed SOURCE_DATE_EPOCH (an explicit argument, or the SOURCE_DATE_EPOCH environment variable — it throws rather than silently falling back to "now" if neither is set), and leaves PackageCode null so the compiler derives it from a content digest instead of a random GUID. Nothing about the installer's behavior changes; only whether two builds of the same inputs are byte-for-byte the same file.

That one property enables several things a non-reproducible build can't offer:

• Supply-chain trust. Anyone — not just the team that ran the original build — can rebuild your installer from the published source and byte-compare it against the artifact you shipped. forge verify <artifact> --rebuild <project> (CLI, 15) automates exactly that comparison and reports VERIFIED/MISMATCH/REBUILD-FAILED. Without reproducibility there is nothing to compare against — a legitimate rebuild and a compromised build machine produce equally "different" bytes from the original, so a mismatch would prove nothing.
• Auditability and attestations. package.Sbom() emits a CycloneDX SBOM listing every installed file's SHA-256; under a reproducible build its own serial number and timestamp are derived from build content rather than the wall clock, so the SBOM itself doesn't introduce non-determinism into an otherwise-reproducible artifact. The same logic applies one layer up to any release pipeline — including FalkForge's own (.github/workflows/release.yml) — that publishes SLSA-style build-provenance attestations: an attestation asserts "these bytes came from this source, this build"; reproducibility is what lets a third party independently confirm that assertion by rebuilding, instead of trusting it on faith.
• Debugging and support. Given a customer's shipped version number, you can rebuild the exact bytes they're running, months or years later, for forensics — without having archived the original build machine's output.
• Trustworthy version diffs. forge plan-diff old new reports what genuinely changed between two releases' install plans. If builds aren't reproducible, re-running a build of the same version can itself introduce noise (a fresh PackageCode, a different embedded timestamp) that has nothing to do with the version bump you actually care about reviewing.
• Smaller, meaningful deltas. BundleBuilder.DeltaFrom() computes a binary delta with Octodiff — a raw byte-level (rsync-style) diff between the old and new payload files. Non-deterministic bytes scattered through an otherwise little-changed file (a random PackageCode, a fresh save timestamp in the MSI's OLE compound structure) reduce how much of the old and new payloads actually match block-for-block, inflating the delta with noise unrelated to your real changes. A reproducible build removes that noise, so the delta reflects the content that actually changed.

None of this is free, which is why it's opt-in rather than the default. A normal build's fresh Guid.NewGuid() PackageCode on every compile exists for a reason of its own: Windows Installer's repair cache needs every packaging event to be unambiguously distinguishable, and a fresh GUID guarantees that without you having to think about it, even across many builds of an unchanged ProductCode. Reproducible mode's content-derived PackageCode preserves that same SECREPAIR safety property a different way — two non-identical packages still never collide, because the digest folds in per-file content hashes — but it requires you to actually pin SOURCE_DATE_EPOCH and accept that identical inputs now produce identical output rather than a fresh identity every time. Pick reproducible mode for a release build you intend to publish, sign, or attest to; a normal (non-reproducible) build remains the simpler default for local development, where a unique identity per compile is exactly what you want and there's nothing yet to verify against.

Combining Reproducible() with Integrity() (MSI)

ECDSA-P256 signing is intentionally nondeterministic (a fresh random nonce every call), so embedding an Integrity() signature in-band would defeat Reproducible()'s byte-identical guarantee the moment both are configured on the same PackageBuilder. When both are set, IntegritySigner skips the in-band _FalkForgeIntegrity table entirely and writes the signature sidecar-only instead (<msi>.sig.json, the same envelope shape as always) — the MSI artifact itself stays byte-identical across rebuilds. The compiler logs an explicit Info-level notice when this applies (not hidden behind --verbose, since it is a real, user-visible change of where the signature lives). A non-reproducible Integrity() build still gets both: the in-band table and the sidecar. forge verify <msi> (CLI, 15) checks the table first and falls back to the sidecar automatically, so verification works the same way either way.

See Sigil: Optional SBOM Attestation & MSI Integrity Signing (23) for what does and doesn't need Sigil in either mode.

See Demo 57 — reproducible-sbom for the full pin-build-twice-and-compare workflow with an SBOM sidecar, Demo 56 — verify-and-plan for forge plan/plan-diff/verify --rebuild together, the CLI reference (15) for full forge verify and forge plan-diff flags, and Bundle Signing, Trust & Key Rotation (23) for how payload signing and integrity attestation build on top of a reproducible artifact.

8.30 Referencing another project's build output (ProjectOutputs)

Hardcoding a path such as files.Add("../app/bin/Debug/net10.0-windows/DemoApp.dll") is fragile: it breaks across Debug/Release configurations, target-framework changes, CI machines with custom output paths, and silently goes stale instead of failing. The FalkForge SDK solves this by generating a typed ProjectOutputs class at build time so that paths are always resolved from MSBuild, not guessed.

Setup (3 steps)

Step 1 — Import Sdk.targets in both projects.

The FalkForge SDK is not NuGet-packaged; import it by relative path. Add the following to the .csproj of both the installer project and the referenced project. Import Sdk.targets only — not Sdk.props, which would default FalkOutputType to Msi and trigger an unwanted build step.

<Import Project="../../../src/FalkForge.Sdk/Sdk/Sdk.targets" />

Step 2 — Add a ProjectReference with ReferenceOutputAssembly="false".

In the installer project, reference the other project with ReferenceOutputAssembly="false". This requests the output path without creating a compile-time assembly reference.

<ProjectReference Include="../app/DemoApp.csproj"
                   ReferenceOutputAssembly="false" />

Step 3 — Set <FalkOutputType> in the referenced project.

The referenced project declares what kind of artifact it produces. The SDK uses this to resolve the correct output path:

The SDK generates obj/…/ProjectOutputs.g.cs at build time. For a referenced project named DemoApp with FalkOutputType=CustomAction the generated file looks like:

namespace FalkForge;
internal static class ProjectOutputs
{
    internal const string DemoApp = @"C:\repo\app\bin\Debug\net10.0-windows\DemoApp.dll";
}

Naming rule

The generated property name equals the referenced project's file name ($(MSBuildProjectName)) sanitized to a valid C# identifier: every character outside [A-Za-z0-9_] (including ., -, and spaces) becomes _, and a leading digit gets a _ prefix. Examples: DemoApp → DemoApp; My.Cool-App 2 → My_Cool_App_2.

Usage

// Single file
files.Add(ProjectOutputs.DemoApp);

// Whole output directory — packages everything the app builds
// (exe, dll, runtimeconfig.json, deps.json, pdb, etc.)
files.FromDirectory(Path.GetDirectoryName(ProjectOutputs.DemoApp)!)
     .To(KnownFolder.ProgramFiles / "Contoso" / "DemoApp");

// Bundle chain
chain.MsiPackage(ProjectOutputs.MyInstaller);

// Custom action referencing a managed DLL
package.CustomAction(ProjectOutputs.MyCaProject, nameof(MyEntryPoint));

9. Bundle Builder API

The Bundle Builder API compiles self-extracting EXE bundles that orchestrate the installation of multiple packages (MSI, EXE, MSU, MSP, nested bundles). Bundles are defined through a fluent API rooted at Installer.BuildBundle(), which delegates to BundleCompiler for output generation.

The compiled EXE follows the format: [PE stub][Magic: "FALKBUNDLE"][Manifest][Compressed payloads][TOC][Footer].

9.1 BundleBuilder

Top-level builder for defining an EXE bundle. Configures bundle metadata, UI mode, chain of packages, related bundles, containers, variables, features, dependency tracking, and update feed. Located in src/FalkForge.Compiler.Bundle/Builders/BundleBuilder.cs.

9.2 ChainBuilder

Configures the ordered chain of packages to install. Each package type has a dedicated method that accepts a source path and a configuration callback. Rollback boundaries can be inserted between packages to control rollback scope. Located in src/FalkForge.Compiler.Bundle/Builders/ChainBuilder.cs.

9.3 BundlePackageBuilder

Configures an individual package (MSI or EXE) within the bundle chain. Created internally by ChainBuilder.MsiPackage(), ChainBuilder.ExePackage(), and ChainBuilder.NetRuntime(). Located in src/FalkForge.Compiler.Bundle/Builders/BundlePackageBuilder.cs.

9.3a SearchConditionBuilder

Defines a search condition used for package detection. Created via BundlePackageBuilder.SearchCondition(). Located in src/FalkForge.Compiler.Bundle/Builders/SearchConditionBuilder.cs.

9.3b PackageGroupBuilder

Defines a reusable group of packages that are flattened into the chain at build time. Created via ChainBuilder.PackageGroup() or passed as a pre-built PackageGroupModel. Located in src/FalkForge.Compiler.Bundle/Builders/PackageGroupBuilder.cs.

ChainBuilder Integration

9.3c Built-in Prerequisites

Pre-configured package groups for common runtime prerequisites. Each group defines detection via registry search conditions and silent install arguments. The actual installer files are not embedded -- users must provide the source files or use RemotePayload. Located in src/FalkForge.Compiler.Bundle/Prerequisites/BuiltInPrerequisites.cs.

// Use built-in prerequisites in a bundle chain
Installer.BuildBundle(args, bundle =>
{
    bundle.Name("My Enterprise App")
          .Version("2.0.0")
          .Chain(chain =>
          {
              // Add .NET Framework and VC++ prerequisites
              chain.PackageGroup(BuiltInPrerequisites.NetFx472());
              chain.PackageGroup(BuiltInPrerequisites.VCRedist14x64());

              // Main application MSI with feature selection
              chain.MsiPackage("MyApp.msi", p => p
                  .Id("MyApp")
                  .DisplayName("My Enterprise App")
                  .EnableFeatureSelection(true));
          });
});

9.3d Variable Resolution in Install Arguments

EXE package install arguments support the [VariableName] syntax, which is resolved at runtime by the bundle engine. Variables are sourced from the VariableStore, which includes built-in variables and any user-defined variables set via the bundle UI or command line.

chain.ExePackage("setup.exe", p => p
    .Id("Setup")
    .Property("InstallArguments", "/TARGETDIR=[InstallFolder] /LOG=[BundleLog]"));

9.3e Runtime Dependency Enforcement

DependencyProvider(key, version, displayName) and DependencyConsumer(providerKey, consumerKey) (§9.1) are now ENFORCED at runtime, not just recorded. The engine's plan phase refuses the operation before any package is touched:

• Uninstall is refused while another installed product's consumer registration still references a provider key this bundle declares. The refusal names both the blocking provider key and the dependent key(s) so the operator can identify what to remove first.
• Install is refused when a required dependency provider is missing, or installed at a version outside the declared range.

Both checks read both HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER under SOFTWARE\Classes\Installer\Dependencies\ — a per-user consumer of a per-machine provider (or the reverse) is a real shape and would otherwise be missed. A PerUser-scoped bundle writes its own provider/consumer registrations directly to HKCU; a PerMachine-scoped bundle writes to HKLM through the elevated companion process. The layout is byte-identical to the MSI-authored one (FalkForge.Extensions.Dependency, §7.11 in the extensions table), so a bundle-level dependency and an MSI-table-authored one are visible to each other.

The uninstall check fails closed: if the registry cannot be read (access denied, corrupted key), the uninstall is refused rather than silently treated as "nothing depends on this" — an unknown state must never be assumed safe. The install check refuses on a genuinely missing/ unsatisfied provider; a registration write failure after a successful apply (e.g. the elevated companion round-trip failed) is logged as a warning and never fails an install or uninstall that otherwise completed.

--ignore-dependencies bypasses both checks — pass it on the command line (MyInstaller.exe --ignore-dependencies --uninstall) when a stale or unwanted registration is blocking an operation you are sure is safe. It is NOT implied by silent/unattended mode: an automated uninstall that would otherwise break a dependent product still gets refused unless this flag is explicitly passed, since silent automation is exactly where a silently broken dependent hurts most.

9.4 MsuPackageBuilder

Configures a Windows Update (MSU) package within the chain. Located in src/FalkForge.Compiler.Bundle/Builders/MsuPackageBuilder.cs.

9.5 MspPackageBuilder

Configures a patch (MSP) package within the chain. Located in src/FalkForge.Compiler.Bundle/Builders/MspPackageBuilder.cs.

9.6 NestedBundlePackageBuilder

Configures a nested bundle package within the chain. Located in src/FalkForge.Compiler.Bundle/Builders/NestedBundlePackageBuilder.cs.

9.7 ContainerBuilder

Configures a payload container for grouping packages. Containers enable separate download of package subsets from a remote URL. Located in src/FalkForge.Compiler.Bundle/Builders/ContainerBuilder.cs.

9.8 RelatedBundleBuilder

Declares a relationship to another bundle (upgrade, addon, detect, or patch). Located in src/FalkForge.Compiler.Bundle/Builders/RelatedBundleBuilder.cs.

The four RelatedBundleRelation values describe, at authoring time, how the bundle you're building relates to another bundle that might already be on the machine: Upgrade means this bundle supersedes the related one (a newer version of the same product); Addon means it extends the related bundle without replacing it (an optional module for a product that must already be present); Patch means it modifies the related bundle in place rather than standing alone; Detect means it should only be recognized as related for detection/reporting purposes, with no install-time action implied.

9.9 RollbackBoundaryBuilder

Configures a rollback boundary inserted into the package chain. If a package after a rollback boundary fails, only packages between this boundary and the next are rolled back. Located in src/FalkForge.Compiler.Bundle/Builders/RollbackBoundaryBuilder.cs.

Each RollbackBoundary(...) call is a marker in the chain's package sequence, not a package itself — it opens a new rollback scope that covers every package after it, up to the next boundary (or the end of the chain). If a package inside a scope fails, only the packages within that same scope roll back; packages that already completed successfully in an earlier scope are left installed. Place a boundary wherever you want a failure to stop propagating backward — typically between prerequisites and the application itself, so a failed application install doesn't tear out prerequisites another product might also depend on:

.Chain(chain => chain
    // Scope 1: if Runtime.msi fails, only Runtime.msi rolls back (nothing precedes it)
    .RollbackBoundary("Prerequisites")
    .MsiPackage("Runtime.msi", p => p
        .Id("Runtime")
        .DisplayName("Runtime Prerequisites")
        .Vital(true))
    // Scope 2: if MyApp.msi fails, only MyApp.msi rolls back -- Runtime.msi (scope 1)
    // stays installed, since it already completed successfully
    .RollbackBoundary("Application")
    .MsiPackage("MyApp.msi", p => p
        .Id("MyApp")
        .DisplayName("My Application")
        .Vital(true)))

See Demo 41 — bundle-rollback for the full runnable bundle.

9.10 BundleVariableBuilder

Declares a bundle variable that can be used in conditions, passed to packages, or persisted across sessions. Created via BundleBuilder.Variable(). Located in src/FalkForge.Compiler.Bundle/Builders/BundleVariableBuilder.cs.

9.11 BundleFeatureBuilder

Declares a feature that groups packages for optional selection by the user. Created via BundleBuilder.Feature(). Located in src/FalkForge.Compiler.Bundle/Builders/BundleFeatureBuilder.cs.

9.12 Typed Reference Handles

Sealed records that provide compile-time-safe cross-references between bundle elements. Prevents stringly-typed errors when referencing containers or rollback boundaries from other builders.

9.13 Entry Point and Compilation

Bundles are compiled using the Installer.BuildBundle() entry point, which accepts command-line arguments and a compilation function. The BundleCompiler validates the model, generates the manifest, reads and hashes payloads, creates the PE stub, and embeds everything into the final EXE.

// Entry point signature
public static int BuildBundle(string[] args, Func<string, Result<string>> compile);

// BundleCompiler
public sealed class BundleCompiler
{
    public Result<string> Compile(BundleModel model, string outputPath);
}

9.14 Code Example

Installer.BuildBundle(args, outputPath =>
{
    var bundle = new BundleBuilder()
        .Name("MyProductSuite")
        .Manufacturer("Contoso")
        .Version("2.0.0")
        .UpgradeCode(Guid.Parse("01234567-89AB-CDEF-0123-456789ABCDEF"))
        .UseBuiltInUI(licenseFile: "License.rtf", themeColor: "#0078D4")
        .UpdateFeed("https://updates.contoso.com/feed.json");

    // Define typed references for compile-time safety
    var mainContainer = bundle.DefineContainer("MainPayloads", c =>
        c.DownloadUrl("https://cdn.contoso.com/main.cab"));
    var boundary = bundle.DefineRollbackBoundary("AfterPrereqs");

    bundle
        .Variable("InstallDir", v => v.String().Default(@"C:\Program Files\Contoso").Persisted())
        .Feature("Core", f => f.Title("Core Components").Required().Package("CoreMsi"))
        .Feature("Tools", f => f.Title("Developer Tools").Package("ToolsMsi"))
        .DependencyProvider("Contoso.Suite", "2.0.0", "Contoso Product Suite")
        .Chain(chain => chain
            .MsiPackage("prereqs.msi", p => p
                .Id("PrereqMsi")
                .DisplayName("Prerequisites")
                .Vital(true))
            .RollbackBoundary(boundary)
            .MsiPackage("core.msi", p => p
                .Id("CoreMsi")
                .DisplayName("Core Application")
                .Container(mainContainer)
                .Property("INSTALLFOLDER", "[InstallDir]"))
            .MsiPackage("tools.msi", p => p
                .Id("ToolsMsi")
                .DisplayName("Developer Tools")
                .Container(mainContainer)
                .Vital(false))
            .MsuPackage("kb12345.msu", p => p
                .KbArticle("KB12345")
                .InstallCondition("VersionNT < v10.0.19041")));

    var model = bundle.Build();
    return new BundleCompiler().Compile(model, outputPath);
});

Delta Updates

BundleBuilder.DeltaFrom(oldBundlePath) switches the compiler into delta mode: instead of emitting a full self-extracting bundle, the compiler produces a smaller artifact that contains only the differences from the supplied previous bundle. Differences are computed with the Octodiff rsync-style algorithm over the compressed payloads. The TOC includes a flag byte plus BaseSha256Hash and ReconstructedSha256Hash per delta payload, so the engine can verify that the base bundle present on the target machine matches the one used at delta compile time.

Installer.BuildBundle(b =>
{
    b.Name("Acme Suite").Version("1.2.0")
     .BundleId(Guid.Parse("..."))
     .DeltaFrom("./previous/AcmeSuite-1.1.0.exe");   // enable delta mode

    b.Chain(c => c.MsiPackage("acme-core.msi"));
});
// Produces: AcmeSuite-1.2.0-delta.exe (much smaller than a full bundle)

Delta handling is split across download and install time. The engine's UpdateDownloader inspects the manifest update feed (UpdateFeedEntry.DeltaUrl + DeltaSha256), fetches and SHA-256-verifies the delta bundle first, then relaunches it — passing the currently-installed (base) bundle as --base-bundle. The relaunched bundle reconstructs each delta payload with DeltaApplicator against the matching payload in that base bundle: it checks the base payload's hash equals the delta's BaseSha256Hash, applies the Octodiff delta, and verifies the finished payload against ReconstructedSha256Hash before writing it — per payload, not per whole bundle. A failed delta download falls back to the full bundle URL. A delta that downloads but cannot be applied (wrong or missing base version, hash mismatch) fails loudly and instructs recovery via the full installer, rather than writing an unverifiable reconstruction. Older engines that don't understand delta flags simply skip the delta entry and download the full URL.

10. Extension System

FalkForge provides a pluggable extension system that allows contributing custom MSI tables, additional components, and validation rules. Extensions implement interfaces defined in FalkForge.Extensibility and are registered with the compiler through the IExtensionRegistry.

The shipped extensions below don't just author inert MSI table rows: Firewall, SQL, IIS (application pools and web sites), HTTP, Dependency, and Util schedule real deferred, elevated custom actions that create the firewall rule, database, site, URL reservation, or registry provider entry at install time. For IIS this now covers the full site graph: application pools, web sites with all their bindings, HTTPS/SSL certificate binding, sub-applications, and virtual directories are all created (and removed on uninstall, with rollback on a failed install) at install time via Microsoft.Web.Administration. An HTTPS binding's certificate is bound to a pre-provisioned certificate located in its authored store — FalkForge does not import the certificate, so it must already exist in the target store or the deferred bind fails loud (a pre-provisioning caveat surfaced via IIS013). A virtual directory targeting a parent application that is neither the site root (/) nor an authored sub-application is warned via IIS015 (its parent will not exist at install).

10.1 Extension Interfaces

Located in src/FalkForge.Extensibility/. These interfaces form the extension contract.

IFalkForgeExtension

Primary entry point for all extensions. Provides a name, optional version metadata, a registration callback, and a hook for contributing validation rules.

IExtensionRegistry

Registry interface provided to extensions during registration.

IComponentContributor

IMsiTableContributor

IExecutionContributor

The counterpart to IMsiTableContributor: where a table contributor puts data into the compiled MSI, an execution contributor makes that data live by scheduling the work that acts on it at install time. See 10.10 How Extensions Work for the full mechanics.

ValidationRule (data-as-rules)

Each rule is a first-class object that names itself with a stable RuleId, declares its Severity, carries a human description and a recommended fix, and exposes the actual diagnostic via an Inspect delegate (which the engine calls during ModelValidator.Inspect with the current package model and an emitter). Extensions contribute their rule set by overriding IFalkForgeExtension.GetValidationRules(). Because rules are values rather than virtual methods, the CLI can enumerate them (forge rules list) and print their full metadata (forge rules explain <RuleId>) without instantiating any compiler internals.

ExtensionContext

Context object passed to all extension callbacks during compilation.

MsiTableRow

A flexible row container for custom MSI table data.

10.2 Firewall Extension

Defines Windows Firewall rules to create during installation. Located in src/FalkForge.Extensions.Firewall/. Validation error codes: FWL001-004.

FirewallExtension

FirewallRuleBuilder

var firewall = new FirewallExtension();
firewall.AddRule(rule => rule
    .Id("WebServerRule")
    .Name("Allow HTTP Traffic")
    .Protocol(FirewallProtocol.Tcp)
    .Port("80")
    .Direction(FirewallDirection.Inbound)
    .Action(FirewallRuleAction.Allow)
    .Profile(FirewallProfile.All));

firewall.AddRule(rule => rule
    .Id("AppRule")
    .Name("Allow Application")
    .Program(@"[INSTALLFOLDER]myapp.exe")
    .Direction(FirewallDirection.Inbound)
    .Action(FirewallRuleAction.Allow));

10.3 IIS Extension

Configures IIS application pools, web sites, web applications, bindings, and certificates. Located in src/FalkForge.Extensions.Iis/. Windows-only ([SupportedOSPlatform("windows")]). Validation error codes: IIS001-011.

IisExtension

AppPoolBuilder

WebSiteBuilder

WebBindingBuilder

CertificateBuilder

WebApplicationBuilder

IIS Typed Reference Handles

var iis = new IisExtension();

// Define app pool with typed reference
var appPool = iis.DefineAppPool(pool => pool
    .Name("MyAppPool")
    .NoManagedCode()
    .PipelineMode(ManagedPipelineMode.Integrated)
    .IdleTimeout(0));

// Define certificate with typed reference
var cert = iis.DefineCertificate(c => c
    .Id("WildcardCert")
    .Store(CertificateStoreName.My, CertificateStoreLocation.LocalMachine)
    .FindBySubjectName("*.contoso.com"));

// Configure web site using typed references
iis.AddWebSite(site => site
    .Description("Contoso Web App")
    .Directory(@"[INSTALLFOLDER]wwwroot")
    .AppPool(appPool)              // compile-time safe
    .Binding(80)
    .Binding(b => b
        .Port(443)
        .HostHeader("www.contoso.com")
        .Certificate(cert))        // compile-time safe
    .AddApplication(app => app
        .Alias("/api")
        .Directory(@"[INSTALLFOLDER]api")
        .AppPool(appPool)));

10.4 SQL Extension

Configures SQL Server database creation, script execution, and inline SQL string execution. Located in src/FalkForge.Extensions.Sql/. Validation error codes: SQL001-013.

SqlExtension

SqlDatabaseBuilder

SqlScriptBuilder

SqlStringBuilder

SqlDatabaseRef

var sql = new SqlExtension();

// Define database with typed reference
var dbResult = sql.DefineDatabase(db => db
    .Id("AppDb")
    .Server("(local)")
    .Database("ContosoApp")
    .Instance("SQLEXPRESS")
    .CreateOnInstall()
    .DropOnUninstall());

if (dbResult.IsFailure)
    return Result<Unit>.Failure(dbResult.Error);

var dbRef = dbResult.Value;

// Execute schema script using typed reference
var schemaScript = new SqlScriptBuilder()
    .Id("CreateSchema")
    .Database(dbRef)
    .SourceFile("scripts/schema.sql")
    .ExecuteOnInstall()
    .RollbackScript("scripts/drop-schema.sql")
    .Sequence(1)
    .Build();

// Execute inline SQL using typed reference
var seedData = new SqlStringBuilder()
    .Id("SeedData")
    .Database(dbRef)
    .Sql("INSERT INTO Settings (Key, Value) VALUES ('Version', '1.0')")
    .ExecuteOnInstall()
    .Sequence(2)
    .Build();

10.5 .NET Extension

Detects installed .NET runtimes and emits real MSI-native detection into the compiled installer — a Signature (sentinel-file version) plus a DrLocator search over the platform-appropriate Program Files shared-framework directory, bound to the author's own property name via AppSearch. The built-in AppSearch standard action evaluates these natively at install time; no custom action is required (unlike the Dependency extension's version-range check, which needs one). Detection targets the shared-framework sentinel per RuntimeType: Runtime → coreclr.dll under Microsoft.NETCore.App, AspNetCore → Microsoft.AspNetCore.dll under Microsoft.AspNetCore.App, WindowsDesktop → PresentationCore.dll under Microsoft.WindowsDesktop.App. Sdk has no shared-framework directory (it is versioned via dotnet\sdk\{version}\, a different layout) and is rejected at author time with NET004. X64/Arm64 search under [ProgramFiles64Folder]; X86 searches [ProgramFilesFolder] (the WOW64 tree). Located in src/FalkForge.Extensions.DotNet/. Validation error codes: NET001–NET007.

Gating is author-chosen, two shapes: the C# fluent path leaves the search's message unset and gates explicitly with package.Require(variableName, message) (see Demo 32); the JSON authoring path (see JSON Configuration Format) has no separate Require call, so DotNetExtension emits its own LaunchCondition whenever a search carries a message (author-provided, or a generated default naming the requirement).

DotNetExtension

DotNetCoreSearchBuilder

Defines a search for a .NET runtime on the target machine.

var dotnet = new DotNetExtension();
var search = dotnet.SearchForRuntime()
    .RuntimeType(DotNetRuntimeType.AspNetCore)
    .Platform(DotNetPlatform.X64)
    .MinVersion(new Version(8, 0))
    .Variable("DOTNET8_ASPNETCORE_FOUND")
    .Build();

dotnet.AddSearch(search.Value);

Attach the extension with new MsiCompiler().Use(dotnet); without a message on the search, gate explicitly with package.Require("DOTNET8_ASPNETCORE_FOUND", "...") (see Demo 32, demo/32-ext-dotnet/Program.cs). Emission — the table rows landing correctly in the compiled MSI — is proven by a compile-and-read-back test (DotNetDetectionEmissionTests); a real msiexec install exercising the runtime gate end-to-end is not part of the default test run — it is gated the same way as the project's other real-system e2e tests (FALKFORGE_E2E + FALKFORGE_REAL_SYSTEM_E2E plus elevation).

10.6 Util Extension

Provides utility actions: XML configuration editing, quiet command execution, user/group management, file share creation, recursive folder removal, internet shortcut creation, and ODBC driver/data source registration. Located in src/FalkForge.Extensions.Util/. Validation error codes: XCF001-009, QEX001-004, FSH001-003, ISC001-004, RFX001-002, GRP001, ODB001.

UtilExtension

XmlConfigBuilder

Configures an XML file modification to execute during installation.

QuietExecBuilder

Configures a silent command-line execution during installation.

FileShareBuilder

Creates a Windows file share during installation.

UserBuilder

Creates or updates a Windows user account during installation.

GroupBuilder

Creates or references a Windows group during installation.

InternetShortcutBuilder

Creates a .url internet shortcut file during installation.

RemoveFolderExBuilder

Recursively removes a folder during install or uninstall (handles non-empty directories).

OdbcDriverBuilder

Registers an ODBC driver (ODBCDriver table row) so the ODBC driver manager knows about it at install time. Unlike the other Util builders above, its file reference is not free text: FileName must name a file the package already declares via Files(...), because the compiler derives the row's File_ and Component_ external keys from that file instead of asking the author to supply generated MSI identifiers directly. There is no ComponentRef here for that reason — component IDs are compiler-generated and no author could ever supply a valid one up front.

OdbcDataSourceBuilder

Registers an ODBC data source (ODBCDataSource table row, plus one ODBCSourceAttribute row per Property call). When DriverName matches an AddOdbcDriver entry's own driver name in the same package, the compiler attaches the data source to that driver's owning component so the two install and uninstall together; a DSN naming a driver the target machine already has falls back to the package's first component instead (the same fallback the built-in CreateFolder producer uses).

// The driver DLL must already be declared as a package file -- FileName below references it
// by name, it is not a free-form path.
package.Files(files => files
    .Add("payload/mydriver.dll")
    .To(KnownFolder.ProgramFiles / "Contoso" / "Drivers"));

var util = new UtilExtension();

util.AddOdbcDriver("ContosoDriver", d => d
    .DriverName("Contoso ODBC Driver")
    .FileName("mydriver.dll"));

util.AddOdbcDataSource("ContosoDsn", ds => ds
    .Name("Contoso Data Source")
    .DriverName("Contoso ODBC Driver")
    .Registration(OdbcRegistration.PerMachine)
    .Property("Server", "localhost")
    .Property("Database", "ContosoDb"));

// Wire the extension into the compiler, same as any other extension:
Installer.Build(args, package => { /* ... */ }, new MsiCompiler().Use(util));

// XML configuration modification
var xmlConfig = new XmlConfigBuilder()
    .Id("SetConnectionString")
    .File(@"[INSTALLFOLDER]appsettings.json")
    .XPath("//configuration/connectionStrings/add[@name='Default']")
    .SetAttribute("connectionString", "Server=(local);Database=MyApp;Trusted_Connection=True")
    .Sequence(1)
    .Build();

var util = new UtilExtension();

// Group first, so the user below can join it by name.
var group = util.AddGroup(g => g
    .Name("ContosoOperators")
    .Description("Operators group for the Contoso service account")
    .RemoveOnUninstall());
if (group.IsFailure) { Console.Error.WriteLine(group.Error); return 1; }

// PasswordProperty (not Password) keeps the secret out of the MSI in plaintext -- it's
// sourced from an MSI property set at install time instead.
var user = util.AddUser(u => u
    .Name("svc-contoso")
    .PasswordProperty("SVC_PASSWORD")
    .PasswordNeverExpires()
    .MemberOf("ContosoOperators")
    .RemoveOnUninstall());
if (user.IsFailure) { Console.Error.WriteLine(user.Error); return 1; }

var fileShare = util.AddFileShare(f => f
    .Id("AppData")
    .Name("ContosoAppData")
    .Directory(@"C:\ProgramData\Contoso\MyApp")
    .GrantRead("Everyone")
    .GrantFull("ContosoOperators"));
if (fileShare.IsFailure) { Console.Error.WriteLine(fileShare.Error); return 1; }

var removeFolderEx = util.AddRemoveFolderEx(r => r
    .Id("Cache")
    .Directory(@"C:\ProgramData\Contoso\MyApp\Cache")
    .OnUninstall());
if (removeFolderEx.IsFailure) { Console.Error.WriteLine(removeFolderEx.Error); return 1; }

var quietExec = util.AddQuietExec(q => q
    .Id("RunMigration")
    .Command(@"[INSTALLFOLDER]migrate.exe --apply")
    .WorkingDir("[INSTALLFOLDER]")
    .RollbackCommand(@"[INSTALLFOLDER]migrate.exe --rollback"));
if (quietExec.IsFailure) { Console.Error.WriteLine(quietExec.Error); return 1; }

var shortcut = util.AddInternetShortcut(s => s
    .Id("HelpLink")
    .Name("Product Documentation")
    .Target("https://docs.contoso.com")
    .Directory("ProgramMenuDir"));
if (shortcut.IsFailure) { Console.Error.WriteLine(shortcut.Error); return 1; }

// Wire the extension into the compiler, same as any other extension:
Installer.Build(args, package => { /* ... */ }, new MsiCompiler().Use(util));

See Demo 33 — ext-util for a runnable version of this pattern (the demo exercises AddFileShare/AddRemoveFolderEx/AddQuietExec/ AddInternetShortcut plus XmlConfigBuilder; user/group management follows the identical Add*(Action<TBuilder>) → Result<Unit> shape shown above).

11. Custom UI Framework

FalkForge provides a custom WPF UI framework for building installer user interfaces with full control over pages, styling, and navigation. The framework uses a page-registration pattern where each page is an InstallerPage<TView> subclass that acts as both ViewModel and page controller, with an associated WPF FrameworkElement as the view.

11.1 InstallerApp

Static entry point for custom UI installers. Orchestrates page creation, engine wiring, window creation, and WPF application lifecycle. Located in src/FalkForge.Ui/InstallerApp.cs.

public static int Main(string[] args)
{
    return InstallerApp.Run(args, ui => ui
        .Window(w => w
            .Title("My Installer")
            .Size(600, 400)
            .Accent("#0078D4"))
        .Pages(pages => pages
            .Add<WelcomePage>()
            .Add<InstallPage>()
            .Add<CompletePage>()));
}

11.2 InstallerUIBuilder

Top-level fluent builder composing window configuration and page registration. Located in src/FalkForge.Ui/InstallerUIBuilder.cs.

11.3 InstallerWindowBuilder

Configures the installer window appearance and behavior. Located in src/FalkForge.Ui/InstallerWindowBuilder.cs.