Custom Actions - Part 1

INTRODUCTION

Custom Actions are deployment projects .NET programs written by your team that execute near the end of the installation process. You can use them to perform installation shores hard to implement with the existing features exposed by the setup project, in this order of ideas a custom action can install packages, create folders, copy files or anything else on the target machine.

When you rely on Custom Actions to enhance the installation of your application, you should enable the Custom Action to uninstall those things it created during installation. If your custom action installs a database file on the target machine, the same custom action should include the routine to remove the database file, if the user chooses to uninstall your application.

Why would you want to use a Custom Action to install a database file or one of your application's files when it can be done with the Deployment Project File System feature? The reason to take the custom action approach is to resolve those scenarios where a file or database may change from the time you create the application deployment package, keep in mind that any file distributed in the DP's File System become part of the MSI file, you should rebuild the project to update them. While a custom action provides the freedom to distribute your application, including its dynamic files without forcing a rebuild.

There are two types of custom actions: Project Installer Class and non-Project Installer Class.

A project installer class is more integrated with your deployment project, and implement an installation component this FAQ document does not address this scenario.

A non-project installer class is a Windows Application executing at the very last step of your installation project, this document focus on implementing them.

SCOPE

This document is based on VS.Net 2003 deployment projects, explaining as much as possible about Custom Actions, and providing a step by step procedure on how to create them.

It does not cover implementing Project Installer Class custom action.

TERMINOLOGY

Target Machine is the PC or workstation your project will be installed on.
Developer Machine is your PC, the one you use to develop your solution and create a deployment project.
Deployment or Setup Projects are specialized projects that install your solution on a target machine.
Launch Condition is the name given to an action in your Deployment Project that takes place when a condition is not satisfied.
Custom Action an external process written by the developer that run by the deployment project at installation time when the installation is about to finish.

ADDING A CUSTOM ACTION

1. You create the application that will perform the custom installation actions of the items your project requires. This is a VS.Net project outside of your deployment project. The enclosed project contains the application DP_CA_App.

This application project should accept parameters.
It should implement Install and Uninstall procedures.
It will be up to your application's requirements what to do with it:
- Create a conditional shortcut.
- Copy files to the target machine.
- Install a component
- etc.
Part 2 of this FAQ illustrates these implementations.

2. Add the application program created on the previous step to this deployment project.
  
   2.1 Open the Solution Explorer panel.
   2.2 Right click on the solution node.
   2.3 Click on the Add option.
   2.4 Click on the Existing Project.
   2.5 Navigate and select the project create on step 1.

3. Add the Custom Action application to the Application Folder of your deployment project.

   3.1 Click on View
   3.2 Click on Editor
   3.3 Click on File System.

On the File System panel.

   3.4 Right click on the Application Folder
   3.5 Click on Add
   3.6 Click on Project Output
   3.7 Making sure that the Custom Action Application is the one shown, click ok
         If the Custom Action Application is not the default on the list, click on the drop down
         list control and select it, then click the Ok button.

4. Select your project's custom action tab.

   4.1 Click on View.
   4.2 Click on Editor.
   4.3 Click on Custom Action.

In the Custom Action Panel select the required custom action type.

There are four types of custom actions, Install, Commit, Rollback and Uninstall. Each one of them representing the different stages of the installation process. You may have one custom action application dealing with these stages, its first parameters should expect i, c, r or u accordingly or you may have one custom action per installation stage. This MSDN article is about the installation phases described in this paragraph Custom Actions Management in Deployment

Now, in order to add an Install custom action, you follow these steps:

   4.4 Right click on the Install tree node.
   4.5 Click on Add Custom Action.
   4.6 Click on the Ok button if your custom action was added to the application folder,
          as explained in the step 3 above.
   4.7 Select the custom action reference from the list.

The custom action was added to your project, and it expose six properties:

(Name) This is the custom action name, nothing to do with this property.

Arguments The arguments expected by the custom action, it could be any of the deployment project properties, your own properties defined in File Search, Launch Conditions, User Interface properties or hardcode parameters, such as i, r, c, or u; it will look like this:

Code:
"i" for install.
"[INSTALL_SC]" is a property defined in the project user interface that prompts the user to install a shortcut.
"[SourceDir]" a deployment project property containing the location of the objects it is installing.
"[TARGETDIR]" another deployment project property, this one contains the location where your application is getting installed.
"[DesktopFolder]" is a deployment project property.

Warning If you are using the [DesktopFolder] property, you should exclude its closing double quote, something is weird with it, it missbehave (bug) as you cannot close its double quote.

The deployment project properties passed as arguments to a custom action should be enclosed in double quotes and brackets "[]", they are case sensitive, so INSTALL_SC is different to Install_SC.

Installer Class custom actions ignore this property.

Condition to control the execution of the custom action, the condition could be based on a Launch Conditions or properties gathered by your deployment project.

Custom Action Data property pass values to your custom action when it is created as an Installer Class; Non installer class custom actions ignore this property.

Installer Class It should be False if your custom action is a Win Application project, and it must be set to True when your custom action was defined as an Installer Project.

Sourc Path is the location of the custom action application in your developing machine.

HOW A CUSTOM ACTION WORKS

A Win Application custom action executes near the end of your deployment project execution, it may trigger processes to install packages, move files around outside the pre-defined setting of the deployment project, create conditional shortcuts, perform post installation validation and provide a better experience to the installer by playing back movies or animations effects.

Both types of Custom Actions, Win Application non-installer class and Installer Class receive parameters passed by the deployment project, as they do not have access to its environment; Win Applications take their parameters from the Arguments property, while Installer Classes relies on the CustomActionData property.

There is no way to cancel the installation within a custom action, unless its code returns a non-trappable error, in this case the installation halt and undo everything.

PROJECT

The enclosed project DP_CA illustrates custom actions, it deploys a simple Hello World application and creates a conditional shortcut based on user input, it also move a file which is not part of the MSI package.

This project does not include the .Net Framework, which is required by its custom action. It was built like that to make the project size small and be able to post it here. You should install the .Net Framework on the target machine you use to play with it.

The project's base path is: C:\Usr\VbCity\Vb_Net\DP_CA; You will find three subfolders in there, one per each of its modules, the DP_CA folder is the deployment project itself; its custom action project is located at the DP_CA_App folder, and the Hello World application is included in the Hello_World folder; try to unzip it on these folders to avoid having path related conflict issues.

It prompts the user to create a conditional shortcut to the Hello World application it install.

This FAQ document continue at Custom Actions - Part 2