InstallKit.WixSharp
1.0.0-rc.1
See the version list below for details.
dotnet add package InstallKit.WixSharp --version 1.0.0-rc.1
NuGet\Install-Package InstallKit.WixSharp -Version 1.0.0-rc.1
<PackageReference Include="InstallKit.WixSharp" Version="1.0.0-rc.1" />
<PackageVersion Include="InstallKit.WixSharp" Version="1.0.0-rc.1" />
<PackageReference Include="InstallKit.WixSharp" />
paket add InstallKit.WixSharp --version 1.0.0-rc.1
#r "nuget: InstallKit.WixSharp, 1.0.0-rc.1"
#:package InstallKit.WixSharp@1.0.0-rc.1
#addin nuget:?package=InstallKit.WixSharp&version=1.0.0-rc.1&prerelease
#tool nuget:?package=InstallKit.WixSharp&version=1.0.0-rc.1&prerelease
InstallKit
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 buildpublishes your app, then produces the MSI and, optionally, a singlesetup.exebundle. - 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)andWithoutX()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 asWithPayload,WithService,WithProperty, the shortcut toggles, the custom actions, and the bundle chain methods. - Start from
Create(...): a barenew MsiBuilder()has no defaults and would reset them (for exampleUior 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 withIK110. - Mix and match: call
WithDirectoryseveral times, optionally with a target subfolder (.WithDirectory(docsDir, "docs")), and combine it withWithPayload. - Existing installers in a bundle:
WithMsi("path.msi")chains an MSI that was built elsewhere, andWithExe(path, ...)chains any other setup program. - Your pipeline: the build only needs a Windows agent, the .NET SDK and the pinned
wixtool (dotnet tool restore). The Azure DevOps templates inpipelines/are optional.
How it works
dotnet buildcompiles the installer project as a small .NET Framework console app.- The SDK runs
dotnet tool restoreso thewixversion in.config/dotnet-tools.jsonis used. WiX extensions are pinned to that same version, so newer extensions on NuGet can't silently break the build. - Each
<InstallerPayload>project is published intoobj/installkit/payload/<Name>/, starting from an empty folder each time. - The SDK runs the program.
InstallerHostvalidates the plan before WiX runs, then builds every MSI, then every bundle. - The built files end up in
@(InstallerOutput), and the generated.wxsis kept inobj/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
.exeprerequisite without aDetectCondition. - A version that doesn't fit MSI's
255.255.65535limit.
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 nameMyService 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:Versionof the build.
Things to know:
- A custom
InstallDirectorymust contain the line (IK270), otherwise the versions share a folder. - Bundles: a bundle that chains a side-by-side MSI needs the same
SideBySidemode (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
IK273when 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
Nonefor 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-guidworks 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 beinternalorpublic. Lambdas, local functions and instance methods are rejected at compile time (IK160–IK162). - Reading properties after install: in
OnAfterInstall, only the properties you list (plusINSTALLDIR) 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. TheWixSharpengine embeds the entry points as managed code;WixSharpCorecompiles 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
ConfigureWixSharpwith WixSharp's ownManagedActionorElevatedManagedAction.
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 withIK171, and an HKLM value in a per-user install withIK172. - Machine-wide or per user: use
RegistryHive.LocalMachinefor per-machine installs andRegistryHive.CurrentUserfor 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
PATHas a whole fails withIK182(useWithPathEntry), a;inside one entry withIK183.
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 ofWithFileAssociationsets it. - What it writes: plain registry values under
HKEY_CLASSES_ROOT(the extension's default value, the ProgId with an icon and anopencommand), 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
wixtool 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
/qnas 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
featureargument. - Command line:
msiexec /i MyApp.msi ADDLOCAL=Samplesadds a feature andREMOVE=Documentationremoves 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.FeatureTreeshows the classic tree. With another UI (Minimal,InstallDir,ProgressOnly,ModernWpf) the build prints warningIK246and 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,AdministratorsorAuthenticated Users, orDOMAIN\namesuch asNT AUTHORITY\LocalServiceorNT SERVICE\MyService. - Rights:
Read(list, read, run),Modify(Windows' "Modify": also create, change and delete) andFullControl. - 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 asconfig\secretswhenconfigholds 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=prodon 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 withe["SERVER"](list it inOnAfterInstall(handler, "SERVER")). - Property names: capital letters, digits and underscores (
IK280); not one Windows Installer or InstallKit uses (IK284); not the same as aWithProperty(IK281). The label is required (IK282) and only three prompts fit on the page (IK283). - Other UIs:
Minimal,InstallDir,FeatureTreeandModernWpfdo not ask; the build prints warningIK285and 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
.bmpfiles through theBannerImageandBackgroundImagesettings ofBranding. 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
WixSharpCoreengine falls back toModernwith warningIK200. - 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), orPrerequisiteInstaller.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 withGet-FileHash -Algorithm SHA512 file.exeand(Get-Item file.exe).Length. - Detection:
WithVcRedistlooks for the Visual C++ 2015 to 2022 runtime of that architecture (Installedin the registry);WithDotNetRuntime(kind, major, installer)finds an installed runtime of that major version (Runtime,AspNetCoreorWindowsDesktop);WithWebView2checks the machine and the user registry. Where it applies they take anarchitectureargument (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:
- Each MSI is signed right after it is built, before any bundle embeds it.
- 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 theINSTALLKIT_SIGN_COMMANDenvironment 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 ownIFileSigner.
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.Corecompiles the same engine source asInstallKit.WixSharp, withINSTALLKIT_COREdefined, so the two engines can't drift apart. - Same names: both use the same namespace and type names, so
using InstallKit.WixSharp;andConfigureWixSharpwork 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_WIXSHARPorINSTALLKIT_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
ModernUI 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
OnAfterInstallhandler andRunAfterInstallcommand, and a property passed on the command line. - Upgrade: 1.1.0 replaces 1.0.0, and
RunBeforeUninstalldoes not run. - Repair: a deleted file is restored.
- Uninstall:
RunBeforeUninstallruns, and the service, files, shortcuts and Add/Remove Programs entry are removed. - Bundle:
QaDemoSetup.exeinstalls 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.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET Framework | net48 is compatible. net481 was computed. |
-
.NETFramework 4.8
- InstallKit.Abstractions (>= 1.0.0-rc.1)
- WixSharp_wix4 (>= 2.14.2)
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 | 46 | 11/17/2026 |
| 1.0.0-rc.1 | 81 | 11/15/2026 |
| 0.1.0-preview.1 | 109 | 11/14/2026 |