Microsoft Windows Installer SDK

Deferred Custom Action

Quando o Windows Installer processa o script de instalação, também cria um script de rollback. Para além do guião de rollback, o instalador guarda uma cópia de cada ficheiro que apaga durante a instalação. Estes ficheiros são mantidos num directório de sistema oculto. Uma vez terminada a instalação, o script de rollback e os ficheiros guardados são apagados. Se uma instalação não for bem sucedida, o programa de instalação tenta desfazer as alterações feitas durante a instalação e restaurar o computador ao seu estado original.

Deferred Execution Custom Actions

O objectivo de uma acção personalizada de execução atrasada é atrasar a execução de uma alteração do sistema até que o script do instalador seja executado. Isto é diferente de uma acção personalizada regular ou uma acção padrão, em que o instalador executa a acção imediatamente quando esta ocorre numa tabela de sequência ou quando a MsiDoAction é chamada. Uma acção personalizada de execução diferida permite ao autor de um pacote especificar as operações do sistema num ponto específico dentro da execução do guião de instalação. O instalador não executa uma acção adiada personalizada no momento em que a sequência de instalação é processada. Em vez disso, o instalador escreve a acção personalizada para o guião de instalação. As acções personalizadas de execução diferida devem vir após InstallInitialize e antes de InstallFinalize na sequência de acções.

As acções personalizadas que alteram directamente o sistema ou emitem comandos para outros serviços do sistema nem sempre podem ser desfeitas por um rollback. Uma acção de retrocesso personalizada é uma acção que o instalador executa apenas durante um retrocesso de instalação, e o seu objectivo é desfazer uma acção personalizada que fez alterações ao sistema.

Definição de uma CustomAction (definição de tipo)

No MSDN, o campo Tipo é explicado desta forma: "Um campo de bits de bandeira (outra palavra para Bitmask) especificando o tipo básico de acção e opções 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

Assim, para a minha CustomAction tenho de determinar primeiro o tipo de base. No exemplo, seria o valor 34 (EXE file having a path referencing a directory). Uma Deferred CustomAction é uma opção In-Script Execution e porque deve ser executada no contexto do sistema, escolhemos o valor 3072 (msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate). Queremos que as CustomActions funcionem de forma sincronizada e não abortem toda a instalação, mesmo que ocorra um erro. Acrescentamos o valor 64 (Custom Action Return Processing Options). Juntar estes três 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

Pode utilizar as seguintes bandeiras para especificar a execução de acções personalizadas no guião. Estas opções copiam o código de acção para executar, retroceder, ou comprometer o guião. Para definir uma opção, adicionar o valor nesta tabela ao valor no campo Tipo da tabela 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.

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.

Note-se que as acções personalizadas que são executáveis devem retornar 0 para serem bem sucedidas. O instalador interpreta qualquer outro valor de retorno como uma falha. Para ignorar os valores de retorno, colocar a bandeira msidbCustomActionTypeContinue bit no campo Type da tabela CustomAction.

Note também que o Windows Installer traduz os valores de retorno de todas as acções quando escreve o valor de retorno no ficheiro de registo. Por exemplo, se o valor de retorno da acção aparecer como 1 no ficheiro de registo, significa que a acção devolve ERROR_SUCCESS.