Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield

Visual FoxPro includes the limited edition of InstallShield Express version 5.0, replacing the Setup Wizard found in versions prior to Visual FoxPro 7.0. To learn how to install InstallShield Express Limited Edition on your computer, see How to: Install Additional Applications.

Note
You can use any setup creation program that uses Microsoft Windows Installer technology to create a Setup program (.msi) or merge modules (.msm) that are compatible with Microsoft Windows Installer. Some distribution scenarios require merge modules in addition to the Visual FoxPro run-time files. For more information, see Visual FoxPro Distribution Scenarios in this walkthrough.

The Windows 2000 Logo guidelines require that setup programs be based on Windows Installer technology. The Windows Installer is part of the Windows 2000 and Zero Administration Windows efforts to reduce the overall cost of deploying, using, and managing desktop computers. Both the limited and full editions of InstallShield Express use Microsoft Installer, which features comprehensive and flexible Setup creation technology. This technology makes it possible for your customers to install and configure your application efficiently.

This walkthrough does not act as a replacement for the InstallShield Express documentation, which you should read first. It is a supplement to assist you in using InstallShield Express to package and distribute applications. You can also download the Platform SDK Components for Windows Installer Developers from the Microsoft download Web site at http://www.microsoft.com/msdownload/platformsdk/sdkupdate/.

You should consider several issues when preparing an application for distribution. In addition to following the procedure outlined in the Application Distribution Process, you must identify the structure of your application; decide how to deliver the application to users, and how to best organize your Setup program. When you have addressed all these issues, you are ready to distribute your Visual FoxPro application.

Creating the Setup project is the first step in creating a Setup program. The Setup project (.ism) file you create with InstallShield Express is based on the Windows Installer project file. This file stores all the logic and information necessary to build a setup program compatible with Windows Installer.

To create a Setup project

On the Start menu, point to All Programs. Point to InstallShield, and click Express to open InstallShield Express.
On the File menu, click New to open the New Project dialog box.
Browse to the location where you want to save your project, rename the default project file name in the Project Name and Location box, and click OK.
To create your setup program in a language other than English, select an alternate language in the Project Language list.

Note

After you choose a language, you cannot change it for the project.

Note
After you choose a language, you cannot change it for the project.

Defining Project Properties

After you create a Setup project, you can define properties, such as:

Product name
Product version
Product icons
Default installation folder for all application files
Name and location of a Readme file

At the minimum, you should specify the product name and a default installation folder for your application files. The INSTALLDIR property in InstallShield Express specifies the location of the default installation folder, for example, the application home directory. The location of the default installation folder specified by INSTALLDIR is:

[ProgramFilesFolder]Your Company Name\Your Product Name

Note
It is recommended that you change Your Company Name and Your Product Name to the appropriate names for your application.

You can also specify a different folder for your application by setting INSTALLDIR to a folder with the name of your application as specified by MyApp in the following example:

[ProgramFilesFolder]\MyApp

If you plan to install any data or database files, you can also edit the DATABASEDIR property to specify the default destination folder for those files.

To specify general information for your Setup project

In the Organize Your Setup node, click General Information.
In the property list, double-click the value field of a property to edit its value.
Click elsewhere in the property list to see your changes take effect.

Dividing Your Product into Features

From the perspective of the application user and InstallShield Express, a feature is considered a building block of an application. Features make it possible for users to install parts of an application. For example, during Visual FoxPro installation, you can specify whether to install the Visual FoxPro Samples and Visual FoxPro Tools as features.

Note
Dividing your product into features is not required when creating a Setup program, although it can be helpful to users.

The default setting for installing features is Always Install, which lists the components that install with all Setup Types.

To create a feature

In the Organize Your Setup node, click Features.
To add a new feature, right-click the Features node in the tree view in the middle pane, and click New Feature Ins.
Type a name for the new feature, and press ENTER.

When you have identified the your product features, you can set feature properties, such as feature description, how the feature is advertised, and whether the feature is required. Although advertised features appear to be installed to the user, they are not installed during setup. Windows Installer installs the advertised feature when the user tries to use the feature for the first time.

To set a feature property

Select the feature for which you want to modify properties.
In the property list, double-click the value field of the property to edit its value.

To display more options, click the ellipsis (...) or arrow button that appears next to the property value field when additional options are available.
Type or select a new value for the property.

For example, suppose you wanted to provide the option of installing the Help file for your application. Follow the steps to create the feature, and name it "Help file." If you want to make the Help file installation optional, set the Required property to No. If you want the feature to be installed the first time the user tries to invoke the feature by pressing F1 for Help, set the Advertised property to Yes.

Specifying Features for a Setup Type

You can include different Setup types in a Setup program and specify which features each Setup type should install. Setup types offer different levels of installation that the user can choose:

Typical Setup installs all features and files.
Minimal Setup installs the minimum number of features and files necessary for an application to function.
Custom Setup makes it possible to specify which features to install.

You must include at least one Setup type.

All three Setup types install features listed by Always Install. For example, a basic Setup includes features listed by Always Install and the &Typical Setup type. The ampersand (&) in the Setup type name indicates the access key for a particular Setup type in the Setup user interface. You can include or remove Setup types depending on whether you want it included, as long as one remains available, or rename the Setup types.

Note
Specifying features for each Setup type is not required when creating a Setup program.

To select Setup types and specify features for each Setup type

In the Organize Your Setup node, click Setup Types.
In the Setup Types pane, select the check box for each Setup type you want to include.
In the Features installed for <selected> setup type pane, select the check box for each feature you want to this Setup type to install.

Adding Files to Setup

The executable (.exe) file is usually needed for the user to start an application. You can add this file first along with other files your application requires, followed by any optional files.

Visual FoxPro provides resource files that extend the basic functionality of your applications, including FoxUser resource files, API libraries, and Microsoft ActiveX controls. If you use these files, you must add them to the Setup program so they can be installed when running Setup. For more information about resource files that you can use, see Resource Files in Applications.

To view files you can add to Setup

In the Specify Application Data node, click Files.

The Files view is divided into four panes. The left panes display folders on the source and destination computers. The right panes display the files in those folders. The Feature box appears above the four panes.

Note
The INSTALLDIR property specifies the directory containing the root folder for your application files and is usually specified as the destination installation directory.

Before adding files to the Setup project, you must specify the feature to associate those files with by selecting it in the Feature box.

Note
Add required files as Always Install features.

Make sure the feature appears in the Feature box. After selecting the feature, you can add files to the Setup project by copying them from the source folders to the folders on the destination computer.

To add files from the source folder to the destination folder

In the Destination computer's folders pane, select the destination folder where you want to install the application file.

In the Source computer's files pane, drag the source file to the destination folder.

Note
The folder specified by INSTALLDIR in the General Information node as the default installation directory should appear in the Destination computer's folders pane. Dragging the source file to the destination folder only instructs InstallShield Express where to locate the source file when you build your Setup program. It does not move or remove any files on the source computer.

You can also view a list of predefined folders, such as the desktop folder, that you can select and add to the list of destination computer folders.

To view and add predefined folders

In the Destination computer's folders pane, right-click Destination Computer.
Click Show Predefined Folders.
Select the folder you want to add.

The folder appears in the list of destination computer folders.

You can create one or more subfolders in a destination folder.

To create a subfolder in a destination folder

Right-click the destination folder, and click Add.
Type a name for the new folder, and press ENTER.

Registering Files

Windows Installer includes the following capabilities:

Roll back an unsuccessful installation, returning the target computer to its preinstallation state.

For example, COM Servers, such as ActiveX, COM, and COM+ files, require special registration so applications can access their interfaces. These .ocx, .exe, and .dll files traditionally contained self-registration functions that can be invoked to register the files during installation. However, relying on self-registration can cause some problems with Windows Installer.

Note
When registering a COM Server, it is highly recommended that you select Extract COM Information instead of Self-registration as the registration type for the file. If you select Self-registration, Windows Installer will not have the information needed to remove the COM Server from the registry properly.

With traditionally scripted Setup programs, self-registration was acceptable for installing COM objects and is still valid. However, self-registering COM objects do not pass their installation and registration information to Windows Installer. Therefore, Windows Installer cannot roll back installation and registration of self-registered COM objects or advertise those objects.

Advertise installed products or individual product elements, such as COM objects.

Advertising makes a product or COM object available to the user or target computer without installing the product until the user or another computer function attempts to access the advertised element. Advertisement occurs by placing a shortcut in the appropriate location such as the Start menu or registry.

To register a COM server with InstallShield Express

In the Specify Application Data node, click Files.
Copy the file for the COM Server from the source folder to the destination folder.
Right-click the file you want to register, and click Properties.
In the Properties dialog box, click the COM & .NET Settings tab.
Select a Registration Type.

For more information registering COM Servers, see Visual FoxPro Distribution Scenarios.

Selecting Objects and Merge Modules

A merge module (.msm file) contains all of the logic, registry entries, and files needed to install an application or run-time files successfully. If you were to install your application manually, you would need to copy the Visual FoxPro run-time files to the destination computer and register those files. However, if you select the Microsoft Visual FoxPro 9 Runtime Libraries merge module, InstallShield Express copies and registers the run-time files properly.

For a Visual FoxPro application, you should select, at the minimum, the Microsoft Visual FoxPro 9 Runtime Libraries and MSXML 4.0 modules. For more information about Visual FoxPro run-time libraries, see Visual FoxPro Run-Time Libraries.

Note
When you select the Microsoft Visual FoxPro 9 Runtime Libraries module in InstallShield Express, the check boxes for the Microsoft Visual C Runtime Library 7.1 and GDI Plus Redist modules are automatically selected and should remain selected. Visual FoxPro 9.0 requires these modules; therefore, do not clear selection of these modules.

There are two MSXML 4.0 modules that should be included:

MSXML 4.0 (msxml4sxs32.msm)
MSXML 4.0 (msxml4sys32.msm)

You should also include the Microsoft Visual FoxPro 9 Report Applications merge module which contains runtime applications used by the Visual FoxPro 9.0 reporting engine. For more information, see Including Report Files for Distribution.

If your application uses one of the CURSORTOXML functions, you should also include the MSXML 3.0 merge modules. These include the following:

MSXML 3.0 (msxml3_wim32.msm)
Msxml3 Exception INF Merge Module (msxml3inf_wim32.msm)
WebData std library (wdstddll_wim32.msm)

If you are deploying your application internationally, you may need to include one or more of the Microsoft Visual FoxPro 9 Resource language modules.

To select objects and merge modules for installation

In the Specify Application Data node, click Redistributables.
In the InstallShield Redistributables pane, select the check box for each merge module you want to install.
You can install a merge module feature by feature by selecting or clearing the check boxes in the Conditional Installation pane when available.

For more information on merge modules, see Visual FoxPro Distribution Scenarios.

Creating Shortcuts and Folders

InstallShield Express makes it possible for you to create shortcuts and folders in the Start menu and on the desktop.

To create folders or shortcuts

In the Configure the Target System node, click ShortCuts/Folders.
From the Shortcuts tree view in the middle pane, right-click the node where you want to install a shortcut or folder, and click New Shortcut or New Folder.
If you created a shortcut, you must specify a target file. In the Browse for Shortcut Target dialog box, double-click the file for which you want to create a shortcut in the Look in list.

You can also associate your shortcut with a feature by navigating to the folder containing the file associated with the feature and selecting the file from the list.
Type a name for the shortcut or folder, and press ENTER.

To rename the folder or shortcut right-click it, click Rename, type a new name, and press ENTER.

Note

Files for your application are at the bottom of the Look in list.

Note
Files for your application are at the bottom of the Look in list.

Creating Registry Keys

If your application uses registry keys, for example, to keep track of user options, InstallShield Express can add them to the target computer during setup. If the keys do not exist on the development computer, you can create them manually.

Note
Creating registry keys is not required when creating a Setup program.

Registry entries are created in registry hives. Registry hives categorize registry entries by function. For example, COM Server classes are stored in the HKEY_CLASSES_ROOT registry hive. Software options, such as options for Visual FoxPro, are stored in the Software folder in the HKEY_CURRENT_USER hive.

To create registry keys

In the Configure the Target System node, click Registry.
In the Destination computer's Registry view pane, right-click the desired registry hive.
On the shortcut menu, point to New, and click Key.
Type a name for the key, and press ENTER.
Right-click the new key, point to New, and select the type of value you want to add to the key.
In the Destination computer's registry data pane, double-click the key to enter a data value.

Depending on the type of key, you can enter a name for it.

Creating Open Database Connectivity (ODBC) Data Source Names (DSNs)

If the development computer has previously existing DSNs, you can instruct InstallShield Express to install the DSN on the destination computer. If you are installing DSNs, you should include the MDAC merge module when selecting merge modules in case the destination computer does not have ODBC components installed.

Note
Creating ODBC DSNs is not required when creating a Setup program.

To create DSNs

In the Configure the Target System node, click ODBC Resources.
In the ODBC Resources tree view, select the check boxes for the DSNs you want to create on the destination computer.

Customizing Setup Appearance

You can select and change the appearance of dialog boxes that users see when installing your application. You can specify bitmap (.bmp) images for each dialog box and add additional dialog boxes, for example, to allow the user to specify a destination folder.

Note
Customizing Setup appearance is not required when creating a Setup program.

To select dialog boxes

In the Customize the Setup Appearance node, select Dialogs.
In the Dialogs tree view, select the dialog boxes you want to display during installation.

When you select a dialog box, an image of the dialog box appears in the lower-left pane, and properties for the dialog box appear in the upper-right pane.

To make it possible for the user to specify a destination folder

In the Customize the Setup Appearance node, select Dialogs.
In the Dialogs tree view, click Destination Folder.

Building Your Setup Program

After you have finished designing and setting the properties for all the elements in your Setup project, including the features, files, shortcuts, registry entries, and user interface, you are ready to build your Setup program.

The most commonly selected build types are CD-ROM or single image. Selecting CD_ROM creates a Setup program that contains files organized in a directory structure. Selecting SingleImage combines the files into a single file.

To build a Setup program

In the Prepare for Release node, click Build Your Release.
In the Builds tree view, select the type of media you want to build.
In the property list, set or edit the build properties.
To build your Setup program, right-click the selected media type, and click Build.

InstallShield Express places the built Setup package into the following folder:

<project directory>\Express\<media type>\DiskImages\DISK1

Testing Your Setup Program

It is important to test your Setup program. You can do so without running the actual installation using InstallShield Express.

To test your Setup program with InstallShield Express

In the Prepare for Release node, click Test Your Setup.
In the Builds tree view, select the media type containing the build you want to test.
If you want to run the Setup program and install your application and its files on the development computer, click Run Your Setup.

-or-

If you want to test only the Setup dialog boxes and any custom actions you have chosen, click Test Your Setup.

This option does not install any files or make any system changes.

After building and testing your Setup program, you are ready to distribute it.

To distribute your Setup program

In the Prepare for Release node, click Distribute Your Release.
In the Builds tree view, select the media type containing the build you want to distribute.
Enter the location, or click Browse and navigate to the location where your Setup package will be copied.
Click Distribute to Location.

You can also copy your Setup package to an FTP location.

For additional information and options for distributing applications, see the InstallShield Express documentation.

This walkthrough assumes you are installing a simple Visual FoxPro application that does not have dependencies other than the Visual FoxPro Runtime Libraries. The following information includes instructions needed for distribution scenarios other than installing only Visual FoxPro applications and their native data. For these scenarios, add the following appropriate merge modules when selecting objects and merge modules for your Setup program.

Web Services and SOAP

If your application uses Web services or SOAP, you must include the following merge modules:

SOAP SDK Files (Soap_Core.msm)
Visual Basic Virtual Machine (MSVBVM60.msm)
Microsoft Component Category Manager Library (Comcat.msm)
Microsoft OLE 2.40 (OLEAUT32.msm)

Applications using Visual FoxPro Report Application Components

If your application uses the default Report Builder Application, Report Output Application, or Report Preview Application, and you want to ensure that these components are available to your application by default, include the following merge module:

Visual FoxPro 9 Report Applications (vfp9rptapps.msm)

For more information, see Including Report Files for Distribution.

Microsoft Visual FoxPro OLE DB Provider

The Visual FoxPro OLE DB Provider makes it possible for both Visual FoxPro and other applications to access Visual FoxPro data using OLE DB or ActiveX® Data Objects (ADO). To install the Visual FoxPro OLE DB Provider on the destination computer, include the Microsoft Visual FoxPro OLE DB Provider (VfpOLEDB.msm) merge module.

ActiveX Controls

ActiveX controls are a common element of many Visual FoxPro applications. To include ActiveX controls with your InstallShield Express Setup, you should include the Microsoft Component Category Manager Library (Comcat.msm) merge module.

Note
Windows 2000 and Windows XP also install files in this merge module.

The ActiveX controls you install affect the type of merge modules you need to install and the extra steps you must take to install them.

Common ActiveX Controls

These are common ActiveX controls that ship with Visual FoxPro and Microsoft Visual Studio. InstallShield Express ships with merge modules for most of these controls.

If necessary, add the appropriate merge module for the needed control. For example, if your application uses the Treeview control, you should include the MSCOMCTL.msm merge module.

Note

The Common ActiveX Controls included in the InstallShield Express merge modules contain registration information that is compliant with Windows Installer.
Microsoft Foundation Class (MFC) Controls

Some older controls, such as the Calendar control, use the MFC libraries; therefore, it is recommended that you include the appropriate MFC merge modules, such as MFC42.msm. As with VBCCE controls, you must add the control manually to the project and set various settings.
Third-party controls

Be sure to register any included third-party controls. In addition, you might need to add specific registry keys using the InstallShield Express Registry window for any necessary licensing requirements.

For more information about third-party controls, see the documentation provided by the vendor about how and where to install these controls. Third-party control documentation should also provide information about any needed dependency files, such as MFC files.

Note
The Common ActiveX Controls included in the InstallShield Express merge modules contain registration information that is compliant with Windows Installer.

To make sure that Windows Installer can roll back or advertise installed files, you must install files in a manner compliant with Windows Installer requirements. Self-registration of files is not compliant with Windows Installer requirements. You can make sure InstallShield Express installs COM objects that are compliant with Windows Installer by following the instructions about registering files in this topic. For more information, see the InstallShield Express online documentation.

Applications Using HTML Help

The Microsoft Visual FoxPro HTML Help Support Library (VFP9HTMLHelp.msm) merge modules include both FOXHHELP9.exe and FOXHHELPPS9.dll files needed to support context-sensitive HTML Help within your Visual FoxPro applications.

In addition to your application-specific .chm file, you can include the core HTML Help viewer files. Later versions of Microsoft Internet Explorer include these files. You also can distribute them with the HHUPD.exe file available on the Microsoft Developer Network (MSDN).

Applications Using MDAC Components

For Visual FoxPro applications running on operating systems earlier than Windows 2000 or Windows XP, it is recommended that you include the Microsoft Data Access Components (MDAC) merge module (MDAC25.msm) if your applications use any of the following data components:

ODBC drivers, including Microsoft Visual FoxPro ODBC Driver (VFPODBC.msm)
OLE DB Provider
ADO, RDS

COM Servers

The Windows Installer rollback and advertising features make it possible to undo component installation and registration if the product installation does not succeed. However, you must install and register COM objects correctly to make these features available. To register installed COM objects correctly, set the Registration Type to Extract COM Information. Self-registering installed COM objects sacrifices Windows Installer rollback and advertising functionality.

For more information, see the instructions about registering files in this topic.

Localized Applications

The Visual FoxPro Runtime Libraries (VFP9Runtime.msm) contain the standard language-neutral resource file (VFP9renu.dll) used for shipping all English (US) applications. If you want to include support for another localized resource file (VFP9Rnnn.dll), include the appropriate Microsoft Visual FoxPro Resource merge module that contains the localized resource file you want.

Note
Localized resource files do not localize Setup dialog boxes. You can select the desired language for Setup dialog boxes when you create your Setup project.

To include a localized Visual FoxPro resource file

In the Specify Application Data node, click Redistributables.
To identify the Microsoft Visual FoxPro Resource merge module you want, look at the description for each merge module in the lower-left pane.

Select the merge module you want.

For example, to include the German resource file, select the VFP9rdeu.msm merge module. The following table lists available merge modules containing the corresponding localized resource files.

Language	Merge Module
Chinese, Simplified	VFP9rchs.msm
Chinese, Traditional	VFP9rcht.msm
Czech	VFP9rcsy.msm
French	VFP9rfra.msm
German	VFP9rdeu.msm
Korean	VFP9rkor.msm
Russian	VFP9rrus.msm
Spanish, International Sort	VFP9resn.msm

Prerequisites

Creating the Setup Program Using InstallShield Express