If you have ever created a new Suite project, you may have seen a mysterious build error message that talks about a mode condition and asked yourself, “What the heck is a mode condition and where can I set it?”
To see this error, you can create a new Suite project, add an .exe package and click Build. The output will display the following message:
A Mode condition or a Detection condition is required for the Setup.exe to run correctly. -7223
You will also see a build error saying the package does not contain a detect condition, but this message should be pretty straight forward to decipher.
Now if you add a detection condition to the .exe package—say a file exists of the form c:MyfolderMyfile.file—and then build a release, both errors disappear.
To see what has changed in the setup.xml file that the engine uses at run time, open the setup.xml file that is created in the Interm folder under the current release. It contains something similar to this under the main Setup element:
You can see that the detection condition from the .exe package that was added has been used to form the child elements Install and Maintenance.
Mode Conditions at Run Time
So, what exactly is a mode condition? At run time the new setup engine needs to determine whether the Suite is already installed on the machine. To do this there is a concept of a mode condition, the evaluation of which determines whether we run as a first-time install or maintenance. The mode condition has two child elements, Install and Maintenance; both of these can contain the standard condition syntax. The setup engine evaluates the mode condition early on in the process and runs the first mode that evaluates to true. If no mode condition evaluates to true, the engine encounters an error and the setup aborts.
Mode Conditions at Build Time
By default, the detection conditions from all primary packages are put together to form the mode condition at build time. The mode condition is Install if none of the primary packages’ detection conditions evaluate as true. The mode condition is Maintenance if any of the primary packages’ detection conditions evaluate as true. In this case, the Suite installation runs in maintenance mode if the file MyFile.file exists on the target system in the c:MyFolder location, and first-time install if it does not.
Dependency Packages and Mode Conditions
Dependency packages such as the.NET Framework are not used as part of the mode condition. You probably do not want the presence of the .NET Framework to change whether the install runs as a first-time install. In fact, it was during the design of the autocreated mode conditions that the idea of a primary and dependency package was first discussed.
Special Handling for MSI Packages and Mode Conditions
If you add an MSI package to an otherwise empty Suite project, the detection and mode condition build errors do not occur. This is because the setup engine (together with some build-time processing) has enough information to determine if the MSI package is already installed on the target machine. The engine uses the product and package codes and the version of the MSI (which are written to setup.xml at build) to query the target system and determine if the MSI is already installed. This information is shown in the Eligibility Condition setting for the MSI package. The asterisks are used as placeholders for the MSI package’s product code, package code, and product version; InstallShield replaces these with the actual values in setup.xml at build time.
Similar information is then used in the mode condition. So for any (primary) MSI package, setup.xml contains a line similar to the following as part of the mode condition:
<MsiInstalled ProductCode=”{00221F01-9384-45EC-A627-1F52ECDD873A}” PackageCode=”{E65ADD26-EA54-4269-9760-5465D8FFF2D9}”/>
Essentially the default mode condition says that we will run a first-time install if none of the packages are detected (usually detected means installed) on the target system, and maintenance otherwise.
Custom Mode Conditions at Design Time
The question now is why is there is no UI for this condition and can I set the mode condition manually? The answer to second part is yes! The build code was written in such a way as to allow expert users to manually add a mode condition to the project file and that mode condition is maintained for the built setup.xml. This means if you need to hand craft a custom mode condition, you can open the .issuite file in your favourite text editor and add mode conditions. This effectively turns off the creation of any autogenerated conditions. If you choose this option, what you enter is what you will get; nothing will be added to it at build time. So you will have to ensure the condition meets your requirements for all installation scenarios (first time, maintenance, upgrades, etc). As for why there is no UI, it essentially came down to ease of use. We wanted to keep the Suites as easy to use as possible whilst being as flexible as the initial design had intended. Over the course of the development cycle we came to realize that the new functionality that we were offering came with some complex and most importantly new concepts. We were throwing all kinds of new terminology at you: detection conditions, eligibility conditions, mode conditions, a brand new run-time UI editor with a ton of new settings. So with that in mind, the decision was made to take as much of the burden off you guys and add autohandling for things. So we didn’t add mode conditions to the IDE and instead we autogenerate them from detection conditions. Depending on feedback, we may well opt to add it for future releases. Hopefully we have made Suites easy enough to use so you can get all the benefits without unnecessary headaches.
A quick note about detection conditions for packages that may not be obvious: The detection condition is assumed to change from false before the installation to true after the installation. If this is not the case (for example, if the condition remains false after installation), subsequent maintenance and remove operations will not function as expected. The mode condition and detection condition should normally be in synch to prevent the engine from skipping the package in any given operation. This is something that I have personally been tripped up with and so I would recommend carefully considering the conditions you use for .exe packages. So if you do create your own mode condition, ensure that the detection condition and mode condition agree for each package; you wouldn’t want a package to be detected but the mode result in the Suite running as a first-time install.
The What’s New in InstallShield 2012 Webinar includes more information to help you get started with Suite installations.