Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield Express
Microsoft Visual FoxPro 7.0
Summary: InstallShield Express - Visual FoxPro Limited Edition provides an easy and intuitive way to package and deploy your Visual FoxPro application. Using the InstallShield Express comprehensive and flexible Setup creation technology for Windows Installer, you can create a Setup project or package, including specifying files and their properties, and then distribute the application files from Setup. (10 printed pages)
InstallShield Express uses Microsoft® Windows® Installer, which makes it possible for users to install and configure your products and applications efficiently. 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.
This white paper is not meant as a replacement for the InstallShield Express documentation, which you should read first. It is merely a supplement to assist Microsoft® Visual FoxPro® developers in using InstallShield Express to package and deploy applications. For more information on InstallShield options, see the InstallShield Express documentation.
**You can use any Setup creation program that uses Windows Installer technology to create .msi or .msm Setup packages. This paper describes how to use InstallShield Express included with Visual FoxPro.
There are several issues you should consider before you prepare your application for distribution. You must identify the structure of your application, decide how it will be delivered to users, and decide what will be the best organization of your Setup program. When all the issues have been addressed, you are ready to distribute your Visual FoxPro application.
To distribute Visual FoxPro applications
- Build an application or executable file. For more information about building an application, see "Compiling an Application" in the Visual FoxPro online Help.
- Create a distribution directory containing all the files a user must have to run your application.
- Create an installation package using a Windows Installer deployment program, such as InstallShield Express - Visual FoxPro Limited Edition.
- Package and distribute your application disks and any printed documentation. Depending on the Setup creation program you use, the program might create the disk images for you, or you might have to copy the files to the distribution location manually.
To use InstallShield Express - Visual FoxPro Limited Edition, you must install the components from the Visual FoxPro 7.0 Setup page (VFPStart) located at the root directory of the Visual FoxPro 7.0 CD. For additional information about InstallShield Express, see the InstallShield online documentation.
Preparing Your Application for Distribution
Before you can distribute your application, you must build an application file with an .app extension, an executable file with an .exe extension, or a COM component (automation server) with a .dll extension.
Prior to building your application, make sure that your project includes the necessary files for your application, as well as any resource files, such as graphics files or templates. For more information about the types of files you can include in your application, see "Including Resources in Applications" in the Visual FoxPro online Help.
The development environment of Visual FoxPro contains many features and files that are licensed for your use only. If your application contains any of these features or files, you must remove them from your application before creating your Setup program. For a list of redistributable files, see Redist.txt, located in your Visual FoxPro directory (C:\Program Files\Microsoft Visual FoxPro 7) and "Removing Restricted Visual FoxPro Features and Files" in the Visual FoxPro online Help.
When you choose the type of build you want to create, consider the size of your final application file and whether users have Visual FoxPro installed on their computers.
Application (.app) file
Executable (.exe) file
COM Server (.dll) files
**Note **A COM server also can have an .exe extension.
Some distribution scenarios might require merge modules in addition to the Visual FoxPro run-time files. For more information, see "Visual FoxPro Distribution Scenarios" later in this white paper.
Ensuring Correct Run-Time Behavior
An executable application file always checks for the presence of the Visual FoxPro Run-Time Library, Vfp7r.dll. To run an application .exe file using the development version of Visual FoxPro, you must force the application to use the Visual FoxPro VFP7.exe file instead. For more information, see "Ensuring Correct Run-Time Behavior" in the Visual FoxPro online Help.
Creating the Setup Program Using InstallShield Express
The first step in creating your Setup program is to create the Setup project. The Setup you create with InstallShield Express is based on a project (.ism) file. This file stores all the logic and information necessary to build your Windows Installer-compatible Setup (.msi) file.
To create a Setup project
- Open InstallShield Express.
- On the File menu, click New. The New Project dialog box appears.
- Type or browse to the path and file name of your new project in the Project Name and Location field.
- Click OK.
Defining Project Properties
Now that you have created your Setup project, you can define its properties, such as a product name, product icons, product version, default location for all application files, as well as identify a readme file from the General Information view in InstallShield Express. At a minimum, you should specify a product name and a default installation directory (Installdir property). In addition, you might want to change the value of the Databasedir property if you will be installing data files.
To specify general information for your Setup project
- In the Organize Your Setup node, navigate to the General Information view.
- To select the property you want to edit, click its value field in the property sheet.
- Enter a new value for the property.
- Click elsewhere in the property sheet to see your changes take effect.
Dividing Your Product Into Features
In InstallShield Express, a feature is a building block of an application from the end user's perspective. For example, during the installation of Visual FoxPro, the Visual FoxPro Samples and Visual FoxPro Tools are features that you can specify to be installed or not installed.
**Note **Although it can be helpful to users, dividing your product into features is not a required step in creating a Setup program.
To create a feature
In the Organize Your Setup node, navigate to the Features view.
Right-click the Features node of the tree view in the right pane, and click New Feature.
Type a name for the new feature, and press Enter.
When you have identified the features of your product, you can set properties for those features, such as descriptions of the feature, advertisement options for the feature, and whether the feature is required. Advertised features are not installed during setup, though to the user the features appear to be installed. When the user first tries to use an advertised feature, Windows Installer then installs the feature.
To set a property of a feature
- Select the feature you would like to modify.
- In the property sheet, select the property you want to edit by clicking its value field.
- Enter a new value for the property.
For example, suppose you wanted to give the user the option of installing the Help file for your application. Follow the previous 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 to obtain help, set the Advertised property to "Yes."
Specifying Features for Each Setup Type
You have the option of choosing features for each Setup type. A typical setup installs all features and files, a minimal setup installs the minimum number of features and files necessary for your application to function, and a custom setup makes it possible for the user to specify which features to install.
**Note **Specifying Setup type features is not a required step in creating a Setup program.
To specify features for each Setup type
- In the Organize Your Setup node, navigate to the Setup Types view.
- Select the check box for each Setup type you want to use.
- Click a Setup type, and then select the check box for each feature you want to install with this Setup type.
Adding Files to Your Setup
Visual FoxPro provides several 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 your Setup.
To add files to your Setup, use the Files Explorer, which is divided into four panes. The two left panes contain folders, and the two right panes display the files located within those folders. Above these four panes is the Features box. Before you add files to your Setup, you must select the feature with which you want your files associated. The feature that appears in the Features box is the feature to which your files are added.
To install a source file to a destination folder when Setup is run
Drag the file from the Source Files frame onto the destination folder.
**Note **INSTALLDIR is your most likely target location, because this is the root directory for your application's files.
The Destination Folders frame makes it possible for you to utilize a list of predefined destinations, such as the installation root directory (INSTALLDIR).
To access these destinations
- Right-click Destination Computer.
- Click Show Predefined Folders.
- Select the folder you would like to use.
If desired, you can create multiple subfolders in each destination folder.
To create a subfolder of a destination folder
- Right-click a destination folder, and click Add.
- To rename your new folder, select it, press F2, and type in the new name.
COM servers, such as ActiveX, COM, and COM+ files, require special registration so applications can access the files' interfaces. Traditionally, these .exe, .dll, and .ocx files contained self-registration functions that could be invoked to register the files during installation. However, relying on self-registration can cause some problems with Windows Installer. It is recommended highly that you choose the "Extract COM Information" option. If you choose "Self-registration" instead of "Extract COM Information," Windows Installer will not have the information necessary to unregister and uninstall the COM server properly.
To register COM servers with InstallShield Express
- Right-click the file that you want to register.
- On the shortcut menu, click Properties.
- In the Properties dialog box, click the Advanced tab.
- Select a Registration Type.
For more information registering COM servers, see "Visual FoxPro Distribution Scenarios" later in this white paper.
Selecting Objects/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. For example, the Visual FoxPro run-time files must be copied to the target computer, and they must be registered. The Microsoft Visual FoxPro 7.0 Run-Time Libraries merge module will copy and register the run-time files properly, if the merge module is selected for the InstallShield Express Setup.
To select objects/merge modules to be installed
- In the Specify Application Data node, navigate to the Objects/Merge Modules view.
- Select the Object/Merge Modules check box.
- In the list of merge modules, select the check boxes of each one you want to install. At a minimum, you should select the Microsoft Visual FoxPro 7.0 Run-Time Libraries and, if you are installing a Visual FoxPro application, the Microsoft Visual C++ 7.0 Run-Time Library.
- You can install a merge module on a feature-by-feature basis by selecting or clearing the check boxes in the Conditional Installation pane.
For more information on merge modules, see "Visual FoxPro Distribution Scenarios" later in this white paper.
Creating Shortcuts and Folders
InstallShield Express makes it possible for you to create shortcuts and folders both in the Start menu and on the desktop. In addition, shortcuts can be associated with the features that you defined earlier.
To create shortcuts or folders
In the Configure the Target System node, navigate to the ShortCuts/Folders view.
From the Shortcuts tree view in the right pane, right-click the node where you want to install a shortcut or folder, and click New Shortcut or New Folder.
Type a name for the item you created, and press Enter.
If you created a shortcut, you must specify a target. In the Shortcut Properties pane, select the Target property, and then select a target from the list box.
**Note **Files for your application are at the bottom of the list box.
You have the option to associate your shortcut with a feature. Select the Feature property, and then select a feature from the list box.
Creating Registry Keys
If your application uses registry keys to keep track of user options, for instance, InstallShield Express can add them to the target machine during setup.
**Note **Creating registry keys is not a required step in creating a Setup program.
If the keys do not exist on the development machine, you can create them by hand. Registry entries are created in registry hives. Registry hives categorize registry entries by function. For example, COM server classes are contained in the HKEY_CLASSES_ROOT registry hive. Software options, such as options for Visual FoxPro, are contained in the HKEY_CURRENT_USER hive under Software.
To create registry keys
- Right-click the registry hive on the destination computer's registry view.
- On the Context menu, click New/Key.
- Type a name for the key, and press Enter.
- Right-click the new key.
- On the Context menu, click New, and then select the type of value you want to add to the key.
Creating ODBC DSNs
If the development machine has pre-existing Data Source Names (DSNs), you can direct InstallShield Express to install the DSN on the target machine. If you are installing DSNs, you should include the MDAC merge module when you select merge modules (in the earlier step, "Selecting Objects/Merge Modules") in case the target machine does not have ODBC components installed.
**Note **Creating ODBC DSNs is not a required step in creating a Setup program.
To create DSNs
- In the Configure the Target System node, navigate to the ODBC Resources view.
- In the ODBC Resources tree view, select the check boxes for the DSNs you want to create on the target machine.
Building Your Setup Program
Before building your package, make sure that you have finished designing and setting the properties for every element in your Setup project, including the features, files, shortcuts, registry entries, and user interface. When you have finished that, you are ready to build a Setup program.
To build a Setup program
In the Prepare for Release node, navigate to the Build Your Release view.
Select the type of media you would like to build in the Build Explorer.
Edit the build properties in the property sheet.
To build your Setup, right-click the selected media type and, on the shortcut menu, click Build.
InstallShield places the built Setup package into the <project directory>\Express\<media type>\DiskImages\Disk1 folder.
Testing Your Setup Program
It is important to test your Setup program. You can use InstallShield Express to test your Setup program without having to run Setup.
To test your Setup program with InstallShield Express
In the Prepare for Release node, navigate to the Test Your Setup view.
Select the media type that contains the build you would like to test.
The right pane offers two options: Run Your Setup and Test Your Setup. If you choose to run your Setup, the Setup will behave as it would on the user's machine, including the installation of your Setup files. If you choose to test your Setup, all of the Setup dialog boxes will be displayed, but no files will be installed, and no system changes will be made.
Distributing Your Application
After you have built and tested your Setup program, you are ready to distribute it.
To distribute your Setup program
- In the Prepare for Release node, navigate to the Distribute Your Setup view.
- Select the media type that contains the build you would like to distribute.
For additional information and options for deployment, see the InstallShield Express online documentation.
Visual FoxPro Distribution Scenarios
The previous steps assume you are installing a simple Visual FoxPro application that has no dependencies beyond the Visual FoxPro Run-Time Libraries. The following information includes steps that are required for distribution scenarios that go beyond installing just Visual FoxPro applications and their native data. The following merge modules should be added when you select merge modules (see the earlier procedure, Selecting Objects/Merge Modules).
Web Services and SOAP
If your application utilizes Web Services or the Simple Object Application Protocol (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)
Microsoft Visual FoxPro OLE DB Provider
The Visual FoxPro OLE DB provider makes it possible for both Visual FoxPro and non-Visual FoxPro applications to access Visual FoxPro data using OLE DB or ActiveX Data Objects (ADO). To install the Visual FoxPro OLE DB provider on the target machine, include the Microsoft Visual FoxPro OLE DB Provider (VFPOLEDB.msm) merge module.
A common element of many Visual FoxPro applications is ActiveX controls. To include ActiveX controls with your InstallShield Express Setup, you should include the COMCAT.msm merge module.
**Note **Windows 2000 also installs files in this merge module.
The ActiveX controls you install determine the merge modules to install and the extra installation steps you must take.
**Common ActiveX Controls **These are the common controls, which ship with Visual FoxPro 7.0 and Microsoft® Visual Studio® 6.0. InstallShield Express ships with merge modules for most of these controls. Simply add the appropriate merge module for that control. For example, if your application uses the Treeview control, you should include the MSCOMCTL.msm merge module.
**Visual Basic Control Creation Edition (VBCCE) Controls **Microsoft® Visual Basic® 6.0 makes it possible for developers to create custom ActiveX Controls. You must add this control manually to the project and set certain properties, such as install location and registration. As in Registering Files earlier in this white paper, you can set the Registration Type to Self-Register. The install location for this control can be the same as the application if the control is not likely to be shared with other applications. In addition to the actual control, you also must include the Visual Basic Virtual Machine merge module (MSVBVM60.msm).
**MFC Controls **Some of the older controls, such as the Calendar control, use the MFC libraries. You should include the MFC42.msm merge module. As with VBCCE controls, you must add the control manually to the project and set various settings.
**Third Party Controls **Refer to documentation provided by the vendor on how and where to install the control. Make sure you register the control. The documentation also should provide information on any dependency files needed, such as MFC and Visual Basic run-time. In addition, you might have to add specific Registry keys (use InstallShield Express Registry window) for any necessary licensing requirements.
Applications with HTML Help
The Microsoft Visual FoxPro HTML Help Support Library (VFPHTMLHelp.msm) merge module includes both FOXHHELP.exe and FOXHHELPPS.dll files needed to support context HTML Help within your Visual FoxPro 7.0 applications. In addition to your application-specific .chm file, you might have to 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 MSDN.
Applications Using MDAC Components
If your applications use any of the following data components, you will want to include the Microsoft Data Access Components merge module (MDAC26ENU.msm).
- ODBC Drivers including the Visual FoxPro driver (VFPODBC.msm)
- OLE DB Providers
- ADO, RDS
Correctly installing and registering COM objects is necessary to take advantage of Windows Installer rollback and advertising features. With Windows Installer you can:
- Rollback an unsuccessful installation to return the target machine to its pre-installation state.
- Advertise installed products or even individual elements of a product, such as COM objects. Advertising makes a product or COM object available to the user or target machine by placing a shortcut in the appropriate place, such as the Start menu or registry without installing the product until the user, or another machine function, specifically calls the advertised element.
To support rollback of component installation and registration if your product installation fails, as well as component advertisement on the target machine, you must register installed COM objects by setting the Registration Type in to Extract COM Information. You can choose not to do so by self-registering your installed COM objects, but this sacrifices the enhanced Windows Installer rollback and advertising functionality.
With traditional scripted Setup programs, self-registration was the accepted method for installing COM objects, and it is still a viable method. However, Windows Installer cannot perform rollback installations and registration of self-registered COM objects, and it cannot advertise those objects. This is because self-registering COM objects do not pass their installation and registration information to Windows Installer.
The VFP7Runtime.msm file includes the standard language-neutral resource file (VFP7RENU.dll), which is used for all English (US) shipping applications. If you want to include support for another localized resource file (VFP7Rxxx.dll), include the merge module containing the localized resource file. For example, include VFP7RDEU.msm for the German run-time resource file.
**Note **You must look in the merge module description pane to determine localized merge module file name.
|Spanish (International Sort)||VFP7RESN.msm|
For more information about deployment options for Visual FoxPro applications, see the MSDN Library.
For additional information about InstallShield Express, see the InstallShield Express online documentation.
The Windows Installer Components can be downloaded from the Platform SDK.