Microsoft Windows Installer SDK

Deferred Custom Action

Quando Windows Installer elabora lo script di installazione, crea anche uno script di rollback. Oltre allo script di rollback, l'installatore salva una copia di ogni file che elimina durante l'installazione. Questi file sono tenuti in una directory di sistema nascosta. Una volta completata l'installazione, lo script di rollback e i file salvati vengono cancellati. Se un'installazione non ha successo, il programma di installazione tenta di annullare i cambiamenti fatti durante l'installazione e ripristinare il computer al suo stato originale.

Deferred Execution Custom Actions

Lo scopo di un'azione personalizzata ad esecuzione ritardata è di ritardare l'esecuzione di una modifica al sistema fino all'esecuzione dello script di installazione. Questo è diverso da una normale azione personalizzata o un'azione predefinita, dove l'installatore esegue l'azione immediatamente quando si verifica in una tabella di sequenza o quando viene chiamato MsiDoAction. Un'azione personalizzata ad esecuzione differita permette all'autore di un pacchetto di specificare operazioni di sistema in un punto specifico dell'esecuzione dello script di installazione. Il programma di installazione non esegue un'azione differita personalizzata al momento dell'elaborazione della sequenza di installazione. Invece, l'installatore scrive l'azione personalizzata nello script di installazione. Le azioni personalizzate di esecuzione differita devono venire dopo InstallInitialize e prima di InstallFinalize nella sequenza delle azioni.

Le azioni personalizzate che cambiano direttamente il sistema o emettono comandi ad altri servizi di sistema non possono sempre essere annullate da un rollback. Un'azione di rollback personalizzata è un'azione che l'installatore esegue solo durante un rollback dell'installazione, e il suo scopo è quello di annullare un'azione personalizzata che ha apportato modifiche al sistema.

Definizione di una CustomAction (definizione del tipo)

Nel MSDN, il campo Type è spiegato così: "Un campo di bit di flag (un'altra parola per Bitmask) che specifica il tipo di base dell'azione e delle opzioni personalizzate".

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

Quindi per la mia CustomAction devo prima determinare il tipo di base. Nell'esempio sarebbe il valore 34 (EXE file having a path referencing a directory). Una Deferred CustomAction è un'opzione di esecuzione In-Script e poiché dovrebbe essere eseguita nel contesto del sistema, scegliamo il valore 3072 (msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate). Vogliamo che le CustomActions vengano eseguite in modo sincrono e non interrompano l'intera installazione anche se si verifica un errore. Aggiungiamo il valore 64 (Custom Action Return Processing Options). Sommate questi tre valori determinati 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

Puoi usare i seguenti flag per specificare l'esecuzione in-script di azioni personalizzate. Queste opzioni copiano il codice dell'azione nello script execute, rollback o commit. Per impostare un'opzione, aggiungi il valore in questa tabella al valore nel campo Type della tabella 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.
Si noti che le azioni personalizzate che sono eseguibili devono restituire 0 per avere successo. L'installatore interpreta qualsiasi altro valore di ritorno come un fallimento. Per ignorare i valori di ritorno, impostare il flag msidbCustomActionTypeContinue bit nel campo Type della tabella CustomAction.

Notate anche che Windows Installer traduce i valori di ritorno di tutte le azioni quando scrive il valore di ritorno nel file di registro. Per esempio, se il valore di ritorno dell'azione appare come 1 nel file di log, significa che l'azione restituisce ERROR_SUCCESS.