InstallShield 2018
Project • This information applies to the following project types:
| • | Basic MSI |
| • | DIM |
| • | InstallScript MSI |
| • | Merge Module |
The Managed Method Definition panel in the Custom Action Wizard is where you specify arguments for the method that your managed assembly custom action should call. You can also specify this information on the Method Signature dialog box.
Using the Default Method Signature
If you use the default method signature, the custom action handles methods with up to one parameter. If the method takes a parameter, it is passed the MsiHandle, as well as any return type. If the method returns an integer, this integer is passed directly to Windows Installer. Therefore, if a method returns integer 1603 (ERROR_INSTALL_FAILURE) in this scenario, the installation aborts.
For more information, see Custom Action Return Values in the Windows Installer Help Library.
Using a Custom Method Signature for an Immediate Custom Action
If you use a custom method signature, the custom action calls the method with the arguments that you specified. If the value of a parameter is a Windows Installer property and the custom action is set for immediate execution, the method stores any by-reference and out parameter values in the passed properties. In addition, the custom action converts the return value to a string and stores it in the return property. If no return property is specified, the return value is ignored.
Note that if you use a custom signature, the custom action’s return value is not passed to Windows Installer. However, if the managed code throws an unhandled exception, the custom action returns ERROR_INSTALL_FAILURE to Windows Installer. Therefore, in order for the custom action to indicate failure and for Windows Installer abort the installation, the managed code must throw an unhandled exception.
Using a Custom Method Signature for a Deferred, Commit, or Rollback Custom Action
Deferred, commit, and rollback custom actions have access to only some of the built-in Windows Installer properties: CustomActionData, ProductCode, and UserSID. Therefore, if you use a custom method signature and you want your managed assembly custom action to access or pass any other properties during deferred, commit, or rollback execution, you must pass them through the CustomActionData property. Note the following guidelines for deferred, commit, and rollback managed assembly custom actions:
| • | Custom signatures that pass properties need to have their values passed in as CustomActionData in the following format: |
PROPERTYNAME="Property Value"
Separate multiple property name–property value pairs with a space, as in the following example:
PROPERTYNAME1="Property Value 1" PROPERTYNAME2="Property Value 2"
| • | If the managed assembly for your deferred, commit, or rollback custom action is installed with the product, use CustomActionData to identify the location of the managed assembly, and use the following format: |
#filekey.dll="location of assembly"
For the “location of assembly” portion, use the format [#filekey.dll].
| • | If the path for the managed assembly references one or more properties, use CustomActionData to pass each of the properties and their corresponding values. |
| • | Consider using CustomActionData to pass the following property and value: |
IS_CLR_VERSION="[IS_CLR_VERSION]"
If run-time issues occur because your custom action attempts to load the wrong version of the .NET Framework to run your managed code, you can have end users set the value of the IS_CLR_VERSION property at the command line when they run your installation. For deferred, commit, and rollback managed-code custom actions, IS_CLR_VERSION must be passed to CustomActionData in order for end users to use this run-time override. To learn more about the IS_CLR_VERSION property, see Run-Time Requirements for Managed-Code Custom Actions.
Specifying Parameter Values for a Custom Method Signature
If you use a custom method signature, you can enter any of the following types of values for a parameter:
| • | A single property that is enclosed within square brackets—for example, [ProductName]. Note that immediate-mode managed assembly custom actions can update ref and out parameters. InstallShield does not support combining multiple properties or mixing properties with strings for a parameter value. |
| • | A literal—for example, a string such as the number 1 or 1603. |
| • | An explicit string that is enclosed within quotation marks—for example, “My Project Name-1”. |
| • | The variable MsiHandle, which indicates the installation handle. |
At run time, after a property has been resolved or a string has been isolated from within its quotation marks, the custom action attempts to convert the string to an instance of the type of the method’s appropriate parameter. A parameter of type String is passed as is, and all normal numeric types are handled by calling the public static Parse(string) method to turn the string into the type. In addition, the custom action calls any type’s public static Parse(string) method and uses the return value as the passed parameter value. IntPtr is also handled despite the lack of a Parse method.
See Also
Using 32-Bit vs. 64-Bit Managed-Code Custom Actions
InstallShield 2018 Help LibraryJanuary 2018 |
Copyright Information | Flexera |