20.8 Creating a Custom Executable Action

You want the setup program to execute some custom code that you have written (a custom action).

Technique

For the setup file to execute a custom action, you need to do the following:

• Write the code for the custom action.

• Ensure that the assembly containing the compiled code is one of the items installed on the target machine by the setup project. The easiest way to do so is to have your custom action code as a separate project in the solution and add the primary output from this project to the items installed in the File System Editor.

• Use another of the setup editors, the Custom Actions Editor (available from View, Editors), to add the assembly containing the code to the list of custom actions.

We start by examining how to write code so it can be executed as a custom action. If you intend your custom action to be an executable assembly, you need to have the entry point to the assembly invoke your custom action. To illustrate the code, we continue the example from Recipe 20.7, "Conditionally Installing Files," in which the setup program uses a custom Windows Installer property, INSTALLTOOLS , to indicate whether the user wants some diagnostic tools installed. Suppose now that you want an extra dialog box that you've coded yourself to be displayed when the setup is finished; this dialog box will display a welcome message and confirm whether the diagnostic tools were requested . Listing 20.1 shows the code to achieve this goal.

Listing 20.1 A Simple Welcome Dialog

 class Class1 {         static void Main(string [] args)         {                 string message = "Welcome to the C# Cookbook Samples\n";                 if (args.Length > 0 && args[0] == "1")                         message += "Diagnostic tools have also been installed";                 MessageBox.Show(message, "Welcome");         } } 

The purpose of this code should be obvious, but you might wonder about the if statement. The code is based on the assumption that the first element of the args[] array passed in as command-line parameters contains the string 1 if the user asked for diagnostic tools to be installed and otherwise . In other words, this string contains the value of our custom INSTALLTOOLS Windows Installer property.

You use the VS.NET Properties Window for the custom action to specify any command-line parameters that Windows Installer should pass to the custom action. You should first build the custom action project and then use the File System Editor to add the primary output for this project to the list of files installed by the setup project. Next , navigate to the setup project's Custom Actions Editor and make the changes shown in Figure 20.16.

Figure 20.16. The Custom Actions Editor with some custom actions added.

The Custom Actions Editor has four nodes according to the circumstances in which you might want your custom action executed ”so you can add custom actions to be executed when the installation is actually performed, committed, rolled back, or uninstalled . Figure 20.16 shows the situation after our custom action was added; for this example, we call the custom action project DisplayWelcome. When you first open the Custom Action Editor, there are no custom actions. To add an action under the Install node, you right-click on the Install node and select Add Custom Action from the context menu. You then see a dialog box asking you to identify the custom action from the set of files installed. Select the primary output from the required custom action project.

Finally, you need to set the properties for the new custom action using the VS.NET Properties Window. Figure 20.17 shows how to set the properties so our custom action will be executed if the user opts to install the diagnostic tools in our example.

Figure 20.17. Setting the properties for an executable custom action.

Note that the InstallerClass property is set to False to indicate it is an executable custom action. It is also possible to code custom actions as classes, which is covered in the next recipe. Notice that it is possible to add a Condition governing whether the custom action should be executed. The Arguments property indicates the command-line arguments to be passed to the custom action when it is executed. If you want the value of a property passed in, then you must enclose the name of that property in square brackets. (To pass in more than one value, separate the properties by commas, as in [Version9x], [VersionNT] ). By specifying the INSTALLTOOLS property that we created in Recipe 20.7, the result is that the value 1 is passed in if the user opts to install the diagnostic tools.

Comments

Adding a custom action as an executable file is what you need to do if you want the custom action to have a separate user interface. It is easy to code; however, it's not the most flexible means of adding a custom action. For maximum flexibility and power in terms of interaction between your custom action and Windows Installer, you should code the custom action as a class.