Deferred custom actions with WiX

Definition of Deferred Custom Actions

The installer does not execute a deferred execution custom action at the time the installation sequence is processed. Instead the installer writes the custom action into the installation script.


Custom actions that set properties, feature states, component states, or target directories, or that schedule system operations by inserting rows into sequence tables, can in many cases use immediate execution safely. However, custom actions that change the system directly, or call another system service, must be deferred to the time when the installation script is executed.

Purpose of deferred Custom Actions

The purpose of a deferred execution custom action is to delay the execution of a system change to the time when the installation script is executed. This differs from a regular custom action, or a standard action, in which the installer executes the action immediately upon encountering it in a sequence table or in the form with tag.


<Publish Event="DoAction" Value="CustomActionName">
<![CDATA[1]]>
</Publish>

How to define deferred custom action in WiX

Deferred custom action is defined in the following way:


<CustomAction Id="MyAction" Return="check" Execute="deferred"
BinaryKey="CustomActionsLibrary" DllEntry="_MyAction@4"
HideTarget="yes"/>


Lets describe the sample above:
- Execute=“deferred” – means that custom action with Id “MyAction” will execute in deferred mode ( in-script ).
- DllEntry="_MyAction@4" – the name of the function to be called, when installer executes generated install script.
- HideTarget="yes" - for security reasons, you may transfer confidential info to your custom action, this attribute notifies installer not to log parameters passed to custom action.

How to Transfer Properties to Deferred Custom Action

Because the installation script can be executed outside of the installation session in which it was written, the session may no longer exist during execution of the installation script. This means that the original session handle and property data set during the installation sequence is not available to a deferred execution custom action. Deferred custom actions that call dynamic-link libraries (DLLs) pass a handle which can only be used to obtain a very limited amount of information.


Properties that can be retrieved during in-script execution are:

- CustomActionData - value at time custom action is processed in sequence table. The “CustomActionData” property is only available to deferred execution custom actions. Immediate custom actions do not have access to this property.
- ProductCode - unique code for the product, a GUID string.
- UserSID - set by the installer to the user's security identifier (SID).


If other property data is required by the deferred execution custom action, then their values must be stored in the installation script. This can be done by using a second custom action.
In order to write the value of a property into the installation script for use during a deferred execution custom action we have to do the following:


- Insert a small custom action into the installation sequence that sets the property of interest to a property having the same name as the deferred execution custom action. For example, if Id for the deferred execution custom action is "MyAction" set a property named "MyAction" to the property X which you need to retrieve. You must set the "MyAction" property in the installation sequence before the "MyAction" custom action.


Although any type of custom action can set the context data, the simplest method is to use a property assignment custom action.


At the time when the installation sequence is processed, the installer will write the value of property X into the execution script as the value of the property CustomActionData.


Lets illustrate the above said with WiX sample.


At first we define custom action that will assign CustomActionData property.


<Property Id=”SOME_PUBLIC_PROPERTY”>
<![CDATA[Hello, from deferred CA]]>
</Property>


<CustomAction Id="MyAction.SetProperty" Return="check"
Property="MyAction" Value="[SOME_PUBLIC_PROPERTY]">
</CustomAction>


Then we put above defined custom action into execution sequence along with “MyAction” deferred custom action


<InstallExecuteSequence>
<Custom Action="MyAction.SetProperty" After="ValidateProductID"/>
<Custom Action="MyAction" After="MyAction.SetProperty"/>
</InstallExecuteSequence>


Our custom action will reside in DLL. Below is the sample where we retrieve “SOME_PUBLIC_PROPERTY”, during deferred (in-script) installer execution.


<Binary Id='CustomActionsLibrary'
SourceFile='Binary\CustomActionsLibrary.dll' />


#include <windows.h>
#include <msi.h>
#include <msiquery.h>
#include <tchar.h>


#pragma comment(linker, "/EXPORT:MyAction=_MyAction@4")

extern "C" UINT __stdcall MyAction (MSIHANDLE hInstall)

{

TCHAR szActionData[MAX_PATH] = {0};

MsiGetProperty (hInstall, "CustomActionData",
szActionData,sizeof(szActionData));

::MessageBox(NULL, szActionData, _T(“Deferred Custom Action”),
MB_OK | MB_ICONINFORMATION);

return ERROR_SUCCESS;

}


If there is need to transfer multiple properties into deferred custom action, “CustomActionData” property may contain value pairs e.g. PropertyName=PropertyValue with some separator symbol ( ; ).