Custom actions play an very prominent role in getting the Developer's task done easily. The Microsoft Windows Installer provides many built-in custom actions for performing the installation process. The standard actions can also be defined as a part of the packaging template. Standard actions are sufficient to execute an installation in most cases. However, there are situations where the developer of an installation package finds it necessary to write a custom action. The Custom Actions are the actions entirely defined by the users i.e. the developer writes an action to execute his own installation. This is basically written to achieve few tasks which are not possible through the MSI.

How Can Custom Actions(CA) Be Defined?

Executable files (.exe)

• Calling an exe file from the Destination computer
• Calling an exe from Installation (stored in the Binary table)
• Calling an exe file from the Installed files (installed by the Application)
• Calling an exe file whose path is stored in a property

Example Scenario: This CA is written to launch an executable during installation that is installed on the user's machine or that is being installed with the application. This type of CA can be used when we have an pre-defined exe to be run for our desired result.

Best example would be to write a CA which gives permissions to registry keys using "setacl.exe". Calling a system exe "RefreshPolicies" which would refresh the user permissions and policies after the installation is complete. (This CA will be used only when we set permission to registry or file for the user.)

Dynamic linked libraries (.dll)

• Calling a Custom dll file from the Destination computer
• Calling a Custom dll from Installation (stored in the Binary table)
• Calling a Custom dll file from the Installed files (installed by the Application)
• Calling an dll from the Installation (stored in the Binary table)
• Calling an dll file from the Installed files (installed by the Application)

Example Scenario: To call special functions during an installation that are defined in a dynamic-link library (DLL). This type of CA can be used when we have a system dll or an application dll to be invoked for our desired result.

Best example: In driver packages, where we need to customize the package in such a way that it should check for the max XX value that is present in the machine and install the PNF or INF file. If the file oem14.INF is the max XX value that is present in the machine, while installing the package it should install the INF as oem15.INF resulting in the unique name for the INF file for that machine. For this purpose we write a custom action using setupapi.dll.

Visual Basic Script files

• Calling a VBScript from Embedded code (stored in the custom action table)
• Calling a VBScript file from the Installation (stored in the binary table)
• Calling a VBScript file from the Installed files (installed by the Application)
• Calling a VBScript file whose path is stored in the property

Java Script files

• Calling a JScript from Embedded code (stored in the custom action table)
• Calling a JScript from the Installation (stored in the binary table)
• Calling a JScript file from the Installed files (installed by the Application)
• Calling a JScript file whose path is stored in the property

Wise Script files

1. Run WiseScript from the Destination computer
2. Run WiseScript from the Installation (stored in the binary table)
3. Run WiseScript from the Installed files (installed by the Application)

Example Scenario: This type of CA is written to Use functions written in the development languages Microsoft Visual Basic Scripting Edition, Wise Script or Microsoft JScript literal script text during an installation. This type of CA can be used by writing a script as an embedded code or as a script file which would reside in the source directory.

Best example: Handling excel addins, Deleting a run time folder which remains back after un-installation., creating a folder in network share etc..

Other Actions Available:

Other Important Actions available in MSI Script of Wise Package studio are,

Display Message -display the message to the end user
Download file from the Internet
Launch Web Page -launch a Web page during an Installation
Open document from the Installed files
Pause Installation -temporarily stop a sequence from executing

Post Data to HTTP Server -post information to your Web server during an Installation

Set Directory -set a new value for the directory
Set Feature State -set the Installation state of a feature at runtime
Set Property -set a Windows Installer property

Terminate Installation -terminate it, if a specific condition is not met.

How Do We Use CA in Our MSI Package?

Steps for creating a Custom Action:

1. Select the Custom Action type in the MSI Script tab
2. Select the Sequence in the location tab
3. Apply the Condition in the location tab
4. Select the Scripting Options in the properties tab
5. Select the Processing Options in the properties tab
6. Select the Scheduling Options in the properties tab

Sequences:

1. Normal User Interface - execute the custom action only when the application Installs in the user interface
2. Normal Execute Immediate / Deferred - execute the custom action only when the application Installs in the silent mode
3. Administrative User Interface - execute the custom action only when the application Installs in "/A" mode with the user interface
4. Administrative Execute Immediate / Deferred - execute the custom action only when the application installs in "/A" with silent mode
5. Advertisement Execute Immediate / Deferred - execute the custom action only when the application installs in "/ju or /jm" mode.

Conditions:

1. Not Installed - During Installation only
2. REMOVE - During UnInstallation only
3. NOT REMOVE - During both Install & Uninstall

Scripting options:

• Immediate Execution
  Immediate custom actions, can be sequenced anywhere within any of the sequence tables. It has access to the installation database (read & set installation properties, modify feature & component states, add temporary columns, rows, and tables).
• Deferred Execution - User Context
  Deferred custom actions can only be sequenced between the InstallInitialize and InstallFinalize actions in execute sequence tables. It doesn't have access to the installation database. Deferred custom actions are not executed immediately. Instead they are scheduled to run later during the execution script. The execution script isn't processed until the InstallExecute, InstallExecuteAgain, or InstallFinalize action is run.

  If the Current User doesn't have the elevated privileges (Permission to make changes in the system directly), the custom actions should run in Deferred Execution in User Context only.

• Rollback only
  This Action should be executed during the Installation of the Rollback script or if the Installation is Unsuccessful
• Commit only
  This Action should be executed during the Installation of the Commit script.
• Deferred Execution - System Context
  Deferred custom actions can only be sequenced between the InstallInitialize and InstallFinalize actions in execute sequence tables. It doesn't have access to the installation database. Deferred custom actions are not executed immediately. Instead they are scheduled to run later during the execution script. The execution script isn't processed until the InstallExecute, InstallExecuteAgain, or InstallFinalize action is run.

If the Current User has the elevated privileges (Permission to make changes in the system directly), then it should run in Deferred Execution in System Context only.

Processing Options:

• Synchronous
  Windows Installer runs the custom action synchronously to the main installation. It waits for the custom action to complete successfully before continuing the main installation.
• Synchronous, ignore exit code
  Windows Installer runs the custom action synchronously to the main installation. It waits for the custom action to complete before continuing the main installation; the action can be either success or fail.
• Asynch, wait at end of sequence
  Windows Installer runs the custom action simultaneously with the main installation. At the end it waits for the exit code from the custom action before continuing.
• Asynch, no wait
  Windows Installer runs the custom action simultaneously with the main installation. It doesn't wait for completion of the custom action and doesn't check the exit code also.

Scheduling Options:

• Always Execute
• This action execute in all sequences
• Run first time
• This action execute only the first time Windows Installer encounters it.
• Run once per process
• This action execute only one time either Execute sequence that should not run if the installation is running in silent mode.
• Run only if UI sequence was run
• This action execute only if either Execute sequence is run following User Interface sequence.

Difference Between "Immediate Execute / Deferred Execute

Immediate

1. Custom actions, can be sequenced anywhere within any of the sequence tables
2. Custom actions have access to the Installation database
3. Custom actions can only run in the User Context
4. Custom actions should never modify the system state. i.e. should not run in elevated context

Deferred

1. Custom actions can be sequenced only between the InstallInitialize and InstallFinalize actions in the sequence tables
2. Custom actions doesn't have access to the Installation database
3. Custom actions can run both in the context of the user and elevated using the system context.
4. Custom actions can modify the system state.i.e can be run in elevated context

Difference Between "Deferred in System Context / Deferred in User Context"

User Context

1. Custom action which installs or modify a file under the INSTALLDIR

System Context

1. Custom action which installs or modify the file under INSTALLDIR or System folder directly.

Wise Default Properties for the Custom Actions

1. [AdminToolsFolder]
   C:\Document and Settings\Current User\Start Menu\Programs\Administrative Tools\
2. [AppDataFolder]
   C:\Document and Settings\Current User\Application Data\
3. [CommonAppDataFolder]
   C:\Document and Settings\All Users\Application Data\
4. [CommonFilesFolder]
   C:\Program Files\Common Files\
5. [DesktopFolder]
   C:\Documents and Settings\Current User\Desktop\
6. [FavoritesFolder]
   C:\Documents and Settings\Current User\Favorites\
7. [FontsFolder]
   C:\Windows\Fonts\
8. [LocalAppDataFolder]
   C:\Documents and Settings\Current User\Local Settings\Application Data\
9. [MyPicturesFolder]
   C:\Documents and Settings\Current User\My Documents\My Pictures\
10. [NetHoodFolder]
    C:\Documents and Settings\Current User\NetHood\
11. [PersonalFolder]
    C:\Documents and Settings\Current User\My Documents\
12. [PrintHoodFolder]
    C:\Documents and Settings\Current User\PrintHood\
13. [ProgramFilesFolder]
    C:\Program Files\
14. [ProgramMenuFolder]
    C:\Documents and Settings\Current User\Start Menu\Programs\
15. [RecentFolder]
    C:\Documents and Settings\Current User\Recent\
16. [SendToFolder]
    C:\Documents and Settings\Current User\SendTo\
17. [StartMenuFolder]
    C:\Documents and Settings\Current User\Start Menu\
18. [StartupFolder]
    C:\Documents and Settings\Current User\Start Menu\Programs\Startup\
19. [System16Folder]
    C:\Windows\System\
20. [SystemFolder]
    C:\Windows\System32\
21. [TempFolder]
    C:\Documents and Settings\Current User\Local Settings\Temp\
22. [TemplateFolder]
    C:\Documents and Settings\Current User\Templates\
23. [WindowsFolder]
    C:\Windows\
24. [WindowsVolume]
    C:\

Environment Settings Properties for the Custom Actions

1. [ALLUSERSPROFILE%]
   C:\Documents and Settings\All Users
2. [APPDATA%]
   C:\Documents and Settings\current User\Application Data
3. [CommonProgramFiles%]
   C:\Program Files\Common Files
4. [COMPUTERNAME%]
   System Name
5. [ComSpec%]
   C:\Windows\system32\cmd.exe
6. [HOMEDRIVE%]
   C:
7. [HOMEPATH%]
   C:\Documents and Settings\Current User
8. [ProgramFiles%]
   C:\Program Files
9. [SystemDrive%]
   C:
10. [SystemRoot%]
    C:\Windows
11. [TEMP%]
    C:\Documents and Settings\Local Settings\Temp
12. [TMP%]
    C:\Documents and Settings\Local Settings\Temp
13. [USERNAME%]
    Current User
14. [USERPROFILE%]
    C:\Documents and Settings\Current User
15. [Windir%]
    C:\Windows

Example Scenario

Consider we have a custom action to add files to the system on installation. Eg: Copy files from network share to the local machine after the installation in complete.

Follow these steps to get this done.

Goto MSI Script section of the Wise Package Editor.

Click to view.

Click to view.

Click to view.

Click to view.

Click to view.

Click to view.

Click to view.

Once the CA is done, sequence it in the right sequence on the MSI script.

Sample Scripts

Consider we have a requirement to delete a file/Registry Key through the MSI Custom Action. Here's the CA script on how we do it.

Custom Action syntax for deleting File:

Option Explicit
On Error Resume Next
Dim FSO
Dim MyFile
Set FSO = CreateObject ("Scripting.FileSystemObject")
Set MyFile = FSO.GetFile ([ProgramFilesFolder] & "ABC\abc.log")
MyFile.Delete 
Set MyFile = nothing
Set FSO = nothing

Custom Action syntax for deleting Registry key:

Option Explicit
On Error Resume Next
Dim WShell
Set WShell = CreateObject ("WScript.Shell")
Wshell.RegDelete "HKCU\Software\Vendor\Application\Test\"
Set Wshell = nothing

References and Further Reading

Introduction to Custom Actions: http://msdn.microsoft.com/en-us/library/aa368066(VS.85).aspx

Custom Action Sequences: http://bonemanblog.blogspot.com/2005/10/custom-act...

Wise Package Studio Reference Guide for standard actions.

Installation Phase and Execution: http://www.installsite.org/pages/en/isnews/200108/...