Microsoft Windows Installer SDK

CustomActions (benutzerdefinierte Aktion(en))

Cuando el instalador de Windows procesa el script de instalación, también crea un script de reversión. Además del script de reversión, el instalador guarda una copia de cada archivo que borra durante la instalación. Estos archivos se guardan en un directorio oculto del sistema. Una vez finalizada la instalación, el script de reversión y los archivos guardados se eliminan. Si una instalación no tiene éxito, el programa de instalación intenta deshacer los cambios realizados durante la instalación y restaurar el ordenador a su estado original.

Deferred Execution Custom Actions

El propósito de una acción personalizada de ejecución retardada es retrasar la ejecución de un cambio en el sistema hasta que se ejecute el script de instalación. Esto es diferente de una acción personalizada normal o una acción por defecto, donde el instalador ejecuta la acción inmediatamente cuando se produce en una tabla de secuencia o cuando se llama a MsiDoAction. Una acción diferida personalizada permite al autor de un paquete especificar operaciones del sistema en un punto específico dentro de la ejecución del script de instalación. El instalador no realiza una acción diferida personalizada en el momento de procesar la secuencia de instalación. En su lugar, el instalador escribe la acción personalizada en el script de instalación. Las acciones personalizadas de ejecución diferida deben venir después de InstallInitialize y antes de InstallFinalize en la secuencia de acciones.

Las acciones personalizadas que cambian directamente el sistema o emiten comandos a otros servicios del sistema no siempre pueden deshacerse mediante una reversión. Una acción de reversión personalizada es una acción que el instalador realiza sólo durante una reversión de la instalación, y su propósito es deshacer una acción personalizada que hizo cambios en el sistema.

Definición de una CustomAction (definición de tipo)

En el MSDN se describe el campo Type de la siguiente manera "Un campo de bits de bandera (otra palabra para máscara de bits) que especifica el tipo básico de acción y opciones personalizadas".

Column Type Key Nullable
Action Identifier Y N
Type Integer N N
Source CustomSource N Y
Target Formatted N Y
ExtendedType DoubleInteger N Y

Así que para mi CustomAction, primero necesito determinar el tipo base. En el ejemplo sería el valor 34 (EXE file having a path referencing a directory). Una Deferred CustomAction es una opción de ejecución dentro del script y como debe ejecutarse en el contexto del sistema, elegimos el valor 3072 (msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate). Las CustomActions deben ejecutarse de forma sincronizada y no abortar toda la instalación aunque se produzca un error. Añadimos el valor 64 (Custom Action Return Processing Options). Suma estos tres valores determinados 34 + 3072 + 64 = 3170 - et voilà.


Custom Action Sources

Custom action source Associated custom action types
Custom action stored in the Binary table. Custom Action Type 1, Custom Action Type 2, Custom Action Type 5, Custom Action Type 6
Custom action copied during installation. Custom Action Type 17, Custom Action Type 18, Custom Action Type 21, Custom Action Type 22
Custom action referencing a directory. Custom Action Type 34
Custom action referencing a property. Custom Action Type 50, Custom Action Type 53, Custom Action Type 54
Custom action stored as literal script code in database table. Custom Action Type 37, Custom Action Type 38
Custom action displaying an error message. Custom Action Type 19

The basic types of custom actions

Custom action type Type Source Target
1
DLL file stored in a Binary table stream.
Key to Binary table. DLL entry point.
2
EXE file stored in a Binary table stream.
Key to Binary table. Command-line string.
5
JScript file stored in a Binary table stream.
Key to Binary table. An optional JScript function that can be called.
6
VBScript file stored in a Binary table stream.
Key to Binary table. An optional VBScript function that can be called.
17
DLL file that is installed with a product.
Key to File table. DLL entry point.
18
EXE file that is installed with a product.
Key to File table. Command-line string.
19
Displays a specified error message and returns failure, terminating the installation.
Blank Formatted text string. The literal message or an index into the Error table.
21
JScript file that is installed with a product.
Key to File table. An optional JScript function that can be called.
22
VBScript file that is installed with a product.
Key to File table. An optional VBScript function that can be called.
34
EXE file having a path referencing a directory.
Key to Directory table. This is the working directory for execution. The Target column is formatted and contains the full path and name of the executable file followed by optional arguments.
35
Directory set with formatted text.
A key to the Directory table. The designated directory is set by the formatted string in the Target field. A formatted text string.
37
JScript text stored in this sequence table.
Null A string of JScript code.
38
VBScript text stored in this sequence table.
Null A string of VBScript code.
50
EXE file having a path specified by a property value.
Property name or key to Property table. Command-line string.
51
Property set with formatted text.
Property name or key to the Property table. This property is set by the formatted string in the Target field. A formatted text string.
53
JScript text specified by a property value.
Property name or key to Property table. An optional JScript function that can be called.
54
VBScript text specified by a property value.
Property name or key to Property table. An optional VBScript function that can be called.

Custom Action In-Script Execution Options

Puede utilizar las siguientes banderas para especificar la ejecución de acciones personalizadas dentro del script. Estas opciones copian el código de la acción al script de ejecución, rollback o commit. Para establecer una opción, añada el valor de esta tabla al valor del campo Tipo de la tabla CustomAction.

Term Description
(none) Hexadecimal: 0x00000000
Decimal: 0
Immediate execution.
msidbCustomActionTypeInScript Hexadecimal: 0x00000400
Decimal: 1024
Queues for execution at scheduled point within script. This flag designates that this is a deferred execution custom action.
msidbCustomActionTypeInScript +
msidbCustomActionTypeRollback
Hexadecimal: 0x00000400 + 0x00000100
Decimal: 1280
Queues for execution at scheduled point within script. Executes only upon an installation rollback. This flag designates that this is a rollback custom action.
msidbCustomActionTypeInScript +
msidbCustomActionTypeCommit
Hexadecimal: 0x00000400 + 0x00000200
Decimal: 1536
Queues for execution at scheduled point within script. Executes only upon install commit. This flag designates that this is a commit custom action.
msidbCustomActionTypeInScript +
msidbCustomActionTypeNoImpersonate
Hexadecimal: 0x00000400 + 0x00000800
Decimal: 3072
Queues for execution at scheduled point within script. Executes with no user impersonation. Runs in system context.
msidbCustomActionTypeInScript +
msidbCustomActionTypeNoImpersonate +
msidbCustomActionTypeRollback
Hexadecimal: 0x00000400 + 0x00000800 + 0x00000100
Decimal: 3328
Queues for execution at scheduled point within script. Executes with no user impersonation. Runs in system context. This flag combination designates that this is a rollback custom action.
msidbCustomActionTypeInScript +
msidbCustomActionTypeNoImpersonate +
msidbCustomActionTypeCommit
Hexadecimal: 0x00000400 + 0x00000800 + 0x00000200
Decimal: 3584
Queues for execution at scheduled point within script. Executes with no user impersonation. Runs in system context. This flag combination designates that this is a commit custom action.
msidbCustomActionTypeTSAware +
msidbCustomActionTypeInScript
Hexadecimal: 0x00000400 + 0x00004000
Decimal: 17408
Queues for execution at the scheduled point within script. Executes with user impersonation. Runs with user impersonation during per-machine installs on a server running the Terminal Server role service. Normal deferred execution custom actions, without this attribute, run with no user impersonation on a terminal server during per-machine installations. This attribute has no effect if the action also has the msidbCustomActionTypeNoImpersonate attribute.
msidbCustomActionTypeTSAware +
msidbCustomActionTypeInScript +
msidbCustomActionTypeRollback
Hexadecimal: 0x00000400 + 0x00004000 + 0x00000100
Decimal: 17664
Queues for execution at the scheduled point within script. Run only upon an installation rollback. Execute with user impersonation. Runs with user impersonation during per-machine installs on a terminal server.
msidbCustomActionTypeTSAware +
msidbCustomActionTypeInScript +
msidbCustomActionTypeCommit
Hexadecimal: 0x00000400 + 0x00004000 + 0x00000200
Decimal: 17920
Queues for execution at the scheduled point within script. Runs only upon an install commit. Executes with user impersonation. Runs with user impersonation during per-machine installs on a terminal server.

Custom Action Return Processing Options

Constant Description
(none) Hexadecimal: 0x00000000
Decimal: 0
A synchronous execution that fails if the exit code is not 0 (zero). If the flag msidbCustomActionTypeContinue is not set, then the custom action must return one of the return values that is described in Custom Action Return Values.
msidbCustomActionTypeContinue Hexadecimal: 0x00000040
Decimal: +64
A synchronous execution that ignores exit code and continues.
msidbCustomActionTypeAsync Hexadecimal: 0x00000080
Decimal: +128
An asynchronous execution that waits for exit code at the end of the sequence. This option cannot be used with Concurrent Installations, Rollback Custom Actions, or Script Custom Actions.
msidbCustomActionTypeAsync + msidbCustomActionTypeContinue Hexadecimal: 0x00000040 + 0x00000080
Decimal: +192
An asynchronous execution that does not wait for completion. Execution continues after Windows Installer terminates. This option can only be used with the EXE type custom actions that is, executable files. All other types of custom actions can be asynchronous only within the install session, and must end for the installation to terminate. This option cannot be used with Concurrent Installations.

Custom Action Hidden Target Option

Constant Description
(none) Hexadecimal: 0x00000000
Decimal: 0
The installer may write the value in the Target column of the CustomAction table into the log file.
msidbCustomActionTypeHideTarget Hexadecimal: 0x2000
Decimal: 8192
The installer is prevented from writing the value in the Target column of the CustomAction table into the log file. The CustomActionData property is also not logged when the installer executes the custom action. Because the installer sets the value of CustomActionData from a property with the same name as the custom action, that property must be listed in the MsiHiddenProperties Property to prevent its value from appearing in the log.

Custom Action Return Values

Return value Description
ERROR_FUNCTION_NOT_CALLED Action not executed.
ERROR_SUCCESS Completed actions successfully.
ERROR_INSTALL_USEREXIT User terminated prematurely.
ERROR_INSTALL_FAILURE Unrecoverable error occurred.
ERROR_NO_MORE_ITEMS Skip remaining actions, not an error.
Tenga en cuenta que las acciones personalizadas que son ejecutables deben devolver 0 para tener éxito. El instalador interpreta cualquier otro valor de retorno como un fallo. Para ignorar los valores de retorno, establezca la bandera del bit msidbCustomActionTypeContinue en el campo Type de la tabla CustomAction.

Tenga en cuenta también que Windows Installer traduce los valores de retorno de todas las acciones cuando escribe el valor de retorno en el archivo de registro. Por ejemplo, si el valor de retorno de la acción aparece como 1 en el archivo de registro, significa que la acción devuelve ERROR_SUCCESS.