Windows Installer
CustomActions (benutzerdefinierte Aktion(en))
Wenn der Windows Installer das Installationsskript verarbeitet, erzeugt es gleichzeitig ein Rollback-Skript. Zusätzlich zum Rollback-Skript speichert das Installationsprogramm eine Kopie jeder Datei, die es während der Installation löscht. Diese Dateien werden in einem verborgenen Systemverzeichnis aufbewahrt. Sobald die Installation abgeschlossen ist, werden das Rollback-Skript und die gespeicherten Dateien gelöscht. Wenn eine Installation nicht erfolgreich ist, versucht das Installationsprogramm, die während der Installation vorgenommenen Änderungen rückgängig zu machen und den ursprünglichen Zustand des Computers wiederherzustellen.
Deferred Execution Custom Actions
Der Zweck einer benutzerdefinierten Aktion mit verzögerter Ausführung besteht darin, die Ausführung einer Systemänderung auf den Zeitpunkt der Ausführung des Installationsskripts zu verschieben. Dies unterscheidet sich von einer regulären benutzerdefinierten Aktion oder einer Standardaktion, bei der das Installationsprogramm die Aktion sofort ausführt, wenn sie in einer Sequenztabelle oder bei einem Aufruf von MsiDoAction auftritt.
Eine benutzerdefinierte Aktion mit verzögerter Ausführung ermöglicht es einem Paketautor, Systemoperationen an einem bestimmten Punkt innerhalb der Ausführung des Installationsskripts festzulegen. Das Installationsprogramm führt zum Zeitpunkt der Verarbeitung der Installationssequenz keine benutzerdefinierte Aktion mit verzögerter Ausführung aus. Stattdessen schreibt das Installationsprogramm die benutzerdefinierte Aktion in das Installationsskript. Benutzerdefinierte Aktionen mit verzögerter Ausführung müssen nach InstallInitialize und vor InstallFinalize in der Aktionsfolge stehen.
Benutzerdefinierte Aktionen, die das System direkt ändern oder Befehle an andere Systemdienste erteilen, können nicht immer durch ein Rollback rückgängig gemacht werden. Eine benutzerdefinierte Rollback-Aktion ist eine Aktion, die das Installationsprogramm nur während eines Installationsrollbacks ausführt, und ihr Zweck ist es, eine benutzerdefinierte Aktion, die Änderungen am System vorgenommen hat, rückgängig zu machen.
Definition einer CustomAction (Typbestimmung)
In den MSDN wird das Feld Type so erklärt: "A field of flag bits (another word for Bitmask) specifying the basic type of custom action and 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 |
Für meine CustomAction muss ich also erst einmal den Basistyp ermitteln. Im Beispiel wäre es der Wert 34 (EXE file having a path referencing a directory). Eine Deferred CustomAction ist eine In-Script Execution Option und weil diese im System-Kontext ablaufen soll, wählen wir den Wert 3072 (msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate). Die CustomActions sollen synchron ablaufen und selbst bei einem Fehler nicht die gesamte Installation abbrechen. Wir addieren den Wert 64 hinzu (Custom Action Return Processing Options). Diese drei ermittelten Werte zusammenzählen 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
Sie können folgende Flags verwenden, um die skriptinterne Ausführung von benutzerdefinierten Aktionen festzulegen. Diese Optionen kopieren den Aktionscode in das Ausführungs-, Rollback- oder Commit-Skript. Um eine Option festzulegen, fügen Sie den Wert in dieser Tabelle zu dem Wert im Feld Type der Tabelle CustomAction hinzu.| 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. |
Beachten Sie auch, dass Windows Installer die Rückgabewerte von allen Aktionen übersetzt, wenn es den Rückgabewert in die Protokolldatei schreibt. Wenn der Rückgabewert der Aktion beispielsweise als 1 in der Protokolldatei erscheint, bedeutet dies, dass die Aktion ERROR_SUCCESS zurückgibt.