MSI Factory
Note: LuaScript custom actions require Internet Explorer 4.01 (version 4.72.2106.8) or later installed.
LuaScript is a scripting language that can be used from your MSI installers to perform advanced logic that cannot be accomplished through the Windows Installer engine itself. LuaScript is based on the Lua (www.lua.org) programming language but has been expanded to include a full action set that will help accomplish many installation tasks.
There are a few good reasons to use LuaScript in your installers over using other Custom Action methods:
1. Self-Contained: The LuaScript engine is relatively small and is completely self-contained. That is, it does not depend on any other technologies being pre-installed on the system in order to work. The LuaScript engine is contained in one DLL which is included in your MSI file.
2. Easy to Use: It is often easier to accomplish what you want using LuaScript than trying to create a custom action executable or DLL in C/C++.
3. Powerful: The LuaScript engine allows you to go beyond the limitations of the Windows Installer engine.
To run a LuaScript in MSI Factory in immediate mode, select Actions > Custom Actions from the menu. Then click the Add button and select Run LuaScript from the menu. Now simply specify the location of your LuaScript file. The LuaScript file (".lua" file) will be included in the Binary table of your MSI file. You can then schedule the execution of the action as you would any other Custom Action.
If you want to run a LuaScript as a deferred custom action, you will have to do it a bit differently:
- Add a new Call DLL custom action
- Specify "Internal binary" as the Location and then for the Source file specify:
$(var.MSIFactoryFolder)\Custom Actions\LuaScript.dll
- That will make the LuaScript DLL that is in MSI Factory's "Custom Actions" folder to be included with your install.
- In the DLL function name field, specify: RunLuaScript
- Now go to the Attributes tab and specify an ID. Take note of the ID that is used for the Custom action.
- Schedule the custom action as desired.
- Create a Set Property custom action.
- Set the Property field to the ID of the Call DLL custom action that you just created.
- Set the Value field to the location of the file on the
end user's system when the Call DLL custom action is run. You are responsible
for bringing along and making the external .lua file available at the
time that the Call DLL custom action is run.
- You can pass extra data to the lua script which will be available via
the "CustomActionData" property. To do this simply use the pipe
(|) character to delimit your value, e.g.: "[#MyLuaScript.lua]|My
Value|My Other Value". The first item in the delimited string must
be the path to your .lua file. You will receive the "CustomActionData"
value "as is", and are responsible for parsing it to get your
extra data.
- The Set Property custom action can be run in immediate mode. But it must be run BEFORE the Call DLL custom action is run.
Remember that when you run a custom action in deferred mode there is a very limited amount of information about the install available to you. Many of the MSI actions in the LuaScript will not work properly for that reason when running in deferred mode. You should only run LuaScript in deferred mode when you need to affect a file or other system change that is made by the installer.
Although using LuaScript is very convenient, there are a few principles that you should be aware of when using it:
1. Do not use LuaScript to accomplish the same functionality that is available through standard Windows Installer actions. For example, in general, there is no need to use LuaScript to make changes to the user's Registry since Windows Installer has built-in actions to accomplish that task.
2. Provide uninstall LuaScript to undo system changes that you make. If your LuaScript makes changes to the system during installation, make sure to create a LuaScript that "un-does" the changes during a remove operation.
3. The Run LuaScript action only runs as an immediate custom action. Therefore you should be aware that immediate custom actions run under the user account. As such, you may not have write access to many system locations.