WixSharp Documentation

repository·master·Indexed 23 days ago

WixSharp is a C# managed interface and transcompiler for the WiX toolset that allows developers to author MSI installers using C# syntax instead of XML. It supports file and directory management, system integration, managed custom actions, and bootstrapper creation. The library provides separate release streams for WiX3 (v1.*) and WiX4+ (v2.*), with specific support for .NET Framework and limited .NET Core support via AOT compilation.

Tokens: 14.4K
Snippets: 26
Records: 119
Agent score: 79%

What's inside WixSharp

Overview of WixSharp features
master
WixSharp supports a wide range of deployment scenarios, including:
- File & Directory Management: Installing files to Program Files, changing installation directories, and installing shortcuts.
- System Integration: Installing Windows services, IIS Web sites, registry keys, and registering assemblies in the GAC.
- Custom Actions: Executing Managed (C#), VBScript, or conditional actions; modifying app config files (Deferred actions).
- UI & UX: Custom MSI dialogs, WinForms dialogs, WPF external UI, and custom license files.
- Advanced Deployment: Major Upgrades, MergeModules, localization, targeting x64, and rebooting the OS.
- Bootstrappers: Simplified Managed bootstrappers for UI-based deployments and Simple Native bootstrappers.
https://github.com/oleg-shilo/wixsharp/blob/master/docs/README.md
What is WixSharp
master
WixSharp is a managed interface for WiX that allows you to build complete MSI or WiX source code using C# scripts. It acts as a transcompiler, taking a more manageable C# syntax and producing the corresponding WiX source code. This approach provides better compile-time error checking and allows you to define both components and behaviors (like Custom Actions) in the same language (C#), eliminating the need for C++ for MSI sub-modules.
https://github.com/oleg-shilo/wixsharp/blob/master/README.md
Use ShellFileDialogs in WixSharp
master
WixSharp uses a specific fork of ShellFileDialogs to provide managed interfaces for Windows shell file dialogs. This fork is specifically recompiled for .NET 4.7.2 to ensure compatibility with the WixSharp target runtime and includes fixes for known issues in the original repository.
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/WixSharp.UI/ManagedUI/ShellFileDialogs/readme.md
Understand the nbsbuilder project structure
master
The nbsbuilder application is a console application generated by the AppWizard. It consists of the following key components:
- nbsbuilder.vcproj: The main Visual C++ project file. It stores configuration details such as the Visual C++ version used, target platforms, build configurations, and specific project features selected during the wizard process.
- nbsbuilder.cpp: The primary source file containing the main application logic.
- StdAfx.h and StdAfx.cpp: Files used to implement a Precompiled Header (PCH) to speed up build times. These generate nbsbuilder.pch and StdAfx.obj respectively.
Customization Note: Look for TODO: comments within the source code to identify specific areas where the AppWizard expects you to add custom logic or modifications.
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/NbsBuilder/NbsBuilder.Src/nbsbuilder/ReadMe.txt
Rules for nesting Merge elements in WiX/WixSharp
master
When working with Merge elements in WixSharp, follow these structural constraints derived from WiX conventions:
1. Nesting: Although WiX syntax might technically allow a Merge element to belong directly to the Product element, the official WiX documentation requires the Merge element to be nested inside a Directory element.
2. Conditions: WiX does not allow a Condition element to be a child of a Merge element.
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/WixSharp.Samples/Wix%23%20Samples/MergeModules/Consuming%20MergeModule/readme.txt

Implement Custom Actions in WixSharp

master

Custom actions are implemented as static methods within a class, decorated with the [CustomAction] attribute. These methods receive a Session object which provides access to MSI properties and installation data.

Important Performance Note: Custom actions are AOT (Ahead-of-Time) compiled. Adding large libraries or dependencies (like System.Windows.Forms) can significantly increase build times and the size of the custom action binaries. For lightweight actions, consider using Native Win32 calls (e.g., Native.MessageBox) to minimize overhead.

public class Actions
{
    [CustomAction]
    public static ActionResult CustomAction(Session session)
    {
        // Access MSI properties via session.Property()
        Native.MessageBox("MSI Session\nINSTALLDIR: " + session.Property("INSTALLDIR"), "WixSharp - .NET8");

        return ActionResult.Success;
    }

    [CustomAction]
    public static ActionResult CustomAction2(Session session)
    {
        // Convert session to SetupEventArgs for richer metadata
        SetupEventArgs args = session.ToEventArgs();

        Native.MessageBox("WixSharp RuntimeData\nMsiFile: " + args.MsiFile, "WixSharp - .NET8");

        return ActionResult.UserExit; // terminate the setup
    }
}

Choose the correct WixSharp release stream
master
WixSharp provides two parallel release streams based on the WiX toolset version you intend to use:
- v1. releases*: Use these if you want to author MSI setups using the WiX3 toolset.
- v2. releases*: Use these if you want to author MSI setups using WiX4+.
Important Compatibility Notes:
- Target Framework: WixSharp NuGet packages (for both WiX3 and WiX4) target .NET Framework only. WiX does not support integration with other .NET flavors.
- WiX4+ Requirements: If using the v2.* stream, you must install the .NET SDK (not just the .NET Framework SDK) in your build environment. Visual Studio 2022 includes this by default. This is required because WiX4+ is distributed via dotnet tool.
https://github.com/oleg-shilo/wixsharp/blob/master/README.md
Work with MSI properties in WixSharp
master
You can interact with MSI properties during a setup installation in two primary ways:
1. Using the Session instance: Analyze property values dynamically during the installation process.
2. Executing SQL commands: Query the installation database directly to retrieve or manipulate property values.
Important Note on Naming: When defining public properties to be passed via the command line, you must follow the MSI naming convention of using capitalized names (e.g., MYPROPERTY instead of myproperty).
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/WixSharp.Samples/Wix%23%20Samples/Properties/readme.txt
Implement conditional installation components
master
When defining components that should only be installed under certain conditions (such as creating a desktop shortcut), you must decide when the condition is evaluated based on whether user interaction is required:
1. User Interaction Required: If the condition depends on user input (e.g., a checkbox in a dialog or a message box), the condition must be set during the InstallUISequence.
2. No User Interaction Required: If the condition can be determined automatically (e.g., by checking for the existence of a registry key), the condition can be set during the InstallExecuteSequence.
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/WixSharp.Samples/Wix%23%20Samples/Conditional%20Installation/readme.txt
Understand the difference between Win32 and .NET Bootstrappers
master
WixSharp supports different types of bootstrappers:
1. Native Win32 Bootstrapper: A self-sufficient setup.exe that handles prerequisites and embedded MSIs. This is the focus of the NsisBootstrapper sample.
2. .NET Bootstrapper: Represented by DotNETBootstrapper.cs in the sample code. Note that DotNETBootstrapper.cs is provided for demonstration purposes only and cannot be executed directly as a standalone bootstrapper in the same manner as the native Win32 version.
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/WixSharp.Samples/Wix%23%20Samples/Bootstrapper/NsisBootstrapper/readme.txt
How AdminExecuteSequence works in WixSharp
master
When creating an MSI intended for administrative installation (using msiexec /a *.msi), you must place Custom Actions in the AdminExecuteSequence to ensure they are invoked correctly.
In this sample, the MyAdminAction is placed in the AdminExecuteSequence. This ensures that when the MSI is launched in administrative mode, the action is triggered. Note that this sample focuses on the sequence setup rather than providing a complete, production-ready AdminInstall MSI.
https://github.com/oleg-shilo/wixsharp/blob/master/Source/src/WixSharp.Samples/Wix%23%20Samples/AdminInstall/readme.txt

Understand .NET Core support in WixSharp

master

WixSharp's ability to use .NET Core for MSI/WiX workflows depends on the specific functionality being implemented. Currently, most standard MSI/WiX workflows (like Custom Actions, Burn Bootstrappers, and Embedded UI) rely on .NET Framework because they are hosted by the MSI or WiX runtimes.

To enable .NET Core support, WixSharp utilizes AOT (Ahead-of-Time) compilation, which converts compiled assemblies into native DLLs. This allows certain scenarios to run in environments that do not support the full .NET runtime.

Current Support Matrix for .NET Core via AOT

Functionality	Host	Runtime	Status
CA (Custom Action)	MSI	Native, AOT-asm	Supported
Managed Project Events	WixSharp	AOT-asm	Possible (with minimal dependencies)
Custom BA (Burn)	WIX	.NET Framework	Not supported (must stay .NET Framework)
Embedded UI	WiX	.NET Framework	Not supported (must stay .NET Framework)
MSI builder	WixSharp	AOT-asm	Requires WixSharp recompilation

Note: The goal of the .NET Core port is to consolidate WixSharp into a single stream rather than maintaining separate versions for WiX3, WiX4, and .NET Core.