Extensions

What you'll learn

FalkForge ships 8 built-in extensions for common server and infrastructure tasks. No NuGet packages to install — they're part of the framework. This tutorial walks through each one.

Each extension follows the same pattern: create an instance, configure it with a fluent API, validate, then compile alongside your MSI package. The SDK extension pipeline wires everything together at build time.

Firewall Rules

The FirewallExtension adds Windows Firewall rules that are installed and removed with your MSI. Open demo/29-ext-firewall/Program.cs to follow along.

Adding a rule

var firewall = new FirewallExtension();

firewall.AddRule(rule => rule
    .Id("AllowHttp")
    .Name("My App HTTP")
    .Description("Allow inbound HTTP on port 8080")
    .Protocol(FirewallProtocol.Tcp)
    .Port("8080")
    .Direction(FirewallDirection.Inbound)
    .Action(FirewallRuleAction.Allow)
    .Profile(FirewallProfile.All));

Each rule needs an Id, a display Name, and the network settings: protocol, port, direction, and action. The Profile controls which network profiles the rule applies to — Domain, Private, Public, or All.

Validation

var errors = firewall.ValidateRules();

Always validate before compiling. Error codes start with FWL (FWL001–FWL004).

IIS Configuration

The IisExtension manages application pools, web sites, bindings, and certificates. Open demo/30-ext-iis/Program.cs.

Defining an app pool

var iis = new IisExtension();

var appPool = iis.DefineAppPool(pool => pool
    .Id("DemoPool")
    .Name("DemoPool")
    .NoManagedCode()
    .PipelineMode(ManagedPipelineMode.Integrated)
    .Identity(AppPoolIdentityType.ApplicationPoolIdentity));

DefineAppPool returns an AppPoolRef — a typed reference handle you pass to web sites. NoManagedCode() sets the CLR version to empty, which is correct for modern .NET apps running via the ASP.NET Core Module.

Adding a web site

iis.AddWebSite(site => site
    .Id("DemoSite")
    .Description("Demo Web Site")
    .Directory("[INSTALLDIR]wwwroot")
    .AppPool(appPool)
    .Binding(8080)
    .AutoStart(true));

The AppPool(appPool) call uses the typed AppPoolRef returned by DefineAppPool. This ensures type safety — you can't accidentally pass a string that doesn't match an existing pool. Binding(8080) sets up an HTTP binding on that port.

SQL Server

The SqlExtension creates databases and runs SQL scripts during installation. Open demo/31-ext-sql/Program.cs.

Defining a database

var sql = new SqlExtension();

var dbRef = sql.DefineDatabase(db => db
    .Id("AppDb")
    .Server(".")
    .Database("DemoDb")
    .CreateOnInstall()
    .ConfirmOverwrite());

DefineDatabase returns a Result<SqlDatabaseRef>. The Server(".") targets the local instance. CreateOnInstall() creates the database during installation. ConfirmOverwrite() prompts the user if the database already exists.

Running scripts

var script = new SqlScriptBuilder()
    .Id("CreateSchema")
    .Database(dbRef.Value)
    .SourceFile("payload\\schema.sql")
    .ExecuteOnInstall()
    .Sequence(1)
    .Build();

sql.Scripts.Add(script.Value);

Scripts reference a database via the typed SqlDatabaseRef. The Sequence number controls execution order when you have multiple scripts. ExecuteOnInstall() runs the script during installation only.

.NET Runtime Detection

The DotNetExtension detects installed .NET runtimes. Combine it with launch conditions to block installation when a required runtime is missing. Open demo/32-ext-dotnet/Program.cs.

Searching for a runtime

var dotnet = new DotNetExtension();

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

This searches for the .NET 8+ runtime on x64. The result is stored in the MSI property DOTNET8_FOUND.

Using as a launch condition

package.Require("DOTNET8_FOUND",
    ".NET 8.0 Runtime (x64) or later is required.");

Require adds a launch condition. If DOTNET8_FOUND is empty at install time, the MSI shows the error message and aborts. The user must install .NET 8 first.

Utility Operations

The UtilExtension bundles six common operations into one extension. Open demo/33-ext-util/Program.cs for the XML configuration example.

XmlConfig — modify XML files during install

var util = new UtilExtension();

var config = new XmlConfigBuilder()
    .Id("SetMode")
    .File("[INSTALLDIR]app.config")
    .XPath("//appSettings/add[@key='Mode']")
    .SetAttribute("value", "production")
    .Sequence(1)
    .Build();

util.XmlConfig.Add(config.Value);

Target any XML file with an XPath expression. SetAttribute modifies an existing attribute. The change is applied during install and reverted on uninstall.

Other utilities

• UserMgmt — create local users and groups during installation.
• FileShare — create Windows file shares pointing to installed directories.
• QuietExec — run a command-line tool silently during install.
• RemoveFolderEx — recursively delete folders on uninstall, including files created after installation.
• InternetShortcut — create .url shortcut files on the desktop or Start Menu.

Validation error codes are XCF001–XCF009.

Dependency Provider/Consumer

The DependencyExtension implements WiX-compatible reference counting between MSI packages. Open demo/34-ext-dependency/Program.cs.

Registering as a provider

var dependency = new DependencyExtension();

dependency.Provides("Demo.SharedRuntime", provider => provider
    .Version("1.0.0")
    .DisplayName("Demo Shared Runtime"));

This registers your package as a provider of Demo.SharedRuntime version 1.0.0. Other packages can declare a dependency on this key.

Declaring a requirement

dependency.Requires("Demo.Framework", consumer => consumer
    .ConsumerKey("Demo.App")
    .MinVersion("2.0.0")
    .MinInclusive());

Requires declares that this package needs Demo.Framework at version 2.0.0 or higher. ConsumerKey identifies this package in the dependency graph. MinInclusive() means version 2.0.0 itself satisfies the requirement.

Recap