InstallTalk

Selecting Suite Packages to Match the Language of the Target Machine

By Michael Urman

I’ve heard several people ask how to conditionally select a package based on the target machine’s system language. While InstallShield 2012 didn’t include a way to do this with a few mouse clicks, it does allow us to create our own extension condition. Extension conditions can perform any check desired, including randomly returning TRUE or FALSE results (though I would never suggest it). In this article I will walk through using Visual C++ 2010 Express with InstallShield 2012 SP1 to add a set of conditions that check the target machine’s language settings.

I start by creating a new Win32 project, called LangCond, and I select DLL for the application type. Because I want minimal run-time dependencies, I edit the properties under Code Generation, changing Runtime Library to /MTd and /MT instead of /MDd and /MD. Then so the proper functions are exported, I create a module definition file LangCond.def and add it to my Linker Input properties by setting Module Definition File to LangCond.def. Finally it’s time to talk C++. Following the instructions on Extension Conditions, I import COM information from setupsuite.exe and create six functions:

        HRESULT __stdcall User_Validate(IDispatch *pCondition);
        HRESULT __stdcall User_Evaluate(IDispatch *pCondition, VARIANT_BOOL *pbResult);
        HRESULT __stdcall System_Validate(IDispatch *pCondition);
        HRESULT __stdcall System_Evaluate(IDispatch *pCondition, VARIANT_BOOL *pbResult);
        HRESULT __stdcall OS_Validate(IDispatch *pCondition);
        HRESULT __stdcall OS_Evaluate(IDispatch *pCondition, VARIANT_BOOL *pbResult);

I want these conditions to respectively allow a match of a match of a target machine’s user locale (User), its system locale (System), or the default UI language (OS). Since we expect to support versions of Windows before Windows Vista, we will accept Locale IDs  (LCIDs) instead of Language or Culture Names. Thus the condition will take an LCID attribute, where exactly one LCID must be specified. If it matches, the condition will yield a TRUE result; if it doesn’t match, it will yield a FALSE result.

Let’s implement this in LangCond.cpp. Each kind_Validate call should verify the LCID attribute is an integer. Correspondingly each kind_Evaluate call should retrieve the current setting corresponding to the kind of condition (using GetUserDefaultLCID, GetSystemDefaultLCID, or GetSystemDefaultUILanguage), and then verify if the one listed in the LCID attribute matches. We will use wcstoul to implement both checks. To avoid repeating too much code, each validation will call a helper function ValidateLCID; each evaluation will call MatchLCID.

Finally let’s wire it up. Start a new suite project and add a package with an eligibility condition. Also add LangCond.dll as a support file. Then save and close the project, and edit it in your favorite XML editor. Add namespace attribute xmlns:language="LangCond.dll" to the root setup element, attribute Namespace="LangCond.dll" to the Resources/Resource element referencing LangCond.dll, and element <language:User LCID="1033"/> to the eligibility condition on the package. Once you build this suite, the package will run only on machines where the user has selected the US English locale. Swap 1033 out for 1041 to run only on a Japanese locale, or swap the whole language:User element for a language:System element to run only on machines that match the system locale. Or combine both conditions under an <Any> group to run on systems where the user is likely to understand the selected language, under the assumption that both the user and system languages that are selected on target systems reflect languages the user understands.

The attached LangCond.zip file contains the sample source code described here, as well as a built copy of LangCond.dll and a sample suite project. In the sample project, there are three packages. One will run only on a machine with US English settings. The second will run on a machine with Japanese settings. The third will run on either.

You can use the language condition in any condition field, such as in an exit condition to allow installation on a specific locale, or in feature conditions to configure the default selection state of language-related subfeatures. The latter is useful in a feature tree that looks like this (with conditions referenced):

• Dictionaries
  • …
  • English: <Any><language:System LCID="1033"/><language:User LCID="1033"/></Any>
  • French: <Any><language:System LCID="1036"/><language:User LCID="1036"/></Any>
  • German: <Any><language:System LCID="1031"/><language:User LCID="1031"/></Any>
  • …

Note that support for extension conditions is available in InstallShield 2012 SP1. To obtain SP1, see Q201298: InstallShield 2012 Service Pack 1.

ICE Validation: Why Bother? (Part 2 of 2)

By Matt St.Clair Bishop

In my last article I discussed the basics of, and motivation for, validating your MSI packages. You may also be aware of the InstallShield internal consistency evaluators (ICEs) and the InstallShield Best Practice rules which were all authored by Flexera Software; these are essentially custom rules that can be used to check additional facets of your MSIs. In this article we show how we can implement our own custom rules within the standard validation process.

Creating a Custom ICE Rule

The entire Windows Installer technology also enjoys the benefit of being open and hence extensible. As such you are at liberty to write your own rules and add them to the Microsoft rules. Once you have gone to the trouble of creating them, satisfying these custom rules should be just as important as satisfying the original Microsoft evaluators, so let us review making our own.

The best place to start here is to take one of the Microsoft rules as an example and modify it to suit your purpose. Most all of the supplied rules in DARICE.CUB are in a DLL format which makes them impossible to refit; however, ICE08, ICE09, ICE32, and ICE61 are available as VBScript which means they can be extracted from the Binary table, modified and reinserted as new rules.

This image shows the modification to the top part of one of those VBScripts to create a rule which checks the UpgradeCode of the MSI and ensures it has been changed from that value in the MSI template. Apart from the modifications of the script function name and descriptions, very little has been changed here, although near the bottom we are checking for existence of the Property table. Since the Property table is a mandatory table, this is technically unnecessary in this case but it does allow you to ensure a table exists before you inspect it. This is good practice, especially since the more recent versions of InstallShield drop empty tables, so you should not assume all your tables will always exist.

The second part of this script is the business end and begins with an OpenView method being called on the Database object. The SQL syntax selects the Property and Value column entries of the row called UpgradeCode from the Property table. As with any SQL select view, we must execute it before we attempt to fetch records out of it. Between the Execute and the Fetch, though, there is a little error checking. Failure at this point often points to the SQL statement not correctly matching the SQL schema.

After the Fetch we ensure the record is not empty (although the UpgradeCode should exist it may not and in that case we need not check its value). Then we proceed to inspect the first nine characters of the value. Notice how we refer to the fields in the select statement: by index number matching their position in the SQL select statement.

In this case finding the record with these characteristics is an error condition, so we flag the error by posting a message with the correct parameters. These are crucial so let us review them in a little more detail.

recInfo.StringData(0) = "ICE1007" & Chr(9) & "1" & Chr(9)& "This package contains the UpgradeCode of the repackaging template, the GUID must be 'spun'" & Chr(9) & "" & Chr(9) & "Property" & Chr(9) & "Value" & Chr(9) & "[1]"

The record has multiple parts delimited by the tab character Chr(9). The first part denotes the rule name. The second “1” denotes an error, “2” is a warning. Then there is a description of the issue and suggestion of the resolution. The next part here is empty but could be used to point to a URL for a more detailed external explanation. The last three parts locate the error by Table, Column and Row; you can equate this to a Latitude, Longitude and Altitude of the problem. Note however that the Row value is not and cannot be coded directly into this message since the message doesn’t know which row the problem lies in. Instead it refers to “[1]” which in this case matches the parameter index from the earlier select statement. This bit of the record is really worth doing correctly since it then allows the operator to double-click on the error message and jump to the error automatically.

Using Your Custom ICE Rules File

Once you have created the new VBScript containing your custom rule code, you insert it back into the Binary table of your DARICE.CUB with a different name. A reference must also be made in the CustomAction table to refer it and then a new row added to the “_ICESequence” table. Your final step is to use it from within InstallShield. From the Build -> Validate menu option you are able to browse for a new validation module (.cub).

When you have selected it once, it will conveniently appear in the Recent Validation Modules list at the bottom of that same Validate submenu.

Selecting the option will run your custom rules along with any existing rules, displaying errors and warnings as if they were native tests.

The Problem with ICE Rules

So we have been able to demonstrate how custom checks or business logic could be incorporated into any quality assurance process. We could leave it at that and move on, but if we could understand what is wrong with this seemingly useful approach perhaps we could improve even on this.

The main problem with the ICE rules is that they are nothing more than what their name suggests: evaluators. They go to great lengths to detect inconsistencies in your MSI (some of them containing hundreds of lines of code); however, they do nothing to resolve the problem for you. This is unfortunate since they know exactly where the problems lie and apart from a rather dry error message, they leave you to solve the issues on your own.

Another problem with the ICE rules is that there is no clearly defined line where we can say these rules are important to deployment or functionality and these are not so important. They are classified into warnings, errors and even failures but these do not directly translate into whether or not you will have installation difficulty. Usually the best advice is that errors and failures should not be tolerated in an MSI, but warnings can often be ignored, but even this approach has drawbacks. For instance it is possible to distribute and even use a product that has errors and failures. Many software vendors are less than conscientious when it comes to MSI validation. There are even cases where a package that has nothing but warnings will not be able to deploy, install or function correctly.

Hence the dividing line between what we fix and what we tolerate is crooked and in the absence of any industry standard on what should be fixed, we are left with the rather woolly advice as given above: Fix all errors and failures and as many warnings as you have time for.

There Must Be a Better Solution

The obvious extension to the error flagging phase of the ICE validation is the error correction phase, which has usually been a manual process. Once we have been around this iterative loop a number of times it soon becomes tedious and prone to being ignored or forgotten. Different validation operators may have different interpretations as to what needs fixing and what doesn’t. Even the same validation operator just before leaving for vacation may have a different opinion as to which issues need to be fixed and which do not. A systematic automated approach is required to reduce the human element during the cleanup process.

The mission statement of such an automated tool would be: If you know what is wrong and you can fix it then do so. Such a script would check a particular facet of the MSI based perhaps on an ICE rule or best practice and loop through the relevant tables seeking a problem. Once an issue has been identified, it would be resolved automatically if it can. The automated procedure would mean that hundreds of errors or warnings can be corrected in seconds, accurately, without the need for human intervention or specialised knowledge. The important thing to note here is that having built a custom ICE rule you have done 80% of the work in creating an automated fix.

Such resolution scripts exist today, I call them Manipulating Internal Consistency Evaluators (MICE), and in my next article we will create one from scratch, step by step.

ICE Validation: Why Bother? (Part 1 of 2)

By Matt St.Clair Bishop

The Microsoft Windows Installer format is a powerful and robust installation technology but, as is often the case in life, ultimate power does not come without certain responsibilities.

Validation Is Your Responsibility

The MSI database is often likened to the SQL database. Indeed when using the Windows Installer automation interface, the syntax statements are very SQL like, although it is not a full SQL implementation. Therein lies the problem; a full implementation of a relational database within the MSI file would have made the engine too large. Remember the first version had to be distributed on a 1.44Mb floppy disk. This means things like foreign key relationships are not being checked on entry, which in turn means the MSI tables, rows and columns can hide all manner of inconsistent entries. To counter this we validate the built MSI package.

Validation is not new by any means. It predates Windows Installer, though you may not have realised. Before the MSI tables structure, installations were generally controlled by a script which was, at least in part, compiled into an executable. As part of this compilation, the syntax of the script is checked. It was a mandatory part of building the installer and essentially is validation.

The Windows Installer equivalent is called validation and uses a slightly modified MSI file with the extension .CUB (pronounced cube) to hold a number of checking routines known as Internal Consistency Evaluator rules (ICE rules). Collections of these rules come in slightly different varieties covering logo compliance for Windows 2000, Vista and XP as well as the full suite of rules which includes all tests.

Validation can be done within the InstallShield 2012 tool from the build menu as well as from within AdminStudio tools such as Application Manager, Conflict Solver and Package Expert.

If the validation options are not available on your build menu, either you have not yet built the package or the type of validation is not applicable to the type of project you are developing.

Updating the Existing ICE Rules for Windows 7

Although these ICE rules have been around since the inception of Windows Installer, some of the newer innovations have somewhat bypassed the older rule sets you may still be using. You may well have seen this being reported:

ICE27  ERROR  Unknown action: 'MsiConfigureServices' of InstallExecuteSequence table. Not a standard action and not found in CustomAction or Dialog tables

It says that the action MsiConfigureServices is unknown. Although it is a standard action “now” it is an extension of the standard services tables which became available in Windows Installer v5.0. Or perhaps you have seen this one:

ICE45  WARNING   Row 'ReadyToInstall.InstallNow' in table 'Control' has bits set in the 'Attributes' column that are reserved. They should be 0 to ensure compatibility with future installer versions.

It says that the InstallNow push button has some unknown attributes, even though those attributes are known “now”: they assign the UAC control icon to the button.

So unless we obtain an updated .CUB file, these appear to be problems we will just have to live with. However, in these instances, that is not the case. As mentioned earlier the .CUB file is just an MSI file with custom tables, so you can use your favourite MSI editor to open it. When we inspect the content we find that the ICE rules themselves have been written to retrieve their parameters and working values from these custom tables and are not using hard-coding inside the rule itself. We can use this to our advantage.

To update the ICE27 we add the MsiConfigureServices row into the _Action table:

And to update the ICE45 we change the UsedBits column of the _ReservedBits table. Here we change the existing value 8126503 by adding the additional allowed attribute for the UAC shield icon 8388608, giving 16515111.

Of course there are also some rules which are plain annoying. Understandably you may never want to fix or even know about them. Further inspecting the .CUB file we find that the _ICESequence table, which controls which rules are used and in which order, has a Condition column. Inserting a suitable logical condition which can never evaluate to true— for example, “1=0”—essentially turns off that rule.

You may also perform the same trick from InstallShield Tools -> Options -> Validation -> Customize by turning off any rules you want to ignore.

In this article we have explored the motivation for MSI Validation and looked in more depth at the standard .CUB file. In my next article we will discover that we can extend this regime to cater for our own business rules by implementing our own custom logic.  Our ultimate aim is to improve our overall package quality.