1. CLI Compiler (winstaller)

The CLI build tool is used to compile setup packages from the command line or CI/CD pipelines.

Command Syntax

winstaller <config.json> [output-directory] [-target=<windows|console|both>] [-min-logs=<level>]

2. Generated Installer Switches (Setup.exe)

The generated setup executable (.exe) accepts command-line flags for silent installation and deployment customization.

Execution Syntax

Setup.exe [-silent] [-lang=<code>] [-min-logs=<level>]

Application Version and Semantic Versioning (version field)

The version field is validated according to the Semantic Versioning (SemVer) specification. The version must consist of three primary numeric segments: MAJOR.MINOR.PATCH (e.g. 1.0.0), optionally with pre-release tags (e.g. 1.2.3-beta.1) or build metadata following a plus sign (e.g. 1.0.0+build.2026). An optional v prefix is also accepted (e.g. v1.2.3).

"version": "1.2.3"

Examples of valid version strings: 1.0.0, 2.1.0-rc.1, 0.9.5-alpha+sha.5114f85.

Target Environment Selection (target field)

Winstaller supports building both graphical (WPF) and console-based (CUI) installers. The target field determines which executable flavor is produced:

"target": "both"

1. Installation Object

The `installation` object specifies the default target path for the application files:

"installation": {
  "type": "local",
  "dir": "MyApplication"
}

2. Shortcut Object

Configure shortcuts on the Desktop and/or Start Menu:

"shortcut": {
  "desktop": {
    "name": "Desktop Shortcut",
    "destination": "%installation%\\app.exe"
  },
  "menu": {
    "name": "Start Menu Shortcut",
    "destination": "%installation%\\app.exe"
  }
}

3. Content Array Items

Specify files or folders. Winstaller packages them into an embedded ZIP and extracts them on the client machine:

"content": [
  { "type": "file", "source": "app.exe", "destination": "%installation%\\app.exe" },
  { "type": "dir", "source": "data", "destination": "%installation%\\data" }
]

4. Install & Uninstall Steps

Available built-in step types:

welcome (Welcome screen), installtype (Destination folder select), license (License agreement), confirmuninstall (uninstall confirmation), install (Runs file copying & registry writes), success (Final success screen).

"install": [
  { "type": "welcome" },
  { "type": "license" },
  { "type": "installtype" },
  { "type": "install" },
  { "type": "success" }
]

5. Code Signing Object

Winstaller CLI has built-in code signing support, using standard Cryptui.dll system libraries. No external tools like signtool.exe are required:

"signing": {
  "certificatePath": "winstaller-test.pfx",
  "certificatePassword": "%MY_PFX_PASSWORD%",
  "timestampUrl": "http://timestamp.digicert.com"
}

6. Service Object

Installs and runs the application as a native Windows Service (requires runAsAdmin set to true):

"service": {
  "name": "MyService",
  "start": "auto",
  "runAfterInstallation": true,
  "forceStop": true,
  "path": "%installation%\\myservice.exe"
}

7. Plugins and Scripts

You can extend Winstaller with custom UI steps (implementing IStep) or background scripts (pre/post install implementing IScript) using C# library plugins:

"plugins": [
  "libs/MyCustomPlugins.dll"
],
"scripts": {
  "preInstall": [ "my-custom-pre-install-script" ],
  "postInstall": [ "my-custom-post-install-script" ]
}

8. Appearance Object

Configures the visual layout and UI window options:

"appearance": {
  "showNavigation": true,
  "width": 760,
  "height": 520
}

9. Resources Object & License Configuration (RTF / TXT)

The `resources` object specifies paths to external asset files required by installer steps, primarily License Agreement documents in RTF (Rich Text Format) or plain text format. Below is an example configuration:

"resources": {
  "license": "licenses/license_en.rtf",
  "license_pl": "licenses/license_pl.rtf",
  "license_de": "licenses/license_de.rtf"
},
"install": [
  { "type": "welcome" },
  { "type": "license" },
  { "type": "install" },
  { "type": "success" }
]

How License Loading Works

When the `{ "type": "license" }` step is present in the `install` array, Winstaller executes the following logic:

• Step Activation: Adding { "type": "license" } to the install array enables the License Agreement step in the wizard.
• Language Matching (i18n): The installer detects the active UI language (from Windows OS or -lang= flag) and searches resources for a matching key (e.g. license_pl). If not found, it falls back to resources.license.
• RTF & Text Rendering: Content is loaded into a WPF RichText FlowDocument. Full RTF formatting (bold text, colors, headers, lists) is rendered automatically. For plain text files (.txt) or malformed RTF, Winstaller gracefully falls back to UTF-8 text.
• GUI & Silent Behavior: The Next button remains disabled until the acceptance checkbox is checked. In silent mode (-silent flag), the license step is automatically accepted and bypassed in the background.

10. Update Object (Preserving Files During Updates)

The update section specifies files and directories to preserve from the previous installation when updating an application. The preserve node accepts an array of relative paths or wildcard patterns (e.g. *.db) relative to the installation directory:

"update": {
  "preserve": [
    "logs",
    "appsettings.json",
    "data",
    "*.db"
  ]
}

Handling File Collisions (Overwriting)

When a file specified in preserve exists in both the newly installed package and the existing user installation (e.g. user-customized appsettings.json):

1. Swap mode: The user's file from the previous version has priority and is restored to its original path (appsettings.json), directly overwriting the default file provided in the new package.
2. Overwrite mode: The installer checks if the target file already exists on disk. If so, it does not overwrite it (skips extraction).
3. Runtime-generated files: Files created at runtime (e.g. SQLite databases, logs directory) that are not present in the new package remain intact in both modes.

Pattern Matching Rules (.gitignore / glob standard)

The preserve node follows standard .gitignore pattern matching semantics:

• No slash (e.g. *.db, appsettings.json, logs): Matches files or directories at any nesting depth — in the root directory and across all subdirectories.
• Leading slash (e.g. /*.db, /logs): Anchors the pattern strictly to the root installation directory (subdirectories are ignored).
• Path with middle slash (e.g. data/*.db): Matches files directly in the specified subdirectory.
• Double asterisk (e.g. data/**/*.db): Recursively matches files across all subdirectories of the specified directory.
• Trailing slash (e.g. logs/): Restricts the pattern to match directories only.

1. Two Update Modes: Swap vs Overwrite

Winstaller provides two distinct update strategies configured via update.mode:

Swap Mode (default – "mode": "swap"):
Designed for standard desktop applications and Windows Services. The new version is extracted and staged entirely in an isolated temporary directory (%installation%_temp). Once prepared, an atomic directory rename (Directory Swap) moves the existing installation to %installation%_backup and activates the new version. If any error occurs, an automatic full rollback restores the previous version. Preserved files are moved from backup into the new installation, directly overwriting target files.

Overwrite Mode ("mode": "overwrite"):
Engineered specifically for games and large applications (e.g. 50–100 GB+), where duplicating directory structures into a temp directory and holding a full backup would require excessive disk space. In this mode, files are directly extracted and copied into the installation directory without creating a full backup and without rollback. If an incoming package file matches a rule in preserve and already exists on disk, it is not overwritten (it is skipped). All other files are updated, and existing runtime files (e.g. game saves, local logs) stay intact.

2. Where Should Applications Store State? (Windows Best Practices)

According to Microsoft guidelines and the Windows User Account Control (UAC) security model, the application installation directory (e.g. C:\Program Files\YourApp) should strictly host immutable executables and static assets. Standard users lack write permissions to this directory. Dynamic data generated at runtime must reside in dedicated Windows standard locations:

3. Warning: Risk of Data Loss in the Installation Folder

4. Solution: The update.preserve Mechanism & .gitignore Patterns

To ensure complete data and configuration safety for such applications, Winstaller provides the update.preserve configuration. Prior to deleting the backup directory, the installer scans previous files and automatically migrates the configured resources into the new installation.

Paths and wildcards in preserve follow standard .gitignore / glob semantics:

• No slash (e.g. *.db, appsettings.json, logs): Matches files or directories at any nesting depth — in the root directory and across all subdirectories.
• Leading slash (e.g. /*.db, /logs): Anchors the pattern strictly to the root installation directory (subdirectories are ignored).
• Middle slash (e.g. data/*.db): Matches files directly in the specified relative path.
• Double asterisk (e.g. data/**/*.db): Recursively matches files across all subdirectories of the specified directory.
• Trailing slash (e.g. logs/): Restricts matching strictly to directories.

"update": {
  "mode": "swap",
  "preserve": [
    "logs/",
    "appsettings.json",
    "*.db",
    "data/**/*.dat"
  ]
}

5. Handling File Collisions Across Modes

When a file specified in preserve exists in both the user's previous installation and the new package (e.g. appsettings.json):

• In swap mode: The user's preserved file from the previous installation has priority and overwrites the new package file. The application launches immediately with existing settings and database state intact.
• In overwrite mode: The installer checks whether the file already exists on disk. If so, it does not overwrite it (skips extracting/copying that file), leaving the user's file completely untouched.

1. Overview & Role of Winstaller.Interfaces

Winstaller provides a clear separation of concerns between the core setup engine and the user interface. The Winstaller.Interfaces library delivers a complete set of abstractions so you can focus solely on designing custom screens and application logic.

2. Prerequisites

To build custom wizard steps, your project must meet two requirements:

• Framework Version: C# library project must target .NET Framework 4.7.2 or higher (matching installer runtime environment).
• Library Reference: Add NuGet package or reference to Winstaller.Interfaces (providing access to IStep, StepViewBase, IView, InstallerContext, and PluginNameAttribute).

3. IStep Architecture & Step Lifecycle

The IStep interface represents a single step in the setup sequence. It separates wizard state management from WPF UI rendering and supports headless silent mode execution.

4. Rendering Windows & Building Custom Views (StepViewBase)

The Winstaller engine manages the main window frame (MainWindow), window headers, fluent themes, and bottom button bar (Next, Back, Cancel). Your custom view is injected into the central container.

In the Start(IView? view) method, you call view.SetStepView(() => new MyStepView(this)). It takes a factory returning a control inheriting from StepViewBase (a WPF UserControl).

5. Step-by-Step Implementation Guide

1. Create C# Class Library (.NET Framework 4.7.2 or higher): Add NuGet package Winstaller.Interfaces (or reference to Winstaller.Interfaces) and WPF assemblies (PresentationFramework, PresentationCore, WindowsBase).
2. Create XAML View (UserControl): Modify the XAML file so that the base class is interfaces:StepViewBase instead of standard UserControl. Design the user interface (textboxes, images, checkboxes).
3. Write View Code-Behind (C#): Pass the IStep instance in the view constructor. Handle field validation and set IsNextEnabled to true or false.
4. Implement Step Class (IStep): Decorate the class with [PluginName("YourStepName")] attribute. In the Start method, create and pass your view via view.SetStepView(...).
5. Build & Register in config.json: Compile the DLL library, place it in the installer directory, and register it in config.json under "plugins" and "install" sections.

6. Complete Working Code Example (C# & XAML)

XAML View (MyWelcomeView.xaml)

<interfaces:StepViewBase x:Class="Winstaller.CustomSteps.MyWelcomeView"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:interfaces="clr-namespace:Winstaller.Interfaces;assembly=Winstaller.Interfaces">
    <Grid Margin="20">
        <StackPanel>
            <TextBlock Text="Welcome to the application installer!" FontSize="20" FontWeight="Bold" Margin="0,0,0,10"/>
            <TextBlock Text="Enter the activation code to unlock the Next button:" Margin="0,0,0,5"/>
            <TextBox x:Name="txtLicenseKey" Padding="8" TextChanged="TxtLicenseKey_TextChanged"/>
        </StackPanel>
    </Grid>
</interfaces:StepViewBase>

View Code-Behind (MyWelcomeView.xaml.cs)

using System.Windows.Controls;
using Winstaller.Interfaces;

namespace Winstaller.CustomSteps
{
    public partial class MyWelcomeView : StepViewBase
    {
        public MyWelcomeView(IStep step)
        {
            InitializeComponent();
            Step = step;
            Title = "Introduction";
            Header = "Custom Welcome Screen";
            IsNextEnabled = false; // Disabled Next button by default
        }

        private void TxtLicenseKey_TextChanged(object sender, TextChangedEventArgs e)
        {
            // Enable Next button only when at least 5 characters are entered
            IsNextEnabled = txtLicenseKey.Text.Trim().Length >= 5;
        }
    }
}

C# Step Class (MyWelcome.cs)

using System;
using System.Threading.Tasks;
using Winstaller.Interfaces;

namespace Winstaller.CustomSteps
{
    [PluginName("MyWelcome")]
    public class MyWelcome : IStep
    {
        private MyWelcomeView? _view;
        private StepConfig? _config;

        public InstallerContext Context { get; set; } = null!;
        public int CurrentStep { get; set; }
        public int TotalSteps { get; set; }

        public event EventHandler? Next;
        public event EventHandler? Back;
        public event EventHandler? Canceled;

        public void Initialize(StepConfig config)
        {
            _config = config;
        }

        public void Start(IView? view)
        {
            if (Context.IsSilent)
            {
                // In silent mode, proceed immediately without creating GUI
                Next?.Invoke(this, EventArgs.Empty);
                return;
            }

            view?.SetStepView(() =>
            {
                _view = new MyWelcomeView(this);
                return _view;
            });
        }

        public void End() => _view = null;
        public void RaiseNext() => Next?.Invoke(this, EventArgs.Empty);
        public void RaiseBack() => Back?.Invoke(this, EventArgs.Empty);
        public void RaiseCanceled() => Canceled?.Invoke(this, EventArgs.Empty);
        public Task RollbackAsync() => Task.CompletedTask;
    }
}

Configuration in config.json

{
  "name": "Application with Custom Steps",
  "plugins": [
    "plugins/Winstaller.CustomSteps.dll"
  ],
  "install": [
    { "type": "MyWelcome" },
    { "type": "install" },
    { "type": "success" }
  ]
}

7. How to Translate the Step Code Name in the Sidebar Navigation

By default, the sidebar navigation displays the step's plugin code name (e.g. defined in [PluginName("MyWelcome")] or the "install" array). To replace this raw identifier with a localized display label (e.g. showing "Powitanie" for PL and "Introduction" for EN instead of "MyWelcome"), you can use two approaches:

Method 1: Register Key in "translations" Section (Recommended)

Winstaller treats the step plugin type name as a translation resource key. Simply add the step code name as a key in the "translations" block of your config.json file for each target language:

{
  "plugins": [ "plugins/Winstaller.CustomSteps.dll" ],
  "install": [
    { "type": "MyWelcome" }
  ],
  "translations": {
    "pl": {
      "MyWelcome": "Powitanie"
    },
    "en": {
      "MyWelcome": "Introduction"
    },
    "de": {
      "MyWelcome": "Einführung"
    }
  }
}

Method 2: Dynamically in C# View Code (Title Property)

You can also set the title dynamically in the constructor of your StepViewBase class, using LocalizationManager.GetString("MyWelcome") from the Winstaller.Interfaces package:

public MyWelcomeView(IStep step)
{
    InitializeComponent();
    Step = step;
    
    // Set dynamic title displayed on sidebar and window title bar
    Title = LocalizationManager.GetString("MyWelcome");
    Header = LocalizationManager.GetString("MyWelcome_Header");
}

8. Accessing Packaged Assets & Binaries (IResourceProvider)

All assets defined in the `resources` block of `config.json` (such as PNG/JPG images, license RTF/TXT documents, or custom binary files) are packaged inside the installer executable. Custom steps (`IStep`) and background scripts (`IScript`) can retrieve these assets at runtime via the `IResourceProvider` service obtained from `Context.GetService()`.

Available IResourceProvider Methods

Example 1: Loading a Packaged PNG Image into a WPF Image Control

using System.IO;
using System.Windows.Media.Imaging;
using Winstaller.Interfaces;

var resourceProvider = Context.GetService<IResourceProvider>();
if (resourceProvider != null && resourceProvider.HasResource("logo"))
{
    byte[] imageBytes = resourceProvider.GetResourceBytes("logo");
    using (var ms = new MemoryStream(imageBytes))
    {
        var bitmap = new BitmapImage();
        bitmap.BeginInit();
        bitmap.CacheOption = BitmapCacheOption.OnLoad;
        bitmap.StreamSource = ms;
        bitmap.EndInit();

        myLogoImage.Source = bitmap;
    }
}

Example 2: Reading a License Document or Text String

var resourceProvider = Context.GetService<IResourceProvider>();
if (resourceProvider != null && resourceProvider.HasResource("license_pl"))
{
    // Direct string reading
    string licenseText = resourceProvider.GetResourceString("license_pl");

    // Stream reading for WPF RichTextBox FlowDocument
    using (var stream = resourceProvider.GetResourceStream("license_pl"))
    {
        var range = new TextRange(myRichTextBox.Document.ContentStart, myRichTextBox.Document.ContentEnd);
        range.Load(stream, DataFormats.Rtf);
    }
}

Built-in Supported Languages

The Winstaller engine includes built-in translations for 10 languages: en (English), pl (Polish), de (German), fr (French), es (Spanish), it (Italian), pt (Portuguese), zh (Chinese), ja (Japanese), and ru (Russian). You can restrict available languages using the allowedLanguages array in config.json.

Adding Custom Languages & Key Overrides

{
  "allowedLanguages": ["en", "es"],
  "translations": {
    "en": {
      "Button_Next": "[EN]Next",
      "WelcomeStep_Title": "Setup Wizard - My Application"
    },
    "es": {
      "Button_Next": "[ES]Siguiente",
      "WelcomeStep_Title": "Asistente de instalación - Mi Aplicación"
    }
  }
}

Built-in Translation Keys Reference