MSI Basics

The Getting Started tutorial built a minimal installer. Real installers need shortcuts, services, registry entries, and features. This tutorial covers the building blocks you'll use in every project.

Shortcuts & Upgrades

Demo 02 (demo/02-notepad-clone) creates a text editor installer with desktop shortcuts, registry entries, and major-upgrade support.

Desktop, Start Menu, and Startup shortcuts

FalkForge provides a fluent Shortcut API. Each call targets a different location.

// Desktop shortcut with icon
package.Shortcut("FalkPad", "falkpad.exe")
    .WithIcon("payload/falkpad.ico")
    .WithDescription("Launch FalkPad text editor")
    .OnDesktop();

// Start menu shortcut under a company subfolder
package.Shortcut("FalkPad", "falkpad.exe")
    .WithIcon("payload/falkpad.ico")
    .OnStartMenu("Falk Software");

// Startup shortcut — launches on Windows login
package.Shortcut("FalkPad Startup", "falkpad.exe")
    .WithArguments("--minimized")
    .OnStartup();

The first argument is the shortcut name visible to the user. The second is the target executable. Chain OnDesktop(), OnStartMenu(), or OnStartup() to place the shortcut. You can also chain multiple locations on a single shortcut call.

Registry entries

Use Registry to write keys and values during installation.

package.Registry(reg => reg
    .Key(RegistryRoot.LocalMachine, @"Software\FalkSoftware\FalkPad", key =>
    {
        key.Value("Version", "2.1.0");
        key.Value("InstallPath", MsiProperty.InstallDir);
        key.DWord("EditorFlags", 3);
        key.DefaultValue("FalkPad Text Editor");
    }));

Value writes a string. DWord writes a 32-bit integer. DefaultValue sets the key's (Default) entry. You can reference MSI properties like MsiProperty.InstallDir — the installer resolves them at install time.

Removing registry on uninstall

Registry entries created by the installer are removed automatically. To clean up entries created by your application at runtime, use RemoveRegistry.

package.RemoveRegistry(rr => rr
    .Id("RemoveFalkPadRegKey")
    .Root(RegistryRoot.LocalMachine)
    .Key(@"Software\FalkSoftware\FalkPad")
    .RemoveKey());

RemoveKey() deletes the entire key and its values on uninstall. This catches any values your application added after installation.

Major upgrade strategy

When you release version 2.1 to replace version 2.0, Windows needs to know it's the same product. The major upgrade pattern handles this.

package.MajorUpgrade(_ => { });
package.Downgrade(d => d.Block("A newer version is already installed."));

MajorUpgrade tells Windows Installer to uninstall the previous version before installing the new one. Downgrade(...).Block() prevents users from installing an older version over a newer one, showing the provided message instead.

License agreement

Demo 02 uses the InstallDir dialog set, which includes a license page. Point it at an RTF file.

package.LicenseFile = "payload/license.rtf";
package.UseDialogSet(MsiDialogSet.InstallDir);

The installer shows the license text and requires acceptance before proceeding. The file must be RTF format — that is a Windows Installer requirement.

Services & Launch Conditions

Demo 03 (demo/03-client-server) installs a client application, a Windows service, and documentation as three selectable features.

Multiple features

You saw features in the Getting Started tutorial. Here's how to define multiple named features so users can pick what to install.

p.Feature("Client", f =>
{
    f.Title = "Client Application";
    f.Description = "Desktop client with user interface";
    f.IsDefault = true;
    f.IsRequired = false;
});

p.Feature("Server", f =>
{
    f.Title = "Server Application";
    f.Description = "Background service for data processing";
    f.IsDefault = true;
    f.IsRequired = false;
});

IsDefault means the feature is selected by default. IsRequired prevents the user from deselecting it. Pair this with MsiDialogSet.FeatureTree to show a feature picker.

p.UseDialogSet(MsiDialogSet.FeatureTree);

Windows service installation

The Service API registers a Windows service. The installer creates, starts, stops, and removes it automatically.

p.Service("AcmeServer", svc =>
{
    svc.DisplayName = "Acme Server";
    svc.Description = "Acme Client-Server Suite background service";
    svc.Executable = "server.exe";
    svc.StartMode = ServiceStartMode.Automatic;
    svc.Account = ServiceAccount.LocalSystem;
    svc.Arguments = "--port=8080 --config=appsettings.json";
});

The first argument is the service name (used by sc.exe and the Services console). StartMode controls when the service starts: Automatic, Manual, or Disabled. Account sets the identity: LocalSystem, LocalService, or NetworkService.

Launch conditions

Launch conditions block installation if prerequisites are missing. The installer checks them before copying any files.

p.Require(Condition.IsWindows10OrLater,
    "This application requires Windows 10 or later.");

FalkForge provides typed conditions like Condition.IsWindows10OrLater, Condition.IsPrivileged, and Condition.Is64BitOS. You can also pass a raw property name as a string.

Environment variables

Set or append system environment variables during installation.

p.EnvironmentVariable("ACME_SERVER_PORT", "8080", ev =>
{
    ev.IsSystem = true;
    ev.Action = EnvironmentVariableAction.Set;
});

Set creates or overwrites the variable. Append adds to an existing value (useful for PATH). IsSystem = true writes a machine-level variable; false writes a per-user one. The installer removes the variable on uninstall.

Demo 03 also shows how to use MsiProperty as a value — the install directory resolves at install time:

p.EnvironmentVariable("ACME_INSTALL_DIR", MsiProperty.InstallFolder, ev =>
{
    ev.IsSystem = true;
    ev.Action = EnvironmentVariableAction.Set;
});

File Associations & Custom Actions

Demo 04 (demo/04-dev-toolkit) builds a developer toolkit with nested features, file type registration, PATH modification, and a custom action.

Nested features

Features can contain child features. Define them inside the parent's lambda.

p.Feature("Editor", f =>
{
    f.Title = "Editor";
    f.Description = "Source code editor with syntax highlighting";
    f.IsDefault = true;

    // Nested feature: Editor Plugins
    f.Feature("EditorPlugins", child =>
    {
        child.Title = "Editor Plugins";
        child.Description = "Linter, formatter, and Git integration";
        child.IsDefault = true;
    });
});

In the feature tree UI, "Editor Plugins" appears indented under "Editor". Deselecting the parent deselects all children. Selecting a child auto-selects the parent.

File associations

Register your application as the handler for a file type.

p.FileAssociation(".falk", fa =>
{
    fa.ProgId("FalkTech.FalkProject");
    fa.Description = "Falk Project File";
    fa.Verb(ShellVerb.Open, "\"%1\"");
});

The first argument is the file extension. ProgId is a unique identifier for the association (convention: Company.AppName). Verb defines the action — ShellVerb.Open is the default double-click action, and "%1" is replaced with the file path.

PATH modification

Add your tool's directory to the system PATH so users can run it from any command prompt.

p.EnvironmentVariable("PATH", "[INSTALLFOLDER]bin", ev =>
{
    ev.IsSystem = true;
    ev.Action = EnvironmentVariableAction.Append;
    ev.Separator = ";";
});

Append adds your directory to the existing PATH value, separated by ;. The installer removes just your entry on uninstall — it does not overwrite the entire PATH variable.

Custom actions

Custom actions run logic during the install sequence. The simplest form sets an MSI property.

p.CustomAction("SetFalkVersion", ca =>
{
    ca.SetProperty("FALK_VERSION", "5.0.0");
    ca.After = "InstallValidate";
});

The After property controls when the action runs. MSI has a fixed sequence of standard actions (CostInitialize, CostFinalize, InstallValidate, etc.). Your custom action slots in relative to these.

The Mondo dialog

Demo 04 uses MsiDialogSet.Mondo — the most full-featured built-in dialog set. It combines directory selection with a feature tree, giving the user maximum control over what gets installed and where.

p.UseDialogSet(MsiDialogSet.Mondo);

Enterprise Feature Trees

Demo 05 (demo/05-enterprise-suite) is a 500-line installer for a large product. Rather than walk through every line, let's focus on the patterns you'll reuse.

Large feature hierarchies

Demo 05 defines eight top-level features. Several have nested children. Here's the "Database Tools" branch:

pkg.Feature("DatabaseTools", db =>
{
    db.Title = "Database Tools";
    db.IsDefault = true;

    db.Feature("SqlExplorer", se => {
        se.Title = "SQL Explorer";
        se.IsDefault = true;
        se.Files(f => f.Add(...).To(dbExplorerDir));
    });

    db.Feature("SchemaDesigner", sd => { /* ... */ });

    // Opt-in: not selected by default
    db.Feature("DbProfiler", dp => {
        dp.Title = "Performance Profiler";
        dp.IsDefault = false;
    });
});

Notice that files are added directly inside the feature lambda using se.Files(...). This scopes those files to the feature — they only install when the user selects "SQL Explorer".

Font registration

Install a font so it's available system-wide.

pkg.Font("payload/fonts/ApexMono.ttf", f =>
{
    f.Title = "Apex Mono";
});

FalkForge copies the font file to the Windows Fonts folder and registers it. The font is available to all applications immediately after install.

Custom tables

Store arbitrary metadata inside the MSI database. Custom actions or external tools can read it later.

pkg.CustomTable(ct =>
{
    ct.Name("ApexComponents");
    ct.Column("ComponentId", CustomTableColumnType.String,
        c => c.PrimaryKey().Width(72));
    ct.Column("Category", CustomTableColumnType.String,
        c => c.Width(64));
    ct.Column("Priority", CustomTableColumnType.Int32);

    ct.Row(r => r
        .Set("ComponentId", "apex.core.dll")
        .Set("Category", "IDE")
        .Set("Priority", 1));
});

Define columns with types and constraints, then add rows. The table becomes part of the MSI database and survives installation — you can query it with forge inspect.

The Advanced dialog

Demo 05 uses MsiDialogSet.Advanced — the most complete built-in dialog. It adds Typical, Custom, and Complete install types on top of directory and feature selection. Users who want a quick install pick Typical; power users pick Custom to fine-tune features.

pkg.UseDialogSet(MsiDialogSet.Advanced);

Recap

Inspecting Your Installer

Want to see what files are inside an MSI without installing it? Use the extract command:

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

This extracts all files to disk, mirroring the directory structure as it would be installed. For bundles containing multiple MSIs:

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

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

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

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

WinGet Distribution

Want to distribute your installer via winget install? FalkForge can generate WinGet manifests automatically:

package.WinGet(w => w
    .PackageIdentifier("Contoso.MyApp")
    .License("MIT")
    .ShortDescription("A tool for doing things")
    .InstallerUrl("https://releases.contoso.com/myapp/1.0.0/MyApp.msi"));

This generates three YAML manifest files alongside your MSI — the format required by the winget-pkgs repository. Version, publisher, product code, and SHA-256 are auto-populated from your package definition.

forge winget myapp.msi --id Contoso.MyApp --license MIT --desc "A tool" -o ./manifests

What's next

• Custom UI — build your own WPF installer pages with InstallerPage and InstallerApp (coming soon).
• Bundles — wrap multiple MSIs into a single EXE with a bootstrapper (coming soon).
• Extensions — Firewall rules, IIS sites, SQL databases, and more (coming soon).