oleg-shilo/wixsharp

Framework for building a complete MSI or WiX source code by using script files written with C# syntax.

Wix# (WixSharp) - managed interface for WiX

Framework for building a complete MSI or WiX source code by using script files written with the C# syntax.

In July 2014 Wix# was migrated to CodePlex Wix# and re-released under MIT license. It was subsequently migrated from CodePlex to GitHub. You can still find old releases and some useful content from the past discussions on CodePlex.

Project Description

Wix# (WixSharp) is a member of the CS-Script family. Wix# allows building a complete MSI or WiX source code by executing script files written with the plain C# syntax. Wix# engine uses a C# class structure to mimic WiX entities and their relationships to produce a valid deployment model.

Wix# answers many MSI authoring challenges. It solves the common MSI/WiX authoring limitations in a very elegant yet unorthodox way. Wix# follows the steps of other transcompilers like Script#, CoffeeScript or GWT by using source code of a more manageable syntax (C# in this case) to produce the desired source code of a less manageable syntax (WiX). A "more manageable syntax" in this context means less verbose and more readable code, better compile-time error checking and availability of more advanced tools.

Wix# also removes the necessity to develop MSI sub-modules (Custom Actions) in a completely different language (e.g. C++) by allowing both the components and behaviour to be defined in the same language (C#). This also allows for a homogeneous, simplified, and more consistent source code structure.

Overview

NOTE: WixSharp releases come in two streams: Releases v1.* use the WiX3 toolset to author msi setups, and v2.* use WiX4+. For the time being, the two streams will be maintained in parallel, but when WiX4/5 becomes mature enough, the WiX3 stream will be obsolete.

If you use WiX4+ stream, you need to install .NET SDK (not .NET Framework SDK) installed in your build environment. Visual Studio 2022 comes with .NET SDK already. The need for .NET SDK is dictated by the method WiX vendor distributes WiX compiler and its dependencies (via dotnet tool). WixSharp fully adheres to this approach. Even though it provides a workaround for the absence of .NET SDK.

If you are planning to use Wix# on Linux, you may find this article useful. Please note that Wix# builds MSI deployment packages and while MSI can be built on Linux it cannot be run on Linux as MSI is a pure Windows technology.

Please note that WixSharp NuGet packages (for both WiX3 and WiX4) are targeting .NET Framework only. This is because WiX does not support integration with any other .NET flavours but .NET Framework only.

You can find the instructions on how to author MSI setups with WixSharp in the Documentation section. And this section only highlights some of the available features.

You can use Visual Studio console application project and NuGet package as the starting point.

Alternatively you can install "WixSharp Project Templates" Visual Studio extension. Read more about the Wix# VS templates here.

Wix# allows a very simple and expressive definition of deployment. This is an example of a simple Wix# script:

using System;
using WixSharp;
 
class Script
{
    static public void Main(string[] args)
    {
        var project = new Project("MyProduct",
                          new Dir(@"%ProgramFiles%\My Company\My Product",
                              new File(@"Files\Docs\Manual.txt"),
                              new File(@"Files\Bin\MyApp.exe")));
 
        project.GUID = new Guid("6f330b47-2577-43ad-9095-1861ba25889b");
 
        Compiler.BuildMsi(project);
    }
}

One of the most intriguing features of Wix# is the ability to define/implement managed Custom Actions directly in the script file:

using System;
using System.Windows.Forms;
using WixSharp;
using Microsoft.Deployment.WindowsInstaller;
 
class Script
{
    static public void Main(string[] args)
    {
        var project = new Project("CustomActionTest",
                          new Dir(@"%ProgramFiles%\My Company\My Product",
                              new DirFiles(@"Release\Bin\*.*")),
                          new ManagedAction(CustomActions.MyAction));
 
        BuildMsi(project);
    }
}
 
public class CustomActions
{
    [CustomAction]
    public static ActionResult MyAction(Session session)
    {
        MessageBox.Show("Hello World!", "Embedded Managed CA");
        session.Log("Begin MyAction Hello World");
 
        return ActionResult.Success;
    }
}

Another important feature is the support for custom UI including WPF external UI:

The Samples Folder an extensive collection of Wix# samples covering the following development scenarios:

• Visual Studio integration including NuGet packages and VS2013/2015 project templates extension
• Installing file(s) into Program Files directory
• Changing installation directory
• Installing shortcuts to installed files
• Conditional installations
• Installing Windows service
• Installing IIS Web site
• Modifying app config file as a post-install action (Deferred actions)
• Installing "Uninstall Product" shortcut into "Program Menu" directory
• Installing registry key
• Showing custom licence file during the installation
• Launching installed application after/during the installation with Custom Action
• Executing VBScript Custom Action
• Executing Managed (C#) Custom Action
• Executing conditional actions
• Targeting x64 OSs
• Registering assembly in GAC
• File Type registration
• Setting/Reading MSI properties during the installation
• Run setup with no/minimal/full UI
• Localization
• Major Upgrade deployment
• Authoring and using MergeModules
• Pre-install registry search
• Customization of setup dialogs images
• Rebooting OS after the installation
• Building MSI with and without Visual Studio
• Simplified Managed bootstrapper for UI based deployments
• Simple Native bootstrapper
• Custom MSI dialogs
• Custom WinForms dialogs
• Custom external UI
• Console setup application
• WinForm setup application
• WPF setup application