InstallTalk

Validating User Input in a Suite Project

By Michael Urman

Just as sometimes you want to let your users configure the software, sometimes you need to limit the choices they can make. Maybe you're checking if they're up too late by asking them to solve a trivial arithmetic problem. Or maybe it's a matter of allowing them to continue only if they have a valid serial number. In this article, I'll show how to do the first in a custom wizard page, using a custom DLL I create with Microsoft Visual C++ 2010 Express.

Similar to last time, I start by creating a new project called SuiteCalc, in which I select an application type of DLL, change my Runtime Library to /MT and /MTd, and add a module definition file named SuiteCalc.def to export the function VerifySum and wire the file to my Linker Input properties. This function follows the interface Hidenori described in his Calling a Function in a DLL from a Wizard Page or Window in a Suite Installation blog post, and it can be called by specifying it in either an Action or a Validate setting of any supporting control. The settings Action and Validate differ in that Validate runs the function before changing the property (calls to get_Property retrieve the old value of the property), and a failure return value prevents the change from being committed; Action runs the function after the change is committed, and a failure return value indicates the install should abort. So I create the function VerifySum in SuiteCalc.cpp.

HRESULT __stdcall VerifySum(IDispatch *pDispatch);

The function VerifySum reads three properties, checks the math, and stores a result into a fourth property. For simplicity it will always read Addend1 and Addend2, and compare their sum to Sum. When all three are supplied, it will set Correct to either Yes or No, and when there isn't a valid mathematical equation because one of the properties doesn't hold a number, it will set Correct to an empty string.

Next I create a Suite project, add a test package, and add SuiteCalc.dll to the project through the Support Files view. It's time to modify the wizard. The InstallationWelcome page needs a way to specify Addend1, Addend2, and Sum, so I add three new text box controls, and set their properties. Each of those text boxes will have their Action setting set to {SuiteCalc::VerifySum} in order to invoke the validation. To react to the results of this action, there are a couple options. One is to add a label with its Property set to Correct, and another is to add two labels with text like Correct and Wrong with their visible conditions set to {Binding Correct==Yes} and {Binding Correct=No} respectively. I'll go with the second. Finally to prevent installing when I can't add numbers correctly, I set the Next button's enabled condition to {Binding Correct==Yes}. For completeness, I added a label with a plus and an equal sign between the text boxes.

And that's it: we have our calculator. The attached SuiteCalc.zip file contains the sample source code I've described, as well as a built DLL and a project that uses it. You can use the same approach to check anything you'd like. You could even make a web call. Just beware that the longer the code takes to execute, the longer the end user has to wait to see the results.

Note that actions that call a function in a DLL require InstallShield 2012 SP1. To obtain SP1, see Q201298: InstallShield 2012 Service Pack 1. For information about the InstallShield 2012 release, see the InstallShield 2012 demo.

ICE Validation Resolution (MICE)

By Matt St.Clair Bishop

In my last two blog articles (ICE Validation: Part 1 and ICE Validation: Part 2) we discussed the need for validation of the MSI databases and a means by which you could include your own custom rules into the standard Internal Consistency Evaluator (ICE) validation checking mechanism. This time we will extend the thinking to provide a means of automatically resolving validation issues creating a Manipulating-ICE or MICE.

Aim
The obvious extension to the error flagging phase of the ICE validation is the error correction phase, which has, up until now, been a manual process. We need to remove the need for a technician performing validation to personally interpret the results. We seek to automate the resolution, fixing hundreds of instances in the same time it would take to resolve one issue manually.

To do this we will perform the following steps:

1. Make a copy of the original MSI database.
2. Inspect some element of the MSI database iterating through records as necessary.
3. Perform resolution by updating the copy of the database.
4. Commit all changes and compare to the original database to generate the transform.

This demonstration will be performed in Visual Basic Script for ease.

During this demonstration we will take a very simple example of a custom packaging Best Practice, that of ensuring that all packages are deployed per-machine by setting the value of the property ALLUSERS to 1.

Copy the Original Database
In the following code snippet we see (on line 18) the command line argument being processed to determine the working directory of the MSI which was dropped onto the VBScript. After that both the base MSI and the changed MSI are assigned names. The VBScript File System Object is used to duplicate the given MSI. Then, using the Windows Installer Object, both databases are opened (the base in read-only and the changed in read-write transact mode).

 

 

Inspect the Current Value of the ALLUSERS Property
In this snippet we see how to interact with the tables; it is quite similar to the way in which you talk to a SQL Database. First we create a view, then we execute that view and finally fetch records from the executed view.

 

 

 

 

The key to getting this right is the types of quotes used on line 42. The double quotes (" ") enclose the entire Select statement. We sometimes break out of that literal string to include VBScript variables calculated or parameterised earlier, and in those cases we concatenate them into the line using the ampersand (&). The single vertical quotes ('') are used to refer to strings within the Select statement. In our example we are looking for the string value of a property to be ALLUSERS. Any columns which are defined as numeric, such as the Root column in the Registry table, do not use the single vertical quotes. Finally the single angled quotes (` `) are used to escape column and table names; this is not necessary unless the column of table name clashes with an internal MSI-SQL keyword—for example, in the Registry table there is a column called Key, which is also a MSI-SQL keyword.

To highlight the problem of not escaping consider a somewhat contrived custom table called FROM containing a column called SELECT and wanting to read its value when a second column called WHERE has the value 1. The un-escaped Select statement would read:

“SELECT SELECT FROM FROM WHERE WHERE=2” and would fail miserably, whereas the escaped equivalent:

“SELECT `SELECT` FROM `FROM` WHERE `WHERE`=2” would work correctly.

Although this is a contrived example unless we learn all MSI-SQL keywords this could also happen in more realistic examples. So to be on the safe side we should escape all column and table names.

 

Perform the Resolution
In this snippet we perform the change necessary to fix our issue. In this case we have some alternate cases: the ALLUSERS value may not exist or it may exist with the non-prescribed value of 1.

The If statement on line 45 is true only if there is an ALLUSERS property in the MSI. We go on to extract its value using the “.StringData(1)” property. This extracts from the current record the value of the column in position 1 and returns it as a string representation. If the value does not already equal 1 we set it to 1 and then on line 56 we create a new view. The MSI-SQL statement here updates the property table and embeds the VBScript value of AllUsers. Note we must still execute that view but we do not proceed to fetch records from it.

 

 

 

 

 

 

 

 

 

 

 

The Else statement that begins on line 61 is true only if the earlier select statement failed to collect any records which means there is no ALLUSERS property (hence this is a non-standard per-user deployment). So in this case we should just insert the missing record into the property table.

Commit Changes and Make a Transform
Technically, at this point, we have completed our changes but since we opened the database in transact mode just closing the database will rollback any un-committed changes. So before we do that we must commit our changes.

 

 

 

 

In our last code snippet we see how to compare the changed database with the original read-only database to create a transform. This allows us to use this same script on a vendor MSI and express the same change without modifying the original vendor package. The line 149 shows how to make the transform more generic and not care too much when applying the transform.

 

 

 

 

Summary
In this article we have seen how to perform a simple check against the MSI database and fix it. Although fairly trivial, this example can easily be extended to perform more complex checks on different and multiple tables retrieving sets of records instead. However the resolution is just as simple and when applied to large packages generate massive time savings over the same manual operation.

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.

Calling a Function in a DLL from a Wizard Page or Window in a Suite Installation

By Hidenori Yamanishi

In Suite installations, InstallShield lets you define actions that an end user triggers when using some of the various wizard interface controls. See the Configuring an Action for a Control on a Wizard Page or Window help topic for more details about the actions. If you need to perform an action in your Suite installation that is not natively supported by InstallShield, you can create an action that calls a function from a .dll file. This .dll file can perform any function that you require, such as verifying a serial number.

The first step in creating an action that calls a function in a DLL is to write the DLL. InstallShield requires a precise prototype for an entry-point function in a DLL called as the result of an action. Flexera Software does not provide technical support for Windows programming or DLL debugging. You are responsible for correctly writing any DLL functions. Prototype your DLL functions as shown below. Any variation in return type or type and number of parameters can cause the action to fail.

HRESULT __stdcall Foo(IDispatch*)

InstallShield uses the function prototype to pass the ISuiteUIExtension COM interface pointer to your DLL, which enables you to access the following functions available in the Suite bootstrap (Suite_UI.dll):

• BrowseFile
  
  HRESULT BrowseFile(BSTR bstrCaption, BSTR bstrInitialFile, BSTR* pbstrFile)
  
  This function launches the Browse for Files or Folders dialog box when an end user clicks the control. The string of instructions that are displayed on this dialog box are typically the value of a string identifier that you specified by the bstrCaption parameter.
  
  The initial file that is selected on this dialog box is the full path and file name of the file that you specified by the bstrInitialFile parameter.
  
  If the end user selects a file in this dialog box and clicks the OK button, the dialog box closes, and the function sets the pbstrFile parameter to the full path and file name of the file that the end user selected. If the end user clicks the Cancel button, the function returns E_FAIL.
  
  If the function succeeds, it returns S_OK.
  
  
• BrowseFolder
  
  HRESULT BrowseFolder(BSTR bstrCaption, BSTR bstrInitialFolder, BSTR* pbstrFolder)
  
  This function launches the Browse for Folder dialog box when an end user clicks the control. The string of instructions that are displayed on this dialog box is typically the value of a string identifier that you specified by the bstrCaption parameter.
  
  The initial folder that is selected on this dialog is the full path of the folder that you specified by the bstrInitialFolder parameter
  
  If the end user selects a folder in this dialog box and clicks the OK button, the dialog box closes, and the function sets the pbstrFolder parameter to the full path of the folder that the end user selected. If the end user clicks the Cancel button, the function returns E_FAIL.
  
  If the function succeeds, it returns S_OK.
  
  
• DoModal
  
  HRESULT DoModal(BSTR bstrDialogName, LONG* pnResult);
  
  This function shows a secondary window that you specified by the bstrDialogName parameter as a modal window.
  
  If the end user clicks the OK button, the modal window closes, and the function sets the pnResult parameter to IDOK. If the end user clicks the Cancel button, the function sets the pnResult parameter to IDCANCEL.
  
  If the function succeeds, it returns S_OK.
  
  
• MessageBox
  
  HRESULT MessageBox(BSTR bstrMessage, BSTR bstrTitle, LONG nType, LONG* pnResult);
  
  This function shows a modal dialog box that contains a system icon, and a brief message that you specified by the bstrMessage parameter.
  
  When the end user closes the message box, the function returns and sets the pnResult parameter to an integer value that indicates which button the end user clicked.
  
  
  
• SetActivePage
  
  HRESULT SetActivePage(BSTR bstrPage);
  
  This function moves to a specific wizard page that you specified as the bstrPage parameter of this function.
  
  If the function  succeeds, it returns S_OK.
  
  
• OpenDocument
  
  HRESULT OpenDocument(BSTR bstrDocument, BSTR bstrVerb);
  
  This function performs an operation on a file that you specified by the bstrDocument parameter. The bstrVerb parameter specifies the action to be performed.
  
  It calls the ShellExecuteEx Windows function. Typical verbs include open, edit, print, and runas. For details about the verb, refer to the lpVerb member of the SHELLEXECUTEINFO structure.
  
  
• LogInfo
  
  HRESULT LogInfo(BSTR bstrMessage);
  
  This function writes a message that you specified as the bstrMessage parameter to a log file for your Setup.exe.
  
  If the function succeeds, it returns S_OK.
   
• get_Property
  
  HRESULT get_Property(BSTR bstrProperty, BSTR* pbstrValue);
  
  This function retrieves the value of a specific property that you specified as the bstrProperty parameter.
  
  If the function succeeds, it returns S_OK.
   
• put_Property
  
  HRESULT put_Property(BSTR bstrProperty, BSTR bstrValue);
  
  This function sets a specific property that you specified as the bstrProperty parameter to a specific value.
  
  If the function succeeds, it returns S_OK.
   
• FormatProperty
  
  HRESULT FormatProperty(BSTR bstrValue, BSTR* bstrReturnValue);
  
  This function substitutes properties using a format string in a string that you specified as the bstrValue parameter. When the function returns, the substituted string is set to the bstrReturnValue parameter.
  
  
• ResolveString
  
  HRESULT ResolveString(BSTR bstrStringId, BSTR* bstrReturnValue);
  
  This function resolves a string identifier that you specified by the bstrStringId parameter. When the function returns, the value of the string identifier is set to the bstrReturnValue parameter.
   
• get_Attribute
  
  HRESULT get_Attribute(BSTR bstrName, BSTR* pbstrValue);
  
  The function is reserved for future use. It currently returns E_NOTIMPL.

To access the ISuiteUIExtension interface from your DLL, you need to incorporate the type library information from the SetupSuite.exe file that is installed with InstallShield. The default path is:

C:\Program Files\InstallShield\2012\Redist\Language Independent\i386\SetupSuite.exe

The example below shows how to display a message box when an end user clicks a control:

#include "stdafx.h"
#include <atlstr.h>
#import "C:\Program Files\InstallShield\2012\ Redist\Language Independent\i386\SetupSuite.exe" no_namespace raw_interfaces_only
named_guids

HRESULT __stdcall Action(IDispatch *pDispSuiteUIExtension)
{
    CComQIPtr<ISuiteUIExtension> spSuiteUIExtenstion = pDispSuiteUIExtension;

    long lResult = 0;
    return spSuiteUIExtenstion->MessageBox(CComBSTR(L"Hello"), CComBSTR(L"DLL Action"), MB_OK, &lResult);
}

Once your DLL is ready, you must add the DLL to your Suite installation, and design an action to call the entry-point function. The following is the syntax of the action statement that calls a DLL function.

{DLLName::FunctionName}

For example, to call a function called Action in TestDLL.dll when an end user clicks the control, enter the following action statement:

{TestDLL::Action}

To add a DLL action to your Suite project:

1. In the View List under Behavior and Logic, click Support Files.
2. In the Behavior and Logic explorer, select the Language Independent node and add TestDLL.dll.
3. In the View List under User Interface, click Wizard Interface.
4. In the Wizard Interface explorer, select the dialog that you want to modify.
5. Do one of the following:
   • To configure the action of one of the navigation controls (the Next, Back, Cancel, Install, or Finish buttons)—In the right pane, expand the settings for the control whose action you want to modify
   • To configure the action of any of the other controls—In the wizard editor, select the control whose action you want to modify.
6. In the Action setting, enter the action statement to call a DLL function in TestDLL.dll.
   {TestDLL::Action}

Note that actions that call a function in a DLL require InstallShield 2012 SP1. To obtain SP1, see Q201298: InstallShield 2012 Service Pack 1. For information about the InstallShield 2012 release, see the InstallShield 2012 demo.

Using SQL Dialogs with DIM Projects

By John Cresswell

With the new DIM projects we essentially support all the functionality offered from a Basic MSI project. This includes our built in SQL support; however, there are a few additional steps you will need to go through in order to configure the SQL dialogs.

First a little background, so bear with me. The two dialogs used by our SQL support—SQLLogin and SQLBrowse—are added by default in a Basic MSI project when the first SQL connection is added to the project. For a DIM project this is not the case and the intended functionality is for the dialogs to be added when the DIM is consumed. Due to a problem discovered very late in the release cycle this process has a flaw that will need to be overcome. The basic idea is that the dialogs need to be added to the Basic MSI before building and the properties that the dialogs are associated with need changing to match the DIM project values.

When you add a SQL connection to a DIM project, the properties in the screen shot below are created and used by the SQL custom actions to connect to the intended server. As you can (barely) see they have GUIDs appended; this is necessary to ensure uniqueness with the Basic MSI projects that consume them.

 

The SQL dialogs that are imported contain hard-coded properties and these properties do not have GUIDs associated with them. So by default, the dialogs that will be shown if you add a DIM file containing SQL connection data to a Basic MSI will not have the correct properties configured, and so the connection string used at runtime will be incorrect. The properties associated with controls on the dialog will be, for example, IS_SQLSERVER_USERNAME but the SQL connection will use IS_SQLSERVER_USERNAME.GUID.

To resolve this problem you can add the two SQL dialogs (SQLLogin and SQLBrowse) to the Basic MSI before building the project. Once the dialogs are in the project you will then need to modify certain controls , events and conditions associated to these dialogs to ensure that the correct properties are being modified by the dialogs.

There are two simple ways to add the dialogs to the project:

• Add a spurious SQL connection and then remove it.
• Manually import the two isd files (SQLLogin.isd and SQLBrowse.isd) from the Dialogs view.

In order for these dialogs to function correctly you will need to update the properties that the controls are associated with.  This can either be done from the Dialogs view or by direct editing of the tables. I created  sample DIM and Basic MSI projects to accompany this blog and I preferred to modify the tables directly. Essentially you will need to find all instances of the properties used in the DIM's ISSQLConnection table and modify them (append the DIM GUID to them). For a default SQL Connection the following properties will need to be modified:

• IS_SQLSERVER_DATABASE*
• IS_SQLSERVER_PASSWORD
• IS_SQLSERVER_USERNAME
• IS_SQLSERVER_AUTHENTICATION
• IS_SQLSERVER_SERVER*

*The default schema for the ControlEvent table for a Basic MSI project is a string of 50 characters. This limit is derived from Schema.msi that Microsoft ship with the platform SDK. The reason I mention this limit is that the ControlEvent table is used by the SQLBrowse dialog to set the values for the server you wish to connect to and the name database you want to use (using the properties of IS_SQLSERVER_SERVER and IS_SQLSERVER_DATABASE). The GUID is 32 characters long and so these property names with GUIDs appended will not fit the schema requirements. There are two possible approaches to work around this problem:

• Limit the length of the properties used for Database and Server to 15 characters or fewer. In my attached sample this is the approach I took, so you will see in the .dim file I used the properties SERVER. B7D178BF_A7D0_44DA_9246_30803A3EDB16 and DATABASE.B7D178BF_A7D0_44DA_9246_30803A3EDB16.
• Modify the schema of the Event column in the ControlEvent table.  Note this is certainly a possible workaround and something that in and of itself will not cause a problem; however, due to issues this can create with patching (you can't change the schema of a table with a patch), I would not recommend this approach without extensive testing.

From the Dialogs view you will need to modify the properties that controls on the SQLLogin dialog are using. The controls in question are:  cboServers, RadioButtonGroup1, Edtlogin, EdtPswd and EdtCatalog. The screen shot below shows the radio button group property modified to work with my sample DIM.

Also on the SQLLogin dialog you will need to modify the properties used for control events for both BtnSQLBrowse and BtnDbBrowse buttons. Control events can be configured by selecting the Behavior section under the SQLLogin dialog and then selecting the Events tab on the right hand pane (the tabs are in the lower left corner of the lower right hand pane).

The final change for this dialog is for the enable disable condition. You will want to modify the conditions for lblPswd, EdtPswd, lblLoginID and EdtLogin.

Onto the SQLBrowse dialog; here you will need to change the events for the OK button as follows:

Assuming you update all the properties to match those in the DIM ISSQLConnection you should now be able to build and run and have the dialogs show up and function as you expect.

We will continue to refine this functionality to eventually avoid these manual steps, but in the meantime, you can follow the steps outlined above to obtain the usual SQL functionality from a DIM project.

The sample DIM and Basic MSI files that I used are available for download.

The ability to create DIM projects is available in the Premier edition of InstallShield. This support is also available in the InstallShield Developer Installation Manifest Editor, a new collaboration add-on. The ability to add DIM files to Basic MSI projects is available in the Premier edition of InstallShield.

Extension Conditions

By Josh Stechnij

InstallShield Suite installers provide a fairly robust condition system implementation, allowing for building conditions in a much more flexible manner than InstallShield prerequisites previously allowed. The Suite bootstrap uses conditions to determine what mode to run in, whether features should be selected by default, determining if a package is installed or can be allowed to install, etc. Conditions can be grouped in any combination of “none” (not), “any” (or), or “all” (and) groups. While the built-in condition types allow for checking a variety of situations (file exists; files with certain version, date/time, or contents; registry key/value exists; specific registry value data; etc.), some scenarios cannot be covered by these built-in types. For example, if the existence of a web site in IIS (or some other web server) needs to be determined, the built-in conditions cannot check for this type of system resource. In order to provide flexibility, an extension mechanism is provided by the Suite bootstrap to allow for custom conditions to be implemented through a C/C++ DLL.

Implementing an extension condition requires the following:
  - A namespace definition in setup.xml to define the resource that implements the condition
  - A resource definition in setup.xml to contain the extension DLL
  - One or more elements in a setup.xml condition block to describe the condition
  - A C/C++ DLL that implements the condition functionality and interfaces with a Suite installer

Authoring Extension Conditions
Built-in conditions are structured as follows in the setup.xml file that drives the Suite bootstrap:

<GroupType>
     <ConditionType Attribute1="…" Attribute2="…" />
</GroupType>

A condition type is defined by the element name of the condition, and any parameters for the condition are provided through attribute name/value pairs. Extension conditions follow the same semantic definition but use XML namespace definitions to provide some additional information. The root setup element contains a namespace definition to indicate that a resource DLL implements the extension condition validation and evaluation functionality:

<setup xmlns="installshield/2012/bootstrap" xmlns:testext="testext.dll" SuiteId="…">

In the above example setup element, the ‘testext’ namespace definition indicates testext.dll is a resource DLL that will implement any conditions residing in the ‘testext’ namespace. An extension condition can then be defined; it is implemented by testext.dll as follows:

<testext:TestExtensionCondition Attribute1="value1" Attribute2="value2" />

The above extension condition defines a condition, TestExtensionCondition, and indicates this is implemented by the DLL defined by the ‘testext’ namespace defined in the setup element. The extension name (TestExtentionCondition) also defines the base names of the entry points the extension DLL must implement and export. The attributes are arbitrary names whose values can be retrieved when the bootstrap calls the extension DLL to validate and evaluate the condition.

A resource entry in setup.xml is the last item required to define an extension condition. Resources are normally streamed into a setup.exe at build time so that no external files are required to launch the setup. To define a resource for the extension DLL, a resource element in the Resources group is defined:

<Resources>
     <Resource Source="PathToResourceFile" Namespace="testext.dll" />
</Resources>

Note: in a Suite project file, there are multiple ‘resources’ groups. One group is defined for the user interface and another is defined for support files needed to run the setup. To define an extension DLL resource, ensure the new resource element is added to the correct group. To simplify this process, add the extension DLL to the Language Independent node in the Support Files view and then edit the project file in a text/XML editor to add the Namespace attribute to the resource element that the IDE created.

The resource element defines that this DLL is streamed into setup.exe with the name testext.dll. The Namespace attribute links the resource to the XML namespace defined for the extension DLL in the setup element.

Implementing the Extension DLL
With the setup.xml authored to use an extension DLL, the entry points in the DLL need to be authored. The Suite bootstrap expects two entry points per condition, one to validate the condition and one to evaluate the condition. Both entry points are based on the name of the extension condition. In the above setup.xml example, the extension condition is named TestExtensionCondition. The DLL implementing this condition must export the following entry points:

TestExtensionCondition_Validate
TestExtensionCondition_Evaluate

These functions should be defined as follows:

HRESULT __stdcall TestExtensionCondition_Validate(IDispatch *pCondition);
HRESULT __stdcall TestExtensionCondition_Evaluate(IDispatch*pCondition, VARIANT_BOOL *pbEvalResult);

The validation entry point is called while the bootstrap is parsing setup.xml conditions and provides an opportunity for the extension condition to ensure the condition attributes defined by setup.xml are suitable for the condition to evaluate in a predictable manner. This entry point is called any time an extension condition of this type is found in setup.xml. Returning S_OK from this entry point indicates to the Suite that the condition is valid. Returning a failed HRESULT status will cause the Suite to abort with an error for the condition that was last validated.

The evaluation entry point is called at any time an extension condition of this type is referenced by setup.xml. The evaluation is allowed to perform any action necessary to evaluate the condition** to a true or false result. The result is returned in the form of a VARIANT_BOOL in the pbEvalResult parameter. A result of VARIANT_TRUE is treated as a true result and a result of VARIANT_FALSE is treated as a false result. A success status (S_OK) should be returned from an evaluation function. A failure status will currently abort the evaluation of the current condition block being evaluated but will not cause the setup to abort.

** While any action is allowed by the bootstrap, extension conditions run with the privileges of the Suite setup that they are called from. Some actions may require administrator privileges (such as reading IIS 7.x configuration data). In such cases, the setup would need to be run with or be manifested to require administrator privileges for the condition to access needed data successfully.

The IDispatch interface passed to the validation and evaluation entry points implements the ISuiteExtension interface. A pointer to an ISuiteExtension can be obtained by calling the QueryInterface method on the IDispatch interface. The ISuiteExtension interface allows the condition functions to access the attribute parameters defined for the extension condition in setup.xml. Note that each condition in setup.xml will receive a different interface pointer that is specific to each condition instance. Therefore, the interface pointer passed to the entry point function should always be used and should not be saved across calls to the extension DLL.

The interface is currently defined as follows:

interface ISuiteExtension : IDispatch {
              [propget, id(1), helpstring("Attribute")]
                           HRESULT Attribute([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

              [id(2), helpstring("method LogInfo")]
                           HRESULT LogInfo([in]BSTR bstr);

             [propget, id(3), helpstring("Property")]
                           HRESULT Property([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

             [propput, id(3), helpstring("Property")]
                           HRESULT Property([in]BSTR bstrName, [in]BSTR bstrValue);

             [id(4), helpstring("FormatProperty")]
                           HRESULT FormatProperty([in]BSTR bstrValue, [out, retval]BSTR *bstrReturnValue);

             [id(5), helpstring("ResolveString")]
                           HRESULT ResolveString([in]BSTR bstrStringId, [out, retval]BSTR *bstrReturnValue);
};

The following methods are provided by ISuiteExtension for use by an extension DLL:

HRESULT get_Attribute([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

This method can be used to retrieve the value of an attribute for the current condition instance. The attribute name is passed in bstrName and its corresponding value is returned in bstrValue.

HRESULT LogInfo([in]BSTR bstr);

This method can be used to write any information needed to the setup Suite debug log that may be useful for debugging or other informational purposes. The bstr parameter contains the string to be written to the log.

HRESULT get_Property([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

This method can be used to retrieve the value of any property currently defined in the running Suite. Properties that are not defined will return an empty value. The bstrName parameter specifies the name of the property to obtain the value for. The value for the property will be returned in the bstrValue parameter.

HRESULT put_Property([in]BSTR bstrName, [in]BSTR bstrValue);

This method can be used to set the value of a new property or change the value of an existing property in the currently running Suite. Passing an empty value effectively deletes the property. The bstrName parameter specifies the name of the property to set. The bstrValue parameter specifies the value to set for the specified property.

HRESULT FormatProperty([in]BSTR bstrValue, [out, retval]BSTR *bstrReturnValue);

This method can be used to format a string that contains embedded property references (in the form ‘[PROPERTYNAME]’) in the string provided in the bstrValue parameter. The formatted value is returned in the bstrReturnValue parameter. Note that only one level of property references is formatted. If one property’s formatted value contains another property reference, this method will not format the second property.

HRESULT ResolveString([in]BSTR bstrStringId, [out, retval]BSTR *bstrReturnValue);

This method can be used to resolve a Suite string identifier into the corresponding string value for the currently running Suite installation in the currently selected UI language. The bstrStringId parameter specifies the string identifier to resolve, and the resolved string is returned in bstrReturnValue. If no such string identifier exists, the returned string is empty.

Building an Extension DLL
An extension condition DLL can be built with any recent version of Visual C++ or any tool/language that supports COM and DLL exports. When any extension DLL is built with Visual C++, the interface definition for the ISuiteExtension interface can be obtained by using #import to import the type library provided with the setup Suite executable starting with InstallShield 2012 SP1. The following statement can be used to import the type library in a VC++ project (such as in stdafx.h):

#import "C:\Program Files\InstallShield\2012\Redist\Language Independent\i386\SetupSuite.exe" no_namespace raw_interfaces_only named_guids

Note that if InstallShield is installed to a different location, the path in the #import statement above needs to be adjusted to the correct location.

For a sample extension condition, download the SuiteExtensionSample.zip file. This file contains a sample extension DLL project created with Visual Studio 2008 and an InstallShield Suite project that uses the extension DLL for an extension condition in the eligibility condition of a package in the Suite project. Note that to build the DLL project, Visual Studio 2008 or newer with ATL support is required. (Express editions of VC++ do not include ATL support.) The #import path to the setup Suite type library in stdafx.h may also need to be adjusted for the project to build correctly.

Suite support is available in InstallShield 2012 Premier Edition. For a list of additional Premier-only features, visit the InstallShield Editions page.

Putting the “Wizard” in Wizard Pages

By Michael Urman

While InstallShield makes it easy to change the UI of your Suite project in small ways, such as editing the text on a wizard page, or moving a control by a few pixels, sometimes that's not enough. Sometimes you need to add a new page to your wizard. There are three approaches you can take to adding a new page. I want to share them and tell you a way to make the third one even more powerful.

The Role of an Intern

The first way to add a page to the wizard is completely manually. In the Wizard Interface view, right-click the Wizard Pages node and select Add Blank Page. Set its title, turn on wizard buttons, add controls, and configure any additional settings to make the page do what you want.

If the new page you want is similar to one you have, either because you just created one of several similar pages, or because InstallShield already provided one that was close, you can copy and paste in the list of pages to clone a page into a new one.

The Role of a Development Tool

The second way to add a page is through copy and paste in the project file (.issuite). Cloning a wizard page in the IDE can work wonders. However it comes with one major limitation: you can clone a page only within the same project. So if you need to go between two projects, you can open the project in an XML editor to copy pages from one project to another. Look for the Page elements with the Name attributes matching the pages you want to copy. They appear in the same order that you saw the pages in the Wizard Interface view, so they should be easy to find. Copy entire Page elements (from <Page …> to </Page>) and paste them in your other project.

If the page you copy uses only strings that are provided by InstallShield, you're done. However if it references any strings that you added yourself, you'll probably see things like ID_STRING17 when you run your Suite. To fix this you may need to copy the string definitions too. You can find them under the Languages element, one copy of your string in an element of the string ID's name, for each Language element.

The Role of an Architect

The third way to add a page to your wizard is by inserting it from the User Interface Wizard, which you access by right-clicking the Wizard Pages node and selecting Add Predefined Page…. InstallShield 2012 comes with six predefined pages that range from selecting a package's INSTALLDIR to accepting a supplemental EULA. The Wizard asks you where to sequence the new page, and may ask one more question such as which package's INSTALLDIR you want to change, or what EULA file you want to show.

But that's not all. If you want to change how a page looks in most of your Suites, including some you've already created, you can create your own template page with these changes in place. Start by modifying the InstallationWelcome page's layout to match what you want. For example, resize the labels to stretch the whole width, set the SS_CENTER Style on all the labels, and center the image above. Save the project, and go find its Page element, and copy it.

Then open <InstallShield>\Support\0409\SuiteTemplates.xml. This file contains definitions for all the templates shown in the wizard, in a format very similar to that in a project. Put in some boilerplate information, including a name and description for your new page template.

Paste your page definition inside the v:WizardPage element.

For simple pages, save it and you're done. Now you can add your custom welcome page to any project; just remove the original and your Suite is ready to go.

For more complex pages, you can tell the User Interface Wizard to ask for a package or a file by including a Variable element with a Choose attribute of Parcel or File; see a template that uses those to figure out how they work. Note that references to variables need to be in attributes that have a v prefix on their attribute name, and the reference uses double hashes. Some variable names also receive several sub-variables. You can see most of this in the View and accept supplemental license agreement template (the remaining capabilities show up in the Browse for installation folder template):

Just remember that this is currently an implementation detail of InstallShield 2012. We expect to have to change the project's XML format over time, and that will result in changes to the SuiteTemplates.xml format as well. If nothing else, expect the namespace to be updated, so be very careful about blindly copying any of your customizations of SuiteTemplates.xml to a new version of InstallShield. 

Using the Hyperlink Control in a Suite Installation

By Richard Woods

Have you ever wanted to add a web link to your setup? It is quick and easy to do with the Suite project hyperlink control.

Adding the Hyperlink Control

1. Open up your Suite project.
2. Browse to the Wizard Interface view.
3. Select the wizard page you want to add a hyperlink to.
4. Click on the hyperlink control on the toolbar:
   
5. Size and position your new hyperlink control to the size and position you want.
6. In the Text field, enter the text you would like to appear on the dialog. Ex: Support Page
7. In the Target URL field, enter the URL that you want to navigate to when the hyperlink is clicked. Ex: http://www.MycompanyURL.Com/support
8. Build and run your project.

You should see the hyperlink on your wizard page, and clicking it will navigate to the URL you specified.

Using a Property for Target URL

If you would like to use a property for your URL instead of hard coding the address, this is easy to do as well.

1. Navigate to the Property Manager view.
2. Click the "New" button.
3. Specify a property name. Ex: SupportURL
4. Specify a web address in the Value field. Ex: http://www.MycompanyURL.Com/support
5. Navigate back to your wizard page in the Wizard Interface view.
6. Change the Target URL to the property name you specified, enclosed in brackets. Ex: [SupportURL]
7. Build and run the installation.

The hyperlink will now navigate to the web page specified in your property.

Using an Action with your Hyperlink

What if in addition to browsing to a URL, you also wanted to perform an additional action when a hyperlink is clicked? You can do this too. The details of what actions you can perform are described in the help topic Configuring an Action for a Control on a Wizard Page or Window. But for now, let's walk through opening a file.

1. In the action field, enter: {Open ReleaseNotesFile}
2. Browse to the Support Files view.
3. Add the file you would like to open. Ex: ReleaseNotes.txt
4. Browse to the Property Manager view.
5. Click the "New" button.
6. Specify a property name. Ex: ReleaseNotesFile
7. Specify the file location for the property's value. Ex: [SETUPSUPPORTDIR]\ReleaseNotes.txt
8. Build and run the installation.

The hyperlink will now navigate to the web page specified, and open ReleaseNotes.txt.

If you want to open only a file with the hyperlink control, you just specify the path directly in the Target URL field and do not specify anything for Action. Ex: [SETUPSUPPORTDIR]\ReleaseNotes.txt

Or, if you wanted to open the file with a button instead of a hyperlink control, you could specify the same action you did for the hyperlink control in the button's Action field. Ex: {Open ReleaseNotesFile}

For more how-to information, review the InstallShield Tips & Tricks.