Automatic account creation is now enabled. Captcha authentication required for account creation and editing unless you are trusted here.
Category:Custom Actions
From WiX Wiki at MindCapers
See also Messy Custom Actions, in process of cleaning up. --Julie 15:49, 19 November 2007 (CST)
Contents |
Introduction to Custom Actions
While almost all actions that must be taken during installation can be handled by standard actions available from Windows Installer, sometimes it is necessary to do other things. This can be accomplished by using external code, be it an executable, DLL or script, called from a Custom Actions. There are many types of custom actions available. These are all used in the same general way in WiX, with the differences being in the way attributes and corresponding properties are used. The choice of what type to use depends on the situation. Care should also be exercised when deciding to use a custom action since they can be difficult to develop appropriately. Indeed some who work with Microsoft Installer on a regular basis suggest that because of this difficulty custom actions using JScript, VBScript or anything with a dependency on a specific runtime should be avoided. [1][2][3]
In the interest of balance, it should also be noted that there are many with strong opinions that the Microsoft Installer team needs to bring themselves back in line with the rest of the development community. [4]
In the real world there will be times when custom actions are needed. Hopefully after you read the following you will be able to create and consume custom actions without creating a maintenance nightmare for yourself.
Defining Custom Actions
todo
Heath Stewart's Blog has an item with for creating custom actions.
C/C++ Custom Actions
Script Custom Actions
Running Custom Actions
The <Custom> Element
This element must have inner text that specifies whether or not it is to be run. If the inner text is empty, the action will never run.
Ordering Custom Actions (Sequences)
It is frequently important that some custom actions run at a certain point in the installation process. For this reason, it is important to understand how the Windows Installer orders its actions.
The Windows Installer makes one or several passes through a .msi each time it is run.
What Sequence Should Custom Actions Be Placed In?
Custom actions should be scheduled in both sequences, usually. If a CA is scheduled only in InstallUISequence, it won't work when a user does a quiet (or quieter) setup, like with /qb or /qn. One option is to mark the CA as Execute="firstSequence" so it only runs once (e.g., in the UI if both sequences are run) if it takes a long time to run.
<InstallExecuteSequence>
...
<Custom Action='CallRegASM' After='InstallFinalize'>NOT Installed</Custom>
<Custom Action='CallUnRegASM' After='InstallInitialize'>Installed</Custom>
...
</InstallExecuteSequence>
<InstallUISequence>
The InstallUISequence runs before the InstallExecuteSequence. The main purpose of this sequence is to get the user's preference for use within the actual execution of the installer. For this reason, if there are custom actions that you would like to run at the very beginning of the installation process, these should be placed in the InstallUISequence. For example, if you would like to check the installed version of another product via a registry entry as a launch condition and inform the user if it isn't up to snuff, you would do something like this:
<Property Id='SOMEAPP_VERSION'>
<RegistrySearch Id='SEARCH_SOMEAPP_VERSION' Root='HKLM' Key='Software\SomeCompany\SomeApp' Name='Version' Type='raw' />
</Property>
<CustomAction Id='SET_APPVERSTR' Property='APP_VERSTR' Value='SomeApplication v[SOMEAPP_VERSION] is installed.' Execute='immediate' />
<CustomAction Id='SET_NOVERSTR' Property='APP_VERSTR' Value='SomeApplication is not installed.' Execute='immediate' />
<InstallUISequence>
<Custom Action='SET_APPVERSTR' After='AppSearch'>SOMEAPP_VERSION</Custom>
<Custom Action='SET_NOAPPVERSTR' Before='LaunchConditions'>SOMEAPP_VERSION</Custom>
</InstallUISequence>
<InstallExecuteSequence>
<AdminUISequence>
<AdminExecuteSequence>
<AdvertiseExecuteSequence>
Scheduling Deferred Custom Actions
See this MSDN article for details about scheduling deferred custom actions. You need two custom actions for every deferred CA: one that performs the action and one, scheduled immediately before the other, that rolls it back.
Links about Sequencing
Relevant Examples
- CANotepadTest is an example of a Type 2 custom action (calling an executable as from a command line).
I have two separate executables that I wish to run. The first is during the install:
- Call an EXE Example
<CustomAction
Id=LaunchAExeWithCLIAction'
Directory='INSTALLDIR'
ExeCommand='[INSTALLDIR]A.exe -blah="blah"'
Return='ignore' />
<InstallExecuteSequence>
<Custom Action='LaunchAExeWithCLIAction' After='InstallFinalize'>
NOT Installed
</Custom>
</InstallExecuteSequence>
- Conditionally call an EXE Example
The second executable I wish to optionally launch upon clicking the finish button at the end of the installation, dependent upon whether a tickbox was selected:
<CustomAction
Id='LaunchBExeAction'
Directory='INSTALLDIR'
ExeCommand='[INSTALLDIR]B.exe'
Return='asyncNoWait' />
<Control
Id="Finish"
Type="PushButton"
X="236" Y="243"
Width="56" Height="17"
Default="yes"
Cancel="yes"
Text="!(loc.WixUIFinish)">
<Publish Event="DoAction" Value="LaunchBExeAction">
NOT Installed AND IS_LAUNCH_ON_INSTALL="1"
</Publish>
</Control>
- Call a CMD Example
<CustomAction Id="CA1" Property="CA1_PROP"
Value="[SystemFolder]cmd.exe" />
<CustomAction Id="CA2" Property="CA1_PROP" ExeCommand="/c dir "[INSTALLDIR]" > c:\dir2.txt" />
<InstallExecuteSequence>
<Custom Action="CA1" After="InstallFinalize" />
<Custom Action="CA2" After="CA1" />
</InstallExecuteSequence>
Articles in category "Custom Actions"
There are 2 articles in this category.
