Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield

When you are ready to distribute an application, you can create a setup program to help your customers install it. This walkthrough explains considerations you should make prior to distributing the application and shows how to create a Setup project, include files and set their properties, and distribute the application files from Setup using InstallShield Express Visual FoxPro Limited Edition.

This walkthrough contains the following sections:

• Prerequisites

• Creating the Setup Program Using InstallShield Express

• Distributing An Application

For more information about distributing applications, see Distributing Applications.

Prerequisites

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.

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 https://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 Program Using InstallShield Express

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

1. On the Start menu, point to All Programs. Point to InstallShield, and click Express to open InstallShield Express.

2. On the File menu, click New to open the New Project dialog box.

3. 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.

4. 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.

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

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

1. In the Organize Your Setup node, click General Information.

2. In the property list, double-click the value field of a property to edit its value.

3. 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.

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

To create a feature

1. In the Organize Your Setup node, click Features.

2. To add a new feature, right-click the Features node in the tree view in the middle pane, and click New Feature Ins.

3. 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

1. Select the feature for which you want to modify properties.

2. 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.

3. 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.

To select Setup types and specify features for each Setup type

1. In the Organize Your Setup node, click Setup Types.

2. In the Setup Types pane, select the check box for each Setup type you want to include.

3. 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.

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

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

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

2. 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

1. In the Destination computer's folders pane, right-click Destination Computer.

2. Click Show Predefined Folders.

3. 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

1. Right-click the destination folder, and click Add.

2. 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

1. In the Specify Application Data node, click Files.

2. Copy the file for the COM Server from the source folder to the destination folder.

3. Right-click the file you want to register, and click Properties.

4. In the Properties dialog box, click the COM & .NET Settings tab.

5. 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.

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

1. In the Specify Application Data node, click Redistributables.

2. In the InstallShield Redistributables pane, select the check box for each merge module you want to install.

3. 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

1. In the Configure the Target System node, click ShortCuts/Folders.

2. 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.

3. 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.

4. 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.

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.

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

1. In the Configure the Target System node, click Registry.

2. In the Destination computer's Registry view pane, right-click the desired registry hive.

3. On the shortcut menu, point to New, and click Key.

4. Type a name for the key, and press ENTER.

5. Right-click the new key, point to New, and select the type of value you want to add to the key.

6. 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.

To create DSNs

1. In the Configure the Target System node, click ODBC Resources.

2. 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.

To select dialog boxes

1. In the Customize the Setup Appearance node, select Dialogs.

2. 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

1. In the Customize the Setup Appearance node, select Dialogs.

2. 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

1. In the Prepare for Release node, click Build Your Release.

2. In the Builds tree view, select the type of media you want to build.

3. In the property list, set or edit the build properties.

4. 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

1. In the Prepare for Release node, click Test Your Setup.

2. In the Builds tree view, select the media type containing the build you want to test.

3. 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.

Distributing an Application

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

To distribute your Setup program

1. In the Prepare for Release node, click Distribute Your Release.

2. In the Builds tree view, select the media type containing the build you want to distribute.

3. Enter the location, or click Browse and navigate to the location where your Setup package will be copied.

4. 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.

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.

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.

To include a localized Visual FoxPro resource file

1. In the Specify Application Data node, click Redistributables.

2. To identify the Microsoft Visual FoxPro Resource merge module you want, look at the description for each merge module in the lower-left pane.

3. 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

See Also

Reference

Resource Files in Applications

Concepts

Distributable and Restricted Visual FoxPro Features and Files

Other Resources

Walkthroughs