The "MajorUpgrade" Command |
This command allows you to define what products should be removed when the installation of this product begins (applications to be uninstalled are identified by their "UpgradeCode" property and perhaps other attributes such as their version number or language).
You can use this command instead of or in addition to specifying the "List of UpgradeCodes" in the ".ver" file.
A major update ensures that you will not have to worry about what is "allowed" in "minor upgrades" etc, each of your builds can work exactly the same way without requiring any knowledge of what was done for the last install...
Most people will probably use the "Guid.UpgradeCode" keyword to assign a unique upgrade code to their product.
This command takes these parameters:
The delimiters accepted are space, comma and semicolon.
This products installation will not proceed if the uninstallation of a product fails.
Each upgrade code can be supplied in a number of formats:
The name is included in the HTML report.
This value is used to specify the minimum and maximum versions of the product to be upgraded etc.
This is the default configuration (for "DEFAULT"):
;--- See the "config" parameter (which defaults to "DEFAULT") --------------- #define? MAJORUPGRADE_DEFAULT_VALIDATE NEW ;;Validation performed when row inserted (Don't allow overwrite of info). #define? MAJORUPGRADE_DEFAULT_REMOVE ALL #define? MAJORUPGRADE_DEFAULT_COMMENT ;;For html report #define? MAJORUPGRADE_DEFAULT_VERSION_MIN #define? MAJORUPGRADE_DEFAULT_VERSION_MAX #define? MAJORUPGRADE_DEFAULT_LANGUAGE #define? MAJORUPGRADE_DEFAULT_PREFIX UPGRADECODE.#. ;;# = unique number #define? MAJORUPGRADE_DEFAULT_PREFIX_MACRO <$MajorUpgrade_DEFAULT_PREFIX> #define? MAJORUPGRADE_DEFAULT_PREFIX_VBVARIABLE <$MajorUpgrade_DEFAULT_PREFIX> #define? MAJORUPGRADE_DEFAULT_PREFIX_GUID <$MajorUpgrade_DEFAULT_PREFIX> #( #define? MAJORUPGRADE_DEFAULT_ATTRIBUTES (msidbUpgradeAttributesVersionMinInclusive or msidbUpgradeAttributesVersionMaxInclusive or msidbUpgradeAttributesLanguagesExclusive) #)
If they are supplied then they overrode any previously configured values.
When looking for the appropriate configuration for an item such as "VERSION_MIN" the configuration is searched for from (in order):
If you don't understand the above then as always look at the debug output.
MAIN OPTIONS |
;--- The HTML (summary row) Related Options --------------------------------- #( '<br>' #define? MAJORUPGRADE_HTMLSUMMROW_DESC Any products with these upgrade codes are automatically removed when installing this package #) #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_REMOVE N #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_REQUESTED_AT Y #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_PROPERTY N #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_MIN_VERSION Y #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_MAX_VERSION Y #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_LANGUAGE Y #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_REMOVE N #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_ATTRIBUTES N #define? MAJORUPGRADE_HTMLSUMMROW_DETAIL_SHOW_COMMENT Y
EXAMPLES |
;--- Define UpgradeCode for product "ProductX" (major version 1) ------------ #define ProductX.Version1 {11111111-1111-1111-1111-111111111111} #define ProductX.Version1_VERSION_MIN 1.00.0000 #define ProductX.Version1_VERSION_MAX 1.99.9999 #define ProductX.Version1_PROPERTY MY_CONFIGURED_PROPERTY_NAME ;--- Define UpgradeCode for product "ProductY" (any version) ---------------- #define ProductY {11111111-1111-1111-1111-333333333333} ;--- Define UpgradeCode via vbscript variable ------------------------------- #define FromVbVariable_PROPERTY MY_UPGRADE_CODE_FROM_VB_VARIABLE ;;Override property name for this GUID #define {21AB9EAB-A161-45EA-9272-704EEC8175F9}_PROPERTY MY_UPGRADE_CODE_21AB9EAB dim FromVbVariable : FromVbVariable ="{99999999-9999-9999-9999-999999999999}" <$MajorUpgrade "{21AB9EAB-A161-45EA-9272-704EEC8175F9} ProductX1.00.0002 ProductX1.00.0003 {22222222-2222-2222-2222-222222222222} =FromVbVariable" comment="test this command"> <$MajorUpgrade "{66666666-A161-45EA-9272-666666666666}" VERSION_MIN="1.23.4567" comment="Test passing some 'Upgrade' table parameters">
The UpgradeCodes (version file keyword) can be passed GUIDS in the same way.
Major Upgrade Supporting Code |
The following code is an extract from "COMPANY.MMH" which:
#define? COMPANY_AUTO_UNINSTALL_VIA_UPGRADE_TABLE Y #if ['<$COMPANY_AUTO_UNINSTALL_VIA_UPGRADE_TABLE>' = 'Y'] ;--- Look for older/newer versions of the same package (group) ----------- #define UpgradeCode_PROPERTY UC_OURSELVES ;;Use this property in "Upgrade" table entry <$MajorUpgrade "=UpgradeCode" Comment=^We upgrade any version of this product!^> ;;Use value in VB variable ;--- Any EXTRA upgrade codes to be handled? ------------------------------ #if ['<$ProdInfo.UpgradeCodes>' <> ''] <$MajorUpgrade "<$ProdInfo.UpgradeCodes>" comment="Defined by .ver file (KeyWord: UpgradeCodes)"> #endif ;--- Install MSI AFTER complete uninstallation of older ------------------ #define? COMPANY_RemoveExistingProducts_HOOK_BEFORE_MOVING #define? COMPANY_RemoveExistingProducts_HOOK_AFTER_MOVING #define? COMPANY_RemoveExistingProducts_SEQ InstallValidate-InstallInitialize #( ;--- Allow easy overiding/removal of this step ---------------------- #define? COMPANY_MOVE_RemoveExistingProducts <$Table "InstallExecuteSequence"> ;--- Move to desired location ----------------------------------- dim RepSeq : RepSeq = GetSeqNumber("InstallExecuteSequence", "<$COMPANY_RemoveExistingProducts_SEQ>", 1) <$Row Action="RemoveExistingProducts" *Sequence="RepSeq"> <$/Table> #) <$COMPANY_RemoveExistingProducts_HOOK_BEFORE_MOVING> <$COMPANY_MOVE_RemoveExistingProducts> <$COMPANY_RemoveExistingProducts_HOOK_AFTER_MOVING> #endif
Optionally Generating a Random Upgrade code |
While I don't neccessarily recommend this the following code place into a common header file will modify the normal behavour so that you can still supply a fixed GUID (via version file or macro) but if not supplied a new unique GUID will be randomly generated for you:
;---------------------------------------------------------------------------- ;--- If Upgrade GUID not supplied want a random one ------------------------- ;---------------------------------------------------------------------------- #NextId #( '<?NewLine>' #define COMPANY_SET_PROPERTY_UPGRADECODE ;--- Simple validation --------------------------------------------------- #if ['<$COMPANY_UPGRADE_CODE_QUALIFIER>' <> ''] #error ^Currently don't support use of a "COMPANY_UPGRADE_CODE_QUALIFIER"...^ #endif ;--- Generate a random GUID unless we already have one ------------------- #RexxVar @@UcMacName = '<$VER_PRODINFO_GUID_PREFIX>UpgradeCode' dim UpgradeCode ;;VBS variable #if Defined(@@UcMacName) = 'N' ;--- Generate Random GUID ------------------------------------------- #info "UpgradeCode GUID randomly generated..." UpgradeCode = GuidMake("UpgradeCode") ;;VBS to generate random GUID #else ;--- Use value supplied (probably in ".VER" file -------------------- #info "UpgradeCode: <$[@@UcMacName]>" UpgradeCode = "<$[@@UcMacName]>" ;;GUID supplied as literal VbsReturnGuid "UpgradeCode", UpgradeCode ;;Ensure HTML report can access this information #endif <$Property "UpgradeCode" *Value="UpgradeCode"> ;;Use GUID "calculated" above #)