Winstaller.Interfaces 1.0.1

Winstaller.Interfaces

The official SDK containing interfaces, base classes, and support models for extending the Winstaller installation engine.

This package provides the core contracts required to build custom wizard steps (GUI/WPF), lifecycle hook scripts (pre-install/post-install), and background operations.

Target Framework

• .NET Framework 4.5 (optimized for maximum compatibility with client machines)
• Uses WPF (UseWPF enabled) for UI-bound steps

Installation

Add the package to your plugin project using the .NET CLI:

dotnet add package Winstaller.Interfaces

Key Concepts & Components

1. IStep

Represents a logical installation wizard step. It manages the lifecycle of the step (initialization, execution start/end, rollback) and handles navigation events.

namespace Rollouta.Winstaller.Interfaces
{
    public interface IStep
    {
        InstallerContext Context { get; set; }
        int CurrentStep { get; set; }
        int TotalSteps { get; set; }

        event EventHandler Canceled;
        event EventHandler Next;
        event EventHandler Back;

        void Initialize(StepConfig config);
        void Start(IView? view);
        void End();
        Task RollbackAsync();
    }
}

2. IStepView & StepViewBase

Defines the visual interface for a step. Custom steps with user interfaces should inherit from StepViewBase (which inherits from WPF's UserControl and implements IStepView). It provides binding properties for controlling navigation button states in the wizard frame.

• Title & Header — Window title and internal header text.
• IsNextEnabled, IsNextVisible — Controls the Next button.
• IsBackEnabled, IsBackVisible — Controls the Back button.
• IsCancelEnabled, IsCancelVisible — Controls the Cancel button.
• IsFinishEnabled, IsFinishVisible — Controls the Finish button.

3. IScript

Represents a lightweight script executed at specific hooks (e.g. PreInstall or PostInstall). Scripts run headless, receive the InstallerContext, and are ideal for file preparation, running processes, or cleaning up.

namespace Rollouta.Winstaller.Interfaces
{
    public interface IScript
    {
        void Execute(InstallerContext installerContext);
    }
}

4. IBackgroundRunnableStep

Designed for steps that must run in the background (such as during UAC elevation or long-running processing tasks) where progress reporting and exception propagation are required.

namespace Rollouta.Winstaller.Interfaces
{
    public interface IBackgroundRunnableStep
    {
        Task ExecuteAsync(IProgress<InstallationProgress>? progress);
    }
}

5. InstallerContext

A shared state container passed to all steps and scripts. It holds variables like:

• AppName, AppVersion, Publisher
• InstallationPath, WorkingInstallationPath, BackupInstallationPath
• IsSilent — true if running in headless/silent command-line mode.
• Data — A Dictionary<string, string> for sharing custom properties and state between steps.
• GetService<T>() — Resolve services registered in the engine (e.g. logging, file operations, configuration).

Examples

1. Creating a Custom Wizard Step

To expose your custom step or script to Winstaller, tag the class with the [PluginName("YourPluginName")] attribute.

Code-behind (MyCustomStep.cs):

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

namespace MyCompany.Winstaller.Plugins
{
    [PluginName("MyCustomStep")]
    public class MyCustomStep : IStep
    {
        private MyCustomStepView? _view;

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

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

        public void Initialize(StepConfig config)
        {
            // Read custom settings defined in installer configuration
            if (config.Properties.TryGetValue("DefaultPort", out var port))
            {
                // Process custom properties
            }
        }

        public void Start(IView? view)
        {
            if (Context.IsSilent)
            {
                // Silent mode execution: immediately advance to next step
                Next?.Invoke(this, EventArgs.Empty);
                return;
            }

            if (view != null)
            {
                view.SetStepView(() =>
                {
                    _view = new MyCustomStepView(this);
                    return _view;
                });
            }
        }

        public void End()
        {
            _view = null;
        }

        public Task RollbackAsync()
        {
            // Roll back changes if installation is aborted
            return Task.FromResult(0);
        }

        public void RaiseNext() => Next?.Invoke(this, EventArgs.Empty);
        public void RaiseBack() => Back?.Invoke(this, EventArgs.Empty);
        public void RaiseCanceled() => Canceled?.Invoke(this, EventArgs.Empty);
    }
}

View (MyCustomStepView.xaml.cs):

using System.Windows;
using Rollouta.Winstaller.Interfaces;

namespace MyCompany.Winstaller.Plugins
{
    public partial class MyCustomStepView : StepViewBase
    {
        private readonly MyCustomStep _step;

        public MyCustomStepView(MyCustomStep step)
        {
            _step = step;
            InitializeComponent();
            Loaded += MyCustomStepView_Loaded;
        }

        private void MyCustomStepView_Loaded(object sender, RoutedEventArgs e)
        {
            Title = "Configuration";
            Header = "Configure network port";

            IsBackVisible = true;
            IsNextVisible = true;
            IsNextEnabled = true;
            IsCancelVisible = true;
        }

        public override void OnNext()
        {
            // Optional: Save user input to Context.Data before advancing
            _step.Context.Data["PortNumber"] = PortTextBox.Text;
            _step.RaiseNext();
        }

        public override void OnBack()
        {
            _step.RaiseBack();
        }

        public override void OnCancel()
        {
            _step.RaiseCanceled();
        }
    }
}

2. Creating a Pre/Post-Installation Script

Scripts execute logic before or after files are written.

using Rollouta.Winstaller.Interfaces;

namespace MyCompany.Winstaller.Plugins
{
    [PluginName("CleanupOldFilesScript")]
    public class CleanupOldFilesScript : IScript
    {
        public void Execute(InstallerContext installerContext)
        {
            // Retrieve shared services (e.g. ILogger) from the context
            var logger = installerContext.GetService<ILogger>();
            logger?.Info("Starting post-installation cleanup script...");

            string targetDir = installerContext.InstallationPath;
            // Execute file manipulation or process management logic here
        }
    }
}

License

Refer to the LICENSE.txt file packed with this package.