How to create fully fledged C# custom actions

ImportantThe following article uses options that are available starting with the Professional edition and project type.

The installation process can be controlled using Custom Actions. They can be dynamic linked libraries, Visual Basic scripts or JavaScript files. A custom action written in C# will generate a dynamic linked library file (DLL).

Tools required

In order to create a custom action in C# the WiX Toolset is required to be installed on the developer machine. Once downloaded and installed, the toolset will add all necessary modules enabling you to create C# custom actions from Microsoft Visual Studio.

For Microsoft Visual Studio 2005 and 2008 editions WiX 3.0 Toolset is required. WiX 3.5 Toolset supports only Microsoft Visual Studio 2010 edition.

Creating a C# custom actions project

Once all the necessary tools are installed, the following steps must be followed:

1. Start Microsoft Visual Studio
2. From the Menu bar select “File > New Project”
3. From the "New Project" dialog select “WiX” project type and “C# Custom Action Project”

By default, the new project will generate a simple custom action that will write some text in the installer log:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.Deployment.WindowsInstaller;

namespace CustomAction1
{
    public class CustomActions
    {
        [CustomAction]
        public static ActionResult CustomAction1(Session session)
        {
            session.Log("Begin CustomAction1"); // Here you can write your own custom action code
            return ActionResult.Success;
        }
    }
}

4. Based on the above example, CustomAction1 is the name of the custom action function. This name can be customized when writing your own custom action.

Generate the custom action file

1. From the Menu bar select the “Build > Build Solution” option.
2. This will generate two DLL files: CustomAction1.dll and CustomAction1.CA.dll
3. The CustomAction1.CA.dll file is the one that holds the C# custom action which will be used in Advanced Installer.

Integrate the C# custom action in Advanced Installer

1. Select the CustomAction1.CA.dll file and add it to your Advanced Installer project
2. Go to Custom Actions Page, add a Custom Actions List“Call function from attached native DLL” custom action with sequence from Add Custom Action Tab or the toolbar and select CustomAction1.CA.dll
3. In the "Function Name" field from the "Custom Action Properties" view select CustomAction1
4. Build the project and test it

Get / Set properties from C# custom action

The following example demonstrates how to get or set an installer public property from a C# custom action:

public static ActionResult CustomAction1(Session session)
{
// sending message to installation log
session.Log("Begin CustomAction1");

// getting a property
YourVariable = session["YOUR_PROPERTY"];

// setting a property
session["YOUR_PROPERTY"] = "YOUR_VALUE";

return ActionResult.Success;
}

Below is a link to a short video depicting the steps explained above.

Build and Run C# custom action

Debug C# custom action

1. Add some code for displaying a message box at the beginning of your custom action:

public static ActionResult CustomAction1(Session session)
{
  // display message to allow attaching the debugger
  MessageBox.Show("Please attach a debugger to rundll32.exe.", "Attach");

  // sending message to installation log
  session.Log("Begin CustomAction1");
  .
  .
  .

1. Since you will use MessageBox, make sure you have a reference to System.Windows.Forms.dll
2. Add a breakpoint on the next line of code, after your message box code
3. Rebuild your custom action project with Visual Studio
4. Rebuild your Advanced Installer project
5. Run the installation using "Run and Log" from Advanced Installer
6. When the message box displays, go to Visual Studio project > Tools > Attach to Process…
7. From the Available Processes list select the process with the name "rundll32.exe" and title "Attach"
8. Click Ok on the message box in your installation
9. The breakpoint you set earlier should now be activated in VS

While debugging the custom action after implementing the above steps, you can observe the property changes in the Log pane of Advanced Installer.

Below is a link to a short video depicting the steps explained above.

Debug C# custom action