How to create fully fledged C# custom actions
The 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.
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.