Coming from WiX

If you know WiX, you already know MSI. FalkForge targets the same Windows Installer tables — it just uses C# instead of XML. This guide translates the WiX patterns you know into FalkForge equivalents.

Concepts mapping

Common patterns

Each pattern shows WiX v4 XML on the left and FalkForge C# on the right.

Adding files

<Component Directory="INSTALLFOLDER">
  <File Source="app.exe" />
</Component>

package.AddFile("payload/app.exe")
    .To("INSTALLFOLDER")
    .WithFeature("Main");

Registry entries

<Component Directory="INSTALLFOLDER">
  <RegistryValue Root="HKLM"
    Key="SOFTWARE\MyApp"
    Name="InstallDir"
    Type="string"
    Value="[INSTALLFOLDER]" />
</Component>

package.AddRegistryEntry(
    RegistryHive.LocalMachine,
    @"SOFTWARE\MyApp",
    "InstallDir",
    "[INSTALLFOLDER]")
    .WithFeature("Main");

Windows services

<Component Directory="INSTALLFOLDER">
  <File Source="myservice.exe" />
  <ServiceInstall
    Name="MyService"
    DisplayName="My Service"
    Start="auto"
    Type="ownProcess"
    Account="LocalSystem" />
  <ServiceControl
    Id="StartMyService"
    Name="MyService"
    Start="install"
    Stop="both"
    Remove="uninstall" />
</Component>

package.AddFile("payload/myservice.exe")
    .To("INSTALLFOLDER")
    .WithFeature("Server")
    .AddService("MyService", svc => svc
        .DisplayName("My Service")
        .StartType(ServiceStartType.Automatic)
        .Account(ServiceAccount.LocalSystem));

Shortcuts

<Component Directory="ProgramMenuFolder">
  <Shortcut Id="StartMenuShortcut"
    Name="My App"
    Target="[INSTALLFOLDER]app.exe"
    WorkingDirectory="INSTALLFOLDER" />
  <RemoveFolder Id="RemovePMF"
    On="uninstall" />
  <RegistryValue Root="HKCU"
    Key="SOFTWARE\MyApp"
    Name="installed"
    Type="integer"
    Value="1"
    KeyPath="yes" />
</Component>

package.AddShortcut("My App",
    "[INSTALLFOLDER]app.exe")
    .ToStartMenu()
    .WithFeature("Main");

Features

<Feature Id="Main"
  Title="Main Application"
  Level="1">
  <ComponentRef Id="AppComponent" />
  <Feature Id="Plugins"
    Title="Optional Plugins"
    Level="1">
    <ComponentRef Id="Plugin1" />
  </Feature>
</Feature>

package.AddFile("payload/app.exe")
    .WithFeature("Main");

package.AddFile("payload/plugin1.dll")
    .WithFeature("Plugins", parent: "Main");

Custom actions

<CustomAction Id="SetInstallDir"
  Property="INSTALLFOLDER"
  Value="C:\MyApp" />
<InstallExecuteSequence>
  <Custom Action="SetInstallDir"
    Before="CostFinalize" />
</InstallExecuteSequence>

package.AddSetPropertyAction(
    "INSTALLFOLDER", @"C:\MyApp")
    .Before(SequenceAction.CostFinalize);

Properties and conditions

<Property Id="MYPROP"
  Value="default" />
<Condition Message="Requires Windows 10">
  <![CDATA[VersionNT >= 1000]]>
</Condition>

package.SetProperty("MYPROP", "default");
package.AddLaunchCondition(
    Condition.IsWindows10OrLater,
    "Requires Windows 10");

Major upgrade

<MajorUpgrade
  DowngradeErrorMessage="A newer version is installed." />

package.MajorUpgrade(upgrade => upgrade
    .BlockDowngrades(
        "A newer version is installed."));

Localization

<WixLocalization
  Culture="en-US"
  xmlns="http://wixtoolset.org/schemas/v4/wxl">
  <String Id="WelcomeTitle">Welcome</String>
</WixLocalization>

package.Localization(loc => loc
    .AddBuiltInCultures()
    .DefaultCulture("en-US")
    .DetectCulture());

Launch conditions

<Launch
  Condition="Privileged"
  Message="Administrator privileges required." />

package.AddLaunchCondition(
    Condition.IsPrivileged,
    "Administrator privileges required.");

Extension mapping

Bundle migration

WiX Burn and FalkForge bundles serve the same purpose — chaining multiple packages into a single installer. Key differences:

• NativeAOT engine — no .NET runtime needed at install time. The bundle engine is a self-contained native executable.
• DPAPI secure property passing — properties never appear as plaintext command-line arguments. Secure values are passed via named pipe IPC and protected with Windows DPAPI.
• IMsiApi P/Invoke — MSI packages are installed via direct Windows Installer API calls, not by spawning msiexec.exe as a subprocess.
• Built-in WPF UI — no need to write a custom bootstrapper application from scratch. Use InstallerPage<TView> with ReactiveUI for custom installer pages.
• JSON update feeds — simpler than Atom XML. Configure with UpdatePolicy for notify-only, download-and-prompt, or auto-update.
• Same package types — MSI, MSP, MSU, EXE, and nested Bundle are all supported.

What you gain

• Compile-time validation — typos caught at build, not install time.
• MSIX output — build MSI and MSIX from the same codebase.
• SBOM generation — CycloneDX format for supply chain security.
• Triple decompiler — decompile MSI, FalkForge bundles, and WiX Burn bundles.
• NativeAOT engine — smaller, faster, no runtime dependency.
• Built-in WPF custom UI — InstallerPage<TView> with ReactiveUI.
• ECDSA payload signing — free, built-in tamper-evident integrity verification for bundle payloads, no external tool required. An optional separate tool, Sigil, adds SBOM attestation on top (see Sigil in the reference docs).
• Compile-time security guards — REG007 warns when registry values reference password properties. WiX has no equivalent compile-time check.
• WinGet manifest generation — .WinGet() on PackageBuilder auto-generates the 3-file YAML manifest set. Advanced Installer charges $2,400+/year for this feature.

Migrating your existing installer

forge migrate is the recommended starting point for any WiX (or other tool) migration. It reads your compiled .msi, .msm, or WiX Burn .exe and writes a complete, buildable FalkForge C# project — not just a code snippet.

Run it

forge migrate your-product.msi -o ./migrated --falkforge-src /path/to/falkforge/src

After it finishes, ./migrated/ contains:

• Program.cs — full fluent API installer definition, reconstructed from the MSI database
• YourProduct.csproj — project file with references to FalkForge.Core and Compiler.Msi
• payload/ — files extracted from the original MSI cabinet
• MIGRATION-REPORT.md — lists anything that did not map automatically (complex custom actions, unusual sequences, etc.)

Build the generated project immediately:

dotnet build migrated/

If the build succeeds, the round-trip is complete. You now have an editable FalkForge project that produces an equivalent installer.

Flags

See demo/54-forge-migrate for a full round-trip example, including a PowerShell script that automates all three steps (build sample MSI → migrate → build generated project).

Just want to inspect? Use decompile

forge decompile your-product.msi

This generates a C# snippet from your existing MSI. Good for inspecting structure or lifting specific patterns, but it is not a buildable project. Use forge migrate (above) for a full migration.