Microsoft Windows Installer SDK

Deferred Custom Action

Lorsque le programme d'installation Windows traite le script d'installation, il crée également un script de retour en arrière. En plus du script de retour en arrière, le programme d'installation enregistre une copie de chaque fichier qu'il supprime pendant l'installation. Ces fichiers sont conservés dans un répertoire système caché. Une fois l'installation terminée, le script de retour en arrière et les fichiers sauvegardés sont supprimés. Si l'installation échoue, le programme d'installation tente d'annuler les modifications apportées pendant l'installation et de restaurer l'ordinateur dans son état d'origine.

Deferred Execution Custom Actions

L'objectif d'une action personnalisée à exécution différée est de retarder l'exécution d'un changement de système jusqu'à ce que le script d'installation soit exécuté. Ceci est différent d'une action personnalisée ordinaire ou d'une action par défaut, où le programme d'installation exécute l'action immédiatement lorsqu'elle apparaît dans un tableau de séquences ou lorsque MsiDoAction est appelé. Une action personnalisée à exécution différée permet à un auteur de paquet de spécifier des opérations système à un moment précis de l'exécution du script d'installation. Le programme d'installation n'effectue pas d'action différée personnalisée au moment où la séquence d'installation est traitée. Au lieu de cela, le programme d'installation écrit l'action personnalisée dans le script d'installation. Les actions d'exécution différée personnalisées doivent venir après InstallInitialize et avant InstallFinalize dans la séquence d'actions.

Les actions personnalisées qui modifient directement le système ou qui envoient des commandes à d'autres services du système ne peuvent pas toujours être annulées par un retour en arrière. Une action de retour en arrière personnalisée est une action que le programme d'installation n'exécute que lors d'un retour en arrière de l'installation, et son but est d'annuler une action personnalisée qui a apporté des modifications au système.

Définition d'une CustomAction (définition du type)

Dans le MSDN, le champ Type est décrit de la manière suivante : "Un champ de bits d'indicateur (autre mot pour Bitmask) spécifiant le type de base de l'action personnalisée et des options."

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

Donc, pour mon CustomAction, je dois d'abord déterminer le type de base. Dans l'exemple, il s'agirait de la valeur 34 (EXE file having a path referencing a directory). Une Deferred CustomAction est une option d'exécution In-Script et parce qu'elle doit s'exécuter dans le contexte du système, nous choisissons la valeur 3072 (msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate). Nous voulons que les CustomActions s'exécutent de manière synchrone et n'interrompent pas l'installation entière même si une erreur se produit. Nous ajoutons la valeur 64 (Custom Action Return Processing Options). Additionnez ces trois valeurs déterminées 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

Vous pouvez utiliser les drapeaux suivants pour spécifier l'exécution in-scriptum des actions personnalisées. Ces options copient le code de l'action dans le script d'exécution, de retour en arrière ou de validation. Pour définir une option, ajoutez la valeur de ce tableau à la valeur du champ Type du tableau 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.
Notez que les actions personnalisées qui sont exécutables doivent retourner 0 pour réussir. L'installateur interprète toute autre valeur de retour comme un échec. Pour ignorer les valeurs de retour, définissez l'indicateur binaire msidbCustomActionTypeContinue dans le champ Type de la table CustomAction.

Notez également que Windows Installer traduit les valeurs de retour de toutes les actions lorsqu'il écrit la valeur de retour dans le fichier journal. Par exemple, si la valeur de retour de l'action apparaît comme 1 dans le fichier journal, cela signifie que l'action renvoie ERROR_SUCCESS.