InstallKit.Sdk 1.0.0-rc.1

This is a prerelease version of InstallKit.Sdk.
There is a newer prerelease version of this package available.
See the version list below for details.
<Sdk Name="InstallKit.Sdk" Version="1.0.0-rc.1" />
                    
For projects that support Sdk, copy this XML node into the project file to reference the package.
#:sdk InstallKit.Sdk@1.0.0-rc.1
                    
#:sdk directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

InstallKit

NuGet NuGet downloads CI License: MIT

Build Windows installers (MSI and setup .exe bundles) with plain C# and dotnet build. InstallKit sits on top of WixSharp and the WiX Toolset, and adds a fluent API, an MSBuild SDK, a native modern installer UI, install-time C# handlers and ready-made Azure DevOps pipeline templates.

Status: early preview (0.1). The API may still change between releases. Feedback and issues are welcome.

Why InstallKit

  • Installers as code: describe the product, services, shortcuts and prerequisites in C#, with validation errors that point at the problem before WiX runs.
  • One command: dotnet build publishes your app, then produces the MSI and, optionally, a single setup.exe bundle.
  • Modern look without extra dependencies: branded native dialogs that need nothing on the target machine.
  • Install-time code in C#: run static methods during install or uninstall, with no WixSharp types in your code.
  • CI included: Azure DevOps templates that build, sign, smoke-test (install and uninstall) and publish.
  • Two engines: WixSharp on .NET Framework 4.8, or a WixSharp.Core preview on .NET 10, with the same installer code.

Requirements

  • Build machine: Windows and the .NET SDK. WiX is restored as a pinned local tool.
  • Target machine: usually nothing beyond Windows. See What target machines need.

Example

using InstallKit;

return InstallerHost.Run(args, plan =>
{
    var app = plan.Msi(MsiBuilder.Create("My App")
        .WithManufacturer("Contoso")
        .WithUpgradeCode("0b6f9a8e-3c1d-4e57-9a43-6d2f1c8b7e10")
        .WithPayload("MyApp")                  // published output of <InstallerPayload>
        .WithMainExecutable("MyApp.exe")       // gets a Start menu shortcut
        .WithDesktopShortcut());

    plan.Bundle(BundleBuilder.Create("My App") // optional: one setup.exe with prerequisites
        .WithUpgradeCode("5a2e7c41-9d83-4b6f-8e15-c3a09f4d2b77")
        .WithNetFramework(NetFrameworkVersion.NetFx48)
        .WithMsi(app));
});
<Project Sdk="InstallKit.Sdk/0.1.0-preview.1">
  <ItemGroup>
    <InstallerPayload Include="..\MyApp\MyApp.csproj" PublishProperties="RuntimeIdentifier=win-x64;SelfContained=true" />
  </ItemGroup>
</Project>

dotnet build -p:Version=1.2.3 publishes MyApp, then writes bin/installer/Release/MyApp.msi and MyAppSetup.exe.

Builders

The fluent builders are the preferred way to describe installers, and every example below uses them. MsiBuilder, BundleBuilder and ServiceBuilder are generated by BuilderGenerator:

  • Generated: every settable property gets WithX(value), WithX(() => value) and WithoutX() automatically, so a new model property needs no builder code.
  • Hand-written: only the "add one more" helpers in src/InstallKit.Abstractions/Builders.cs, such as WithPayload, WithService, WithProperty, the shortcut toggles, the custom actions, and the bundle chain methods.
  • Start from Create(...): a bare new MsiBuilder() has no defaults and would reset them (for example Ui or the Start menu shortcut). plan.Msi(...) rejects a builder without a name.

You can still set properties directly, with plan.Msi("My App", msi => { msi.Manufacturer = "Contoso"; ... }), for cases a builder method doesn't cover yet. Both produce the same MsiDefinition.

Layout

Folder What it is
src/InstallKit.Abstractions Engine-neutral model: MsiDefinition, BundleDefinition, validation, InstallerHost. No WixSharp types.
src/InstallKit.WixSharp The default engine: maps the model to WixSharp v2 on .NET Framework 4.8.
src/InstallKit.WixSharp.Core Preview engine on WixSharp.Core (.NET 10). It compiles the same engine source.
src/InstallKit.Sdk MSBuild SDK: publishes payloads, restores the pinned wix tool, runs the installer program.
templates/ dotnet new installkit project template (generates the upgrade codes for you).
pipelines/ Azure DevOps step, job and stage templates.
samples/ A Windows service with an MSI and a bundle, plus an example azure-pipelines.yml.
tests/ Unit tests for the model, version handling and validation.
qa/ End-to-end QA: a demo installer that uses most features, plus Pester tests that install, upgrade, repair and uninstall it on a Windows agent.

Getting started

The packages are on nuget.org. While InstallKit is a preview, name the version explicitly (a bare 0.1.0 is not the same version as 0.1.0-preview.1):

dotnet new install InstallKit.Templates::0.1.0-preview.1
dotnet new installkit -n MyApp.Installer --sdkVersion 0.1.0-preview.1 --product "My App" --manufacturer Contoso --payload ../MyApp/MyApp.csproj --bundle
# add --engine WixSharpCore for the .NET 10 preview engine
# once per repository: pin the WiX toolset
dotnet new tool-manifest
# InstallKit needs the manifest at .config/dotnet-tools.json. The .NET 10 SDK creates dotnet-tools.json
# in the root instead, so if that happens, move it: create a .config folder and move the file into it.
dotnet tool install wix --version 6.0.2
dotnet build MyApp.Installer -p:Version=1.0.0

Building the MSI requires Windows (WiX and the .NET Framework engine). On other OSes the build stops with IK003. You can set InstallKitBuildOnBuild=false there, which still compiles the project.

Using your own build output

You don't need a monorepo, and you don't need InstallKit to build your application. If your pipeline already produces the files to ship (a dotnet publish folder, a build artifact, files downloaded from another job), leave out <InstallerPayload> and give the installer the folder's path:

using InstallKit;

// The pipeline that built the application passes the folder in.
var appDir = Environment.GetEnvironmentVariable("APP_PUBLISH_DIR")
    ?? throw new InvalidOperationException("Set APP_PUBLISH_DIR to the published application folder.");

return InstallerHost.Run(args, plan =>
{
    plan.Msi(MsiBuilder.Create("My App")
        .WithManufacturer("Contoso")
        .WithUpgradeCode("0b6f9a8e-3c1d-4e57-9a43-6d2f1c8b7e10")
        .WithDirectory(appDir)                 // every file in the folder, keeping its structure
        .WithMainExecutable("MyApp.exe"));     // relative to the folder; gets the Start menu shortcut
});
<Project Sdk="InstallKit.Sdk/0.1.0-preview.1">
  
</Project>
APP_PUBLISH_DIR=/path/to/publish dotnet build MyApp.Installer -p:Version=1.2.3
  • Any path works: absolute or relative, on any drive. A relative path is relative to the installer project folder, so prefer absolute paths from a pipeline.
  • Checked before WiX runs: a folder that doesn't exist fails with IK112, and an MSI with no files at all fails with IK110.
  • Mix and match: call WithDirectory several times, optionally with a target subfolder (.WithDirectory(docsDir, "docs")), and combine it with WithPayload.
  • Existing installers in a bundle: WithMsi("path.msi") chains an MSI that was built elsewhere, and WithExe(path, ...) chains any other setup program.
  • Your pipeline: the build only needs a Windows agent, the .NET SDK and the pinned wix tool (dotnet tool restore). The Azure DevOps templates in pipelines/ are optional.

How it works

  1. dotnet build compiles the installer project as a small .NET Framework console app.
  2. The SDK runs dotnet tool restore so the wix version in .config/dotnet-tools.json is used. WiX extensions are pinned to that same version, so newer extensions on NuGet can't silently break the build.
  3. Each <InstallerPayload> project is published into obj/installkit/payload/<Name>/, starting from an empty folder each time.
  4. The SDK runs the program. InstallerHost validates the plan before WiX runs, then builds every MSI, then every bundle.
  5. The built files end up in @(InstallerOutput), and the generated .wxs is kept in obj/installkit/ for review.

Validation errors use MSBuild's format (error IK101: ...), so they appear in Visual Studio's error list and in Azure DevOps annotations. Examples:

  • A missing UpgradeCode. The error suggests a newly generated one.
  • Upgrade codes shared between packages.
  • An unknown payload name.
  • A main executable that isn't in any payload.
  • An .exe prerequisite without a DetectCondition.
  • A version that doesn't fit MSI's 255.255.65535 limit.

MSBuild properties

Property Default
Version / InstallKitVersion 1.0.0 Prerelease and +metadata suffixes are dropped.
InstallKitOutputDir bin/installer/$(Configuration)/
InstallKitBuildOnBuild true Set to false for fast inner-loop builds.
InstallKitRestoreTools true Runs dotnet tool restore.
InstallKitEmitSource true Keeps the generated .wxs.
InstallKitSignCommand empty See Signing.
InstallKitAcceptWixEula empty wix7 accepts the WiX 7 EULA. See WiX version and licence.
InstallKitEngine WixSharp WixSharp or WixSharpCore. See Engines.

To add your own steps, hook targets onto InstallKitBuild: BeforeTargets="InstallKitBuild" or AfterTargets="InstallKitBuild". @(InstallerOutput) holds the built files.

Escape hatch

Anything the model doesn't cover yet can be done with raw WixSharp:

using InstallKit.WixSharp;

MsiBuilder.Create("My App")
    .ConfigureWixSharp(project => project.ControlPanelInfo.HelpLink = "https://contoso.com/support");

Code that uses this escape hatch is tied to the WixSharp engine, so move recurring needs into the model instead.

Editor checks

InstallKit.Abstractions ships Roslyn analyzers that flag mistakes while you type, before the installer program runs:

Code Severity Finds
IK300 Warning An upgrade code that is not a constant string, such as Guid.NewGuid().ToString() or a Func overload. A different value on every build makes Windows treat each build as a new product, so upgrades stop working.
IK301 Error An upgrade code that is not a valid GUID (or is all zeros).
IK302 Error The same upgrade code used for two MSIs or bundles in one project.
IK303 Warning new MsiBuilder(), new BundleBuilder() or new ServiceBuilder() instead of Create(...), which would reset the model's defaults.

They check WithUpgradeCode(...) and assignments to UpgradeCode. Everything else is still checked by the validators when the installer program runs, with the IK1xx codes above.

Versions side by side

By default a newer version replaces the installed one (a major upgrade). To keep versions apart, so installing 3.5.6 does not remove 3.1.0, set a side-by-side mode:

MsiBuilder.Create("My App")
    .WithManufacturer("Contoso")
    .WithUpgradeCode("0b6f9a8e-3c1d-4e57-9a43-6d2f1c8b7e10")   // keep this forever; the per-line codes are derived from it
    .WithSideBySide(SideBySideMode.MajorMinor)
    .WithService("MyService.exe", "MyService");
Mode A new version replaces Installs next to
None (default) every older version nothing
Major versions with the same major version (3.1.0 and 3.5.6) other majors (4.0.0)
MajorMinor versions with the same major and minor version (3.1.0 and 3.1.9) other minor versions (3.1.x and 3.5.x)
Full nothing every version

What a line (for example 3.1) changes at build time, so the products do not collide:

  • Name: My App 3.1, which is the entry in Add or Remove Programs, the Start menu folder, the default install folder (%ProgramFiles%\Contoso\My App 3.1) and the default output file name (MyApp3.1.msi).
  • Upgrade code: a stable GUID derived from yours and the line, so Windows Installer treats each line as its own product (and gives its components their own GUIDs). The code you write stays the same forever.
  • Services: MyService-3.1, with the display name MyService 3.1, so two versions can run at once. Mind the ports and data folders they use.
  • Version line: comes from the MSI's Version, or the -p:Version of the build.

Things to know:

  • A custom InstallDirectory must contain the line (IK270), otherwise the versions share a folder.
  • Bundles: a bundle that chains a side-by-side MSI needs the same SideBySide mode (IK271), otherwise a newer bundle replaces the older one together with its MSIs. A side-by-side bundle gets its name and upgrade code per line in the same way.
  • Machine-wide settings are not renamed: registry values, environment variables, file associations, URL protocols and firewall rules keep the names you gave them, so versions share them. The build prints warning IK273 when you use them together. Put the version into their names where they must not be shared.
  • Switching an existing product: a build with a side-by-side mode has new upgrade codes, so it does not upgrade versions that were installed without one. Uninstall those first, or keep the mode None for the line you already shipped.

Command line tool

src/InstallKit.Tool builds the installkit command (a .NET 8 program that also runs on newer runtimes):

dotnet run --project src/InstallKit.Tool -c Release -- new-guid 2       # two fresh GUIDs for UpgradeCodes
dotnet run --project src/InstallKit.Tool -c Release -- inspect MyApp.msi            # what the MSI installs
dotnet run --project src/InstallKit.Tool -c Release -- inspect MyApp.msi --json     # the same as JSON
dotnet run --project src/InstallKit.Tool -c Release -- diff MyApp-1.0.msi MyApp-1.1.msi
  • inspect: product name, version, codes, features, files with sizes, services, registry values, environment variables, shortcuts, firewall rules and custom actions.
  • diff: what a change does to the product: + added, - removed and ~ changed files, services, registry values and so on. The product code is not compared, because every build gets a new one. Handy in a pull request or to check that an upgrade does not drop something.
  • Windows only for MSI files: reading an MSI uses the Windows Installer API. new-guid works everywhere.
  • Not published as a dotnet tool yet: that needs a new package id on nuget.org first; until then run it from source as above.

Custom actions

Code that runs on the target machine during the install:

MsiBuilder.Create("My App")
    .OnAfterInstall(Setup.Configure, "MODE")           // elevated, after files are copied
    .OnBeforeInstall(Setup.CheckPrerequisites)         // not elevated, before anything changes
    .RunAfterInstall("MyApp.exe", "--init-db")         // run a program (elevated by default)
    .RunBeforeUninstall("MyApp.exe", "--unregister");  // real uninstall only, not upgrades

static class Setup
{
    public static void Configure(InstallEvent e)
    {
        if (e.IsInstalling) File.WriteAllText(e.InstallDir + "mode.txt", e["MODE"] ?? "client");
    }

    public static void CheckPrerequisites(InstallEvent e)
    {
        if (!Environment.Is64BitOperatingSystem) e.Cancel("64-bit Windows is required.");
    }
}
  • Static methods only: pass a static method (.OnAfterInstall(Setup.Configure)), which must be internal or public. Lambdas, local functions and instance methods are rejected at compile time (IK160–IK162).
  • Reading properties after install: in OnAfterInstall, only the properties you list (plus INSTALLDIR) can be read.
  • How they run: the InstallKit source generator, shipped with InstallKit.Abstractions, emits one [CustomAction] entry point per handler in your installer assembly. The engine registers each one as an ordinary custom action, and nothing is looked up by reflection at install time. The WixSharp engine embeds the entry points as managed code; WixSharpCore compiles them to native code.
  • Upgrade-safe: handlers receive the engine-neutral InstallEvent, never WixSharp types, so they keep working when the engine changes.
  • Advanced cases: use ConfigureWixSharp with WixSharp's own ManagedAction or ElevatedManagedAction.

System settings

Settings that change the machine besides copying files. They are removed again on uninstall.

Registry

MsiBuilder.Create("My App")
    .WithRegistryValue(RegistryHive.LocalMachine, @"Software\Contoso\My App", "InstallPath", "[INSTALLDIR]")
    .WithRegistryValue(RegistryHive.LocalMachine, @"Software\Contoso\My App", "Telemetry", 0)     // REG_DWORD
    .WithRegistryValue(RegistryHive.CurrentUser, @"Software\Contoso\My App", "LogDir", @"%LOCALAPPDATA%\My App\logs", RegistryValueKind.ExpandString)
    .WithRegistryValue(RegistryHive.LocalMachine, @"Software\Contoso\My App", null, "My App");    // the key's default value
  • Formatted text: string values can use MSI properties such as [INSTALLDIR].
  • Uninstall: Windows Installer removes the values with the files, and deletes a key it created once it is empty.
  • Checked before WiX runs: a key with a leading backslash fails with IK170, a DWord that is not a whole number with IK171, and an HKLM value in a per-user install with IK172.
  • Machine-wide or per user: use RegistryHive.LocalMachine for per-machine installs and RegistryHive.CurrentUser for per-user installs.

Environment variables and PATH

MsiBuilder.Create("My App")
    .WithPathEntry("[INSTALLDIR]bin")                      // adds the folder to PATH, removes only it on uninstall
    .WithPathEntry("[INSTALLDIR]tools", prepend: true)     // at the start of PATH instead
    .WithEnvironmentVariable("MYAPP_HOME", "[INSTALLDIR]");
  • Per machine or per user: a per-machine install changes the machine-wide variable, a per-user install the user's own.
  • Only your part is touched: appended and prepended values are added to the existing value, and only that part is removed again.
  • Already running programs: they keep the old environment. A new terminal or program sees the change.
  • Checked before WiX runs: setting PATH as a whole fails with IK182 (use WithPathEntry), a ; inside one entry with IK183.

File associations and URL protocols

MsiBuilder.Create("My App")
    .WithMainExecutable("MyApp.exe")
    .WithFileAssociation(".foo", "Foo document")                         // opens with MyApp.exe "%1"
    .WithFileAssociation(".bar", "Bar file", "tools/Viewer.exe")         // another program of the product
    .WithUrlProtocol("myapp", "My App link");                            // myapp://... starts MyApp.exe "myapp://..."
  • Program: defaults to MainExecutable; pass a path relative to the install directory to use another one. It must be in a payload (IK121), and one of the two must be given (IK192).
  • ProgId: defaults to the output file name plus the extension (MyApp.foo); the fourth argument of WithFileAssociation sets it.
  • What it writes: plain registry values under HKEY_CLASSES_ROOT (the extension's default value, the ProgId with an icon and an open command), so uninstall removes them like any other value.
  • Not forced on users: Windows 10 and 11 keep the user's own "Open with" choice for an extension; the association only registers your program as a candidate and the default for extensions nobody else claimed.
  • Checked before WiX runs: an invalid extension (IK190), scheme (IK191) or ProgId (IK194), and duplicates (IK193, IK195).

Firewall rules

MsiBuilder.Create("My App")
    .WithService("MyService.exe", "MyService")
    .WithFirewallRule("My App web", "8080")                                  // TCP port, any program
    .WithFirewallRule("My App ports", "8000-8100", FirewallProtocol.Udp)     // a range, or a list such as "80,443"
    .WithFirewallRule("My App", executable: "MyService.exe",                 // any port of one installed program,
        scope: FirewallScope.LocalSubnet, profile: FirewallProfile.Private); // only from the local subnet, on private networks
  • Inbound: the rule allows inbound connections and is removed on uninstall. Outbound rules are not supported yet.
  • Needs elevation: a per-user install cannot create firewall rules (IK214).
  • Checked before WiX runs: a rule needs a name (IK210) and a port or a program (IK211); ports must be 1 to 65535, a range or a list (IK212); a port needs TCP or UDP (IK213); the program must be in a payload (IK121).
  • WiX extension: the build adds the WiX firewall extension automatically when a rule is used; it is pinned to the same version as the wix tool like the other extensions.

Values in XML config files

MsiBuilder.Create("My App")
    .WithProperty("SERVER", "localhost")
    .WithXmlValue("MyApp.exe.config", "/configuration/appSettings/add[@key='Server']/@value", "[SERVER]");

Run msiexec /i MyApp.msi SERVER=prod.contoso.com and the installed file contains prod.contoso.com. This needs no custom action. To ask the user instead, see Asking for values.

  • File: relative to the install directory and part of a payload (IK121). The edit happens after the files are copied.
  • XPath: points at one element or attribute and is checked before WiX runs (IK221). InstallKit escapes the [ and ] of XPath predicates for you, because Windows Installer would otherwise read them as property references.
  • Value: MSI formatted text such as [SERVER] or [INSTALLDIR]logs.
  • XML only: a JSON file fails with IK222. JSON support is planned.

Closing running programs

MsiBuilder.Create("My App")
    .WithMainExecutable("MyApp.exe")
    .WithCloseApplication("MyApp.exe")                                      // asks it to close, then installs
    .WithCloseApplication("MyHelper.exe", terminate: true, timeoutSeconds: 10); // ends it if it does not close

A running program locks its files, so an upgrade or uninstall would otherwise ask for a restart or leave files behind. Windows Installer asks the program to close first. With terminate: true it ends a program that is still running after the timeout; unsaved work in it is lost, so use it for helpers and services, not for programs people edit documents in.

  • Process name: the executable's file name, such as MyApp.exe, without a path (IK230). It matches by name for every user on the machine.
  • When: during the install, before files are replaced or removed (so for upgrades and uninstalls too).
  • Silent installs: it works with /qn as well, which is the main use.
  • Checked before WiX runs: a name that is not a file name (IK230), duplicates (IK231) and a timeout outside 1 to 600 seconds (IK232).

Optional features

MsiBuilder.Create("My App")
    .WithPayload("MyApp")                                                      // always installed
    .WithFeature("Documentation", "Help files and the user guide")
    .WithFeature("Samples", "Example projects", installedByDefault: false)
    .WithDirectory(@"..\docs", "docs", feature: "Documentation")
    .WithDirectory(@"..\samples", "samples", feature: "Samples")
    .WithUi(InstallerUi.FeatureTree);                                          // lets users tick them
  • Always-installed files: everything without a feature argument.
  • Command line: msiexec /i MyApp.msi ADDLOCAL=Samples adds a feature and REMOVE=Documentation removes one. Spaces in a feature name become underscores (Sample_files).
  • Dialogs: the modern UIs (Modern, ModernInstallDir) show a feature page after the welcome page and a "ready to install" page after that; running the MSI again on an installed product offers Repair, Remove and Change, and Change opens the same feature page. InstallerUi.FeatureTree shows the classic tree. With another UI (Minimal, InstallDir, ProgressOnly, ModernWpf) the build prints warning IK246 and the defaults apply.
  • Must always be installed: the main executable, services, XML-edited files and the programs used by file associations and firewall rules cannot be in a feature (IK244).
  • Checked before WiX runs: an unusable name (IK240), duplicates (IK241), files for a feature that was never declared (IK242) and a feature with no files (IK243).

Folder permissions

MsiBuilder.Create("My App")
    .WithService("MyService.exe", "MyService", s => s.WithAccount(@"NT AUTHORITY\LocalService"))
    .WithFolderPermission(@"NT AUTHORITY\LocalService", FolderRights.Modify, "data")   // creates data\ if no payload has it
    .WithFolderPermission("Users", FolderRights.Read, "config")                         // a payload folder
    .WithFolderPermission("Authenticated Users", FolderRights.Modify);                  // the install folder itself
  • Accounts: a name such as Users, Everyone, Administrators or Authenticated Users, or DOMAIN\name such as NT AUTHORITY\LocalService or NT SERVICE\MyService.
  • Rights: Read (list, read, run), Modify (Windows' "Modify": also create, change and delete) and FullControl.
  • Folders: the install directory (no folder given), a folder of a payload (WithDirectory(dir, "config")), or any other relative path, which is created as an empty folder. Only that one folder is changed: never Program Files or the manufacturer folder above the install directory.
  • Not supported yet: a folder inside a payload folder (IK252), such as config\secrets when config holds files.
  • Checked before WiX runs: a missing account (IK250), a folder that is not below the install directory (IK251), and the same account twice for one folder (IK253).

Asking for values

MsiBuilder.Create("My App")
    .WithModernUi()
    .WithPromptedProperty("SERVER", "Server address", defaultValue: "localhost", required: true)
    .WithPromptedProperty("DB_NAME", "Database name", "myapp")
    .WithXmlValue("MyApp.exe.config", "/configuration/appSettings/add[@key='Server']/@value", "[SERVER]");

The modern UI shows a settings page after the welcome page with a labelled input box for each value (at most three). The default fills the box, a required value keeps Next or Install disabled while the box is empty, and the page is followed by the feature page when the product has optional features.

  • Silent installs and the command line: nothing is asked; SERVER=prod on the command line wins over the default, otherwise the default is used.
  • Where the value goes: it is an ordinary MSI property, so [SERVER] works in XML values and run commands, and an install event reads it with e["SERVER"] (list it in OnAfterInstall(handler, "SERVER")).
  • Property names: capital letters, digits and underscores (IK280); not one Windows Installer or InstallKit uses (IK284); not the same as a WithProperty (IK281). The label is required (IK282) and only three prompts fit on the page (IK283).
  • Other UIs: Minimal, InstallDir, FeatureTree and ModernWpf do not ask; the build prints warning IK285 and the defaults apply. Use the WPF custom dialogs there.
  • Not for secrets: the box shows what is typed and the value ends up in the install log. Use it for server names, regions, ports and the like.

UI and branding

Ui Dialogs
Minimal (default) Classic WiX: welcome/license, progress
InstallDir, FeatureTree, ProgressOnly Classic WiX variants
Modern Native, branded: one welcome page (license and accept box when set), progress, finish; repair/remove
ModernInstallDir Modern with the install folder and a Browse button on the welcome page
ModernWpf WPF dialogs, which allow custom XAML dialogs (WixSharp engine only)
MsiBuilder.Create("My App")
    .WithModernUi()                  // or WithModernUi(chooseInstallDir: true), or WithWpfUi()
    .WithAccentColor("#0067C0")
    .WithLogo("logo.png");
  • Branded images: InstallKit generates the banner (493×58) and dialog (493×312) bitmaps in your accent colour with your logo, so even the classic dialogs look current. You can supply your own .bmp files through the BannerImage and BackgroundImage settings of Branding. Bundles use the logo too.
  • Modern (native), with optional features: the feature page is WiX's own feature tree dialog (with its Reset and Disk Usage buttons) in the classic banner style, between the branded welcome page and the "ready to install" page. Add or Remove Programs offers Change for such a product.
  • Modern (native): the dialogs are built from MSI's own dialog tables, in Segoe UI on the branded background. The target machine needs nothing extra, and it works the same on both engines. The progress, error and repair/remove pages reuse WiX's dialogs, which pick up the same fonts and banner. Its texts are English for now.
  • ModernWpf: needs .NET Framework 4.8 on the target machine and adds about 1 MB to the MSI. The WixSharpCore engine falls back to Modern with warning IK200.
  • Silent installs (/qn) show no UI at all.

Your own dialog (ModernWpf): write a XAML UserControl that derives from WixSharp.UI.WPF.WpfDialog and implements IWpfDialog, and set <InstallKitUseWpf>true</InstallKitUseWpf> in the project. Then add it:

using InstallKit.WixSharp;
MsiBuilder.Create("My App")
    .WithWpfUi()
    .AddWpfDialog<ServerSettingsDialog>(after: ModernDialog.Welcome);

The dialog stores what the user enters in MSI properties, and your custom actions read them with e["SERVER"]. Custom dialogs are the one WixSharp-specific part of the UI, so keep them in a separate file.

Bundles

A bundle is a single setup .exe that installs its packages in chain order:

plan.Bundle(BundleBuilder.Create("My App")
    .WithUpgradeCode("5a2e7c41-9d83-4b6f-8e15-c3a09f4d2b77")
    .WithLogo("logo.png")
    .WithNetFramework(NetFrameworkVersion.NetFx48)
    .WithExe(@"prereqs\vc_redist.x64.exe", e => e.DetectCondition = "VCRedistInstalled") // a Burn variable you set with a search
    .WithMsi(app));
  • WithMsi(app) is an MSI from the same plan. It is always built before the bundle.
  • WithMsi("path.msi") is an existing MSI file.
  • WithNetFramework(...) installs .NET Framework from the web when it is missing.
  • WithExe(path, e => e.DetectCondition = ...) runs any other installer, such as the .NET runtime or VC++ redistributables. A detect condition is required so it is skipped when already installed.

The bundle has its own UpgradeCode, separate from its MSIs' codes.

Prerequisites

Helpers for the runtimes most apps need. Each adds the right silent arguments and a detect condition, so the runtime is only installed when the machine does not have it yet:

plan.Bundle(BundleBuilder.Create("My App")
    .WithUpgradeCode("5a2e7c41-9d83-4b6f-8e15-c3a09f4d2b77")
    .WithVcRedist(@"prereqs\vc_redist.x64.exe")                                              // embedded in the setup
    .WithDotNetRuntime(DotNetRuntimeKind.WindowsDesktop, 8, @"prereqs\windowsdesktop-runtime-8.0.11-win-x64.exe")
    .WithWebView2(PrerequisiteInstaller.FromDownload(                                           // downloaded when the setup runs
        "https://go.microsoft.com/fwlink/p/?LinkId=2124703", sha512: "<128 hex digits>", sizeInBytes: 1_800_000,
        fileName: "MicrosoftEdgeWebview2Setup.exe"))
    .WithMsi(app));
  • Two ways to supply the installer: a file you download once and keep in your repository (WithVcRedist("path.exe"), works offline), or PrerequisiteInstaller.FromDownload(url, sha512, sizeInBytes), which keeps the setup small. The setup refuses a download whose hash or size differs, so use the values of exactly what the URL serves and update them when Microsoft updates the file. Compute them with Get-FileHash -Algorithm SHA512 file.exe and (Get-Item file.exe).Length.
  • Detection: WithVcRedist looks for the Visual C++ 2015 to 2022 runtime of that architecture (Installed in the registry); WithDotNetRuntime(kind, major, installer) finds an installed runtime of that major version (Runtime, AspNetCore or WindowsDesktop); WithWebView2 checks the machine and the user registry. Where it applies they take an architecture argument (x64 by default).
  • One per kind: using the same helper twice for one runtime, version and architecture fails with IK264.
  • Checked before WiX runs: an embedded file that is missing (IK133); a download that is not https (IK260), has no valid SHA-512 hash (IK261), no size up to 2 GB (IK262) or an unusable file name (IK263); a .NET major version below 3 (IK265).

Signing

InstallKit leaves the signing tool to you; it only decides when files get signed:

  1. Each MSI is signed right after it is built, before any bundle embeds it.
  2. For a bundle, the Burn engine is detached and signed, then reattached (wix burn detach/reattach), and then the bundle itself is signed.

Signing a bundle .exe after the build would leave its engine and the MSIs inside it unsigned, which is why signing happens during the build. You can plug in your tool in either of two ways:

  • Command: set InstallKitSignCommand (or the INSTALLKIT_SIGN_COMMAND environment variable). It runs once per file, with {file} replaced by the quoted path: AzureSignTool sign -kvu https://my-vault.vault.azure.net -kvm -kvc my-cert -tr http://timestamp.digicert.com {file}
  • Code: plan.UseSigner(new MySigner()) with your own IFileSigner.

Azure DevOps

The templates are layered so you can use a whole stage or individual steps:

pipelines/
  steps/setup-tools.yml        UseDotNet + dotnet tool restore
  steps/build-installer.yml    dotnet build with version, output dir and sign command
  steps/smoke-test.yml         msiexec install + uninstall every MSI, publish the logs
  steps/publish-universal.yml  publish a folder to Azure Artifacts as a Universal Package
  jobs/build-installer.yml     Windows job: tools → preBuildSteps → build → postBuildSteps → smoke test → artifact
  stages/installer.yml         Build stage + Publish stage (skipped for pull requests)
resources:
  repositories:
    - repository: installkit
      type: github
      name: lucavoit/InstallKit
      endpoint: github
      ref: refs/tags/installkit-v0.1.0

stages:
  - template: pipelines/stages/installer.yml@installkit
    parameters:
      setupProject: src/MyApp.Installer/MyApp.Installer.csproj
      version: 1.2.$(Build.BuildId)
      feed: MyProject/installers      # Azure Artifacts feed
      packageName: my-app
      preBuildSteps:                  # optional: your signing setup
        - task: AzureCLI@2
          inputs: { ... }
      signCommand: AzureSignTool sign ... {file}

Download a published installer with az artifacts universal download --feed installers --name my-app --version 1.2.345 --path ..

These templates are for your own pipelines. InstallKit itself is built with GitHub Actions; see Contributing.

What target machines need

The installer project only runs on your build machine. A target machine needs:

Installer uses Target machine needs
Plain MSI (classic UI, services, shortcuts, run commands) Nothing beyond Windows: Windows Installer is built in
Modern UI (native) Nothing
Install events (OnAfterInstall, ...), WixSharp engine .NET Framework 4.8 (included in Windows 10 1903+, Windows 11 and Windows Server 2022+; install it on older systems)
Install events, WixSharpCore engine Nothing: they are compiled to native code
ModernWpf UI .NET Framework 4.8
Bundle (setup .exe) Nothing: the bundle engine and its standard UI are native code
Your application itself Whatever it needs. Publish it self-contained (SelfContained=true, as in the sample) or chain its runtime into a bundle
  • No InstallKit or WixSharp at install time: neither is installed on the target machine. Custom-action code is embedded in the MSI and runs during installation only.

Engines

An installer project uses one engine, chosen with a single property. Your installer code stays the same either way:

<PropertyGroup>
  <InstallKitEngine>WixSharpCore</InstallKitEngine>  
</PropertyGroup>
WixSharp (default) WixSharpCore (preview)
Package InstallKit.WixSharp → WixSharp_wix4 InstallKit.WixSharp.Core → WixSharp.Core
Installer project targets .NET Framework 4.8 .NET 10 (net10.0-windows); WixSharp.Core itself ships for .NET 8 and runs on 10
MSIs, services, shortcuts, run commands, branding, bundles, signing ✓ ✓
Install events (OnAfterInstall, ...) ✓ (managed custom actions) ✓ (compiled to native code; the build machine needs the C++ build tools)
Modern UI (native) ✓ ✓
ModernWpf, custom WPF dialogs ✓ not yet: falls back to Modern (IK200)

Build agent requirements: either engine needs only Windows and the .NET SDK. The SDK pulls in just the engine package you chose, so the other engine is never restored or built. The .NET Framework 4.8 reference assemblies come from NuGet, so the WixSharp engine needs no targeting pack. The pipeline templates are the same for both.

Code shared by both:

  • One engine source: InstallKit.WixSharp.Core compiles the same engine source as InstallKit.WixSharp, with INSTALLKIT_CORE defined, so the two engines can't drift apart.
  • Same names: both use the same namespace and type names, so using InstallKit.WixSharp; and ConfigureWixSharp work with either. WixSharp.Core mirrors WixSharp's API, so most raw WixSharp code carries over too.
  • Adapting your installer code: the SDK defines INSTALLKIT_ENGINE_WIXSHARP or INSTALLKIT_ENGINE_WIXSHARPCORE. The sample uses this to register its install event only on the .NET Framework engine.

Core engine notes:

  • Native compilation: WixSharp.Core compiles the installer assembly's custom actions to a native DLL with NativeAOT. That needs the C++ build tools ("Desktop development with C++") on the build machine, which Microsoft-hosted Windows agents have. It also adds roughly 10–60 seconds per build.
  • Remaining gap: the WPF dialogs. WixSharp.Core needs them in a separate .NET Framework UI project; the native Modern UI covers the default look without it.

samples/HelloService.Installer.Core builds the same sample with the Core engine. CI builds both.

WiX version and licence

InstallKit uses whichever wix version is pinned in .config/dotnet-tools.json; the default is 6.0.2, the version WixSharp recommends. WiX extensions are pinned to the same version automatically.

WiX Licence of the official binaries Fee Acceptance
5.0.2 and older MS-RL (open source) None Not needed
6.0.x MS-RL source + Open Source Maintenance Fee EULA Owed by users who generate revenue with WiX Not enforced by the build
7.x MS-RL source + OSMF EULA Owed by revenue-generating users with ≥ US$10,000 annual gross revenue Required: the build fails with IK004 until you set InstallKitAcceptWixEula

In every version the source code stays MS-RL. The fee applies only to the official binaries, and binaries you build from source yourself are not covered by it. This summarises the EULA files shipped in the wix NuGet packages; it is not legal advice.

Changing the WiX version

Run this in the folder that contains .config/:

dotnet tool update wix --version 5.0.2 --allow-downgrade   # or 6.0.2 / 7.0.1

That is the only change needed: local builds and the pipeline templates both run dotnet tool restore. For WiX 7 or later, also accept its EULA in the installer project:

<PropertyGroup>
  <InstallKitAcceptWixEula>wix7</InstallKitAcceptWixEula>
</PropertyGroup>

Only WiX 6 and 7 are confirmed to work with WixSharp 2.14.2; test 5.0.2 before you rely on it.

Contributing

Issues and pull requests are welcome. Please open an issue first for larger changes. CI runs on every pull request and push to main: unit tests, packing, both sample installers and the end-to-end QA. Run the unit tests locally with:

dotnet test tests/InstallKit.Abstractions.Tests -c Release    # model, builders, validation, analyzers
dotnet test tests/InstallKit.WixSharp.Tests -c Release        # the modern dialogs' XML
dotnet test tests/InstallKit.WixSharp.Engine.Tests -c Release # the engine: the WiX source it writes for a model
dotnet test tests/InstallKit.Tool.Tests -c Release            # the installkit tool

The engine tests compile the engine source into a test project and read the WiX source that comes out, so they need neither Windows nor WiX. They guard what used to be found only by the Windows CI run.

QA

The qa jobs in .github/workflows/ci.yml build the QA demo installer as 1.0.0 and 1.1.0 with each engine, then run qa/tests/Installer.Tests.ps1 on a GitHub-hosted Windows runner. It checks:

  • Install: the Add/Remove Programs entry, payload and extra files, Start menu and desktop shortcuts, the running service, the OnAfterInstall handler and RunAfterInstall command, and a property passed on the command line.
  • Upgrade: 1.1.0 replaces 1.0.0, and RunBeforeUninstall does not run.
  • Repair: a deleted file is restored.
  • Uninstall: RunBeforeUninstall runs, and the service, files, shortcuts and Add/Remove Programs entry are removed.
  • Bundle: QaDemoSetup.exe installs and uninstalls the same product.

A separate consumer job checks the route a user without a monorepo takes. qa/consumer/Build-Consumer.ps1 creates an installer project outside this repository from the packed NuGet packages and the dotnet new installkit template, points it at a folder of prebuilt files, and builds an MSI and a bundle. qa/tests/Consumer.Tests.ps1 then installs and removes it. This is the test that proves the packages work without this repository.

The tests change the machine, so only run them on a disposable one. Locally, from an elevated PowerShell:

dotnet build qa/QaDemo.Installer -c Release -p:InstallKitVersion=1.0.0 -p:InstallKitOutputDir=$PWD/out/1.0.0/
dotnet build qa/QaDemo.Installer -c Release -p:InstallKitVersion=1.1.0 -p:InstallKitOutputDir=$PWD/out/1.1.0/
./qa/tests/Invoke-Qa.ps1 -V1 out/1.0.0 -V2 out/1.1.0

Roadmap

See ROADMAP.md for what is planned now, later and in the future, and what is not planned.

License

InstallKit is released under the MIT License. WixSharp and the WiX Toolset have their own licences; see WiX version and licence.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0-rc.2 47 11/17/2026
1.0.0-rc.1 59 11/15/2026
0.1.0-preview.1 60 11/14/2026