Obtaining Context Information for Deferred Execution Custom Actions (Windows)

MSDN Library
Win32 and COM Development
Administration and Management
Application Installation and Servicing
Windows Installer
Windows Installer Guide
Custom Actions
Using Custom Actions

Invoking Custom Actions
Sequencing Custom Actions

Obtaining Context Information for Deferred Execution Custom Actions

Adding Custom Actions to the ProgressBar
Debugging Custom Actions
Determining UI Level from a Custom Action
Uninstalling Custom Actions
Returning Error Messages from Custom Actions
Setting a Restore Point from a Custom Action
Functions Not for Use in Custom Actions
Changing the System State Using a Custom Action
Accessing the Current Installer Session from Inside a Custom Action
Accessing a Database or Session from Inside a Custom Action
Using a Custom Action to Launch an Installed File at the End of the Installation
Using a Custom Action to Create User Accounts on a Local Computer
Using 64-bit Custom Actions

Obtaining Context Information for Deferred Execution Custom Actions

Obtaining Context Information for Deferred Execution Custom Actions

Because 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. In this case, the original session handle and properties set during the installation sequence are not available to a deferred execution custom action. Any functions that require a session handle are restricted to a few methods that can retrieve context information, or else properties that are needed during script execution must be written into the installation script. For example, 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. Functions that do not require a session handle can be accessed from a deferred custom action.

Deferred execution custom actions are restricted to calling only the following functions requiring a handle.

Function	Description
MsiGetProperty	Supports a limited set of properties when used with deferred execution custom actions: the CustomActionData property, ProductCode property, and UserSID property. Commit custom actions cannot use the MsiGetProperty function to obtain the ProductCode property. Commit custom actions can use the CustomActionData property to obtain the product code.
MsiFormatRecord	Supports a limited set of properties when used with deferred execution custom actions: the CustomActionData and ProductCode properties.
MsiGetMode	When called from deferred execution custom actions, commit custom actions, or rollback custom actions, MsiGetMode returns True or False when requested to check the mode parameters MSIRUNMODE_SCHEDULED, MSIRUNMODE_COMMIT, or MSIRUNMODE_ROLLBACK. Requests to check any other run mode parameters from a deferred, commit, or rollback custom action returns False.
MsiGetLanguage	The numeric language ID for the current product. Commit custom actions cannot use the MsiGetLanguage function. Commit custom actions can use the CustomActionData property to get the numeric language ID.
MsiProcessMessage	Processes error or progress messages from the custom action.

A custom action that is written in JScript or VBScript requires the install Session object. This is of the type Session Object and the installer attaches it to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the following methods or properties of the Session object to retrieve its context.

Name	Description
Mode Property	Returns True for MSIRUNMODE_SCHEDULED only.
Property Property (Session Object)	Returns the CustomActionData property, ProductCode property, or UserSID property.
Language Property (Session Object)	Returns numeric language ID of the installation session.
Message Method	Called to handle errors and progress.
Installer Property	Returns the parent object, which is used for non-session functions such as registry access and installer configuration management.

Property values that are set at the time the installation sequence is processed into script may be unavailable at the time of script execution. Only the following limited set of properties is always accessible to custom actions during script execution.

Property name	Description
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.

Aa370543.wedge(en-us,VS.85).gif To write the value of a property into the installation script for use during a deferred execution custom action

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 the primary key 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 (for example Custom Action Type 51).
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.

See Also