Using Microsoft Visual Studio Installer for Distributing Visual FoxPro 6.0 Applications

Microsoft Corporation

December 1999

Summary: This article is a supplement to assist Microsoft Visual FoxPro 6.0 developers in using the Visual Studio Installer as an alternative to the Visual FoxPro 6.0 Setup Wizard. (13 printed pages)

Click to download the VFP_VSI.exe sample file.

Introduction

The Microsoft® Visual Studio® Installer is a great new tool you can use to create customized setups for your Visual FoxPro® distributed applications. It is based on the new Microsoft Windows® installer, which reduces the total cost of ownership (TCO) for your customers by enabling them to efficiently install and configure your products and applications. The new Windows installer is part of the Windows 2000 and Zero Administration Windows (ZAW) efforts to reduce the overall cost of deploying, using, and managing desktop computers.

This article is not meant as a replacement for the Visual Studio Installer (VSI) documentation, which you should read first. It is merely a supplement to assist Visual FoxPro developers in using VSI as an alternative to the Visual FoxPro 6.0 Setup Wizard. We highly recommend you reread the Visual Studio Installer Best Practices section on how to package your application components, available in the VSI documentation.

Additionally, you should read the accompanying tutorial article, “Microsoft Visual FoxPro 6.0 Visual Studio Installer Tutorial,” which walks you through the process of creating an installer package with your Visual FoxPro application.

This article is broken down into sections based on typical distributed application scenarios. At the end, you will find a reference guide to assist you in creating VSI setup scripts.

Visual FoxPro Distribution Scenarios

Simple Executable Application

Many typical Visual FoxPro applications today are built entirely with Visual FoxPro and use native Fox data (that is, .dbc and .dbf files). The following steps are general guidelines to follow for creating a Visual Studio Installer setup for your Visual FoxPro distributed application.

Note   The accompanying tutorial, “Microsoft Visual FoxPro 6.0 Visual Studio Installer Tutorial,” provides more details if you are not familiar with the basics of using Visual Studio Installer.

1. Open a new project. Launch the Visual Studio Installer and select a new project of type Empty Installer.
   
   
2. Add application files. You can add files from the Project menu’s Add File(s) item or drag and drop them from the Windows Explorer to either the Project Explorer or File System window. (You cannot drag and drop an entire folder, only files from within.)
   
   
3. Set application file locations. This step ensures that your application files are installed in the proper target location. Use the File System window to place files in the location where you want them installed.

   Note   If you manually drag and drop files from the Windows Explorer, the application folder structure is not preserved. You need to manually add subfolders to the Application Folder in the File System window to preserve the folder structure.

4. Set file-specific settings. Open the Properties window to set individual file install settings for any file in your VSI project.
   
   
5. Add a shortcut to application. You can select the User’s Desktop or User’s Start Menu folder in File System window as a place to create a shortcut to your main application. After selecting the desired location, right-click on the right pane and select Create Shortcut. Pick the name of your application from the dialog. If you want, you can add additional shortcuts to other files your application uses.
   
   
6. Add required merge modules. Merge modules are packages of files and install information for common shared components. With Visual FoxPro applications, you should include the following merge modules:
   • VFP6RUN.MSM
     
     
   • MSVCRT.MSM
     
     
   • OLEAUT32.MSM

   Merge modules that ship with VSI are installed in the following location:

   C:\Program Files\Microsoft Visual Studio\Common\Tools\VSInst\BuildRes
   

   This location includes MSVCRT.MSM and OLEAUT32.MSM. Merge modules can be added to your project in a way that is similar to how you add a file. The Project menu’s Add Merge Module(s) item allows you to do this.

   Note   Windows 2000 installs files in these last two merge modules under System File Protection. If you are only distributing your application to customers running Windows 2000, you do not need to include these modules.

7. Set Project Options. You do this through the Project menu’s myproject Properties item (see VSI documentation).

   Important   Choose the appropriate Build Type option based on your target customer. Picking the Installer with Windows Installer Loader option will add an extra 2.6 megabytes (MB) to the entire setup, but it is required for customers who do not have the Windows Installer loaded on their machines.

8. Set additional VSI installer options (see VSI documentation).
   
   
9. Build your .msi installer package file by selecting Build from the Build menu.

The output of your project is a Microsoft Installer package file (.msi), which any user can double-click to run. See the section Distributing Your Application below for more details.

Executable Application with ActiveX Controls

A common element of many Visual FoxPro applications is ActiveX® Controls. You can include ActiveX Controls with your VSI setups by following these steps:

1. Follow steps in the Simple Executable Application scenario above.
   
   
2. Include the COMCAT.MSM merge module. Note that Windows 2000 also installs files in this merge module.
   
   
3. Follow additional steps below based on specific ActiveX Controls being installed:

   Common ActiveX Controls—these are the common controls, which ship with Visual FoxPro 6.0 and Visual Studio 6.0. VSI ships with merge modules for most of these controls. Simply add the appropriate merge module for that control (see the Reference Guide below). For example, if your application uses the Treeview control, you should include the MSCOMCTL.MSM merge module.

   VBCCE Controls—Visual Basic® 6.0 allows developers to create custom ActiveX Controls. You will need to manually add this control to the project and set certain properties (for example, install location, registration). You can set the Register property for the ActiveX Control file to vsifrSelfReg (1) to register the file (see “Important” below for more details). 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 will also need to include the Visual Basic run-time 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 if this is the case. As with VBCEE controls, you will need to manually add the control 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 should also provide information on any dependency files needed (for example, MFC, Visual Basic run time). You may also have to add specific Registry keys (use VSI Registry window) for any necessary licensing requirements.

Important   To ensure the Microsoft Windows installer knows about your installed files to roll back or advertise them, you must install the files in a manner compliant with Windows Installer requirements. Self-registering your files is not compliant with Windows installer requirements. The Associations Editor in Visual Studio Installer makes it possible for you to install Windows installer-compliant COM objects. For more information, see the Visual Studio Installer documentation.

If you choose to register controls by setting the Register property to vsifrSelfReg, then you should also set the SharedLegacyFile property so that the application can be properly reference counted. This is essential if that control is shared by multiple applications.

Note   The Common ActiveX Controls included in the VSI merge modules contain registration information that is Windows installer-compliant.

Applications with HTML Help

The VFP6RUN.MSM merge module includes both FOXHHELP.EXE and FOXHHELPPS.DLL files needed to support context HTML Help within your Visual FoxPro 6.0 applications. Besides your application specific .chm file, you will need to include the core HTML Help viewer files. The HTML Help viewer files are available as a redistributable called HHUPD.EXE, which can be downloaded from the MSDN Web site http://msdn.microsoft.com/workshop/author/htmlhelp/download_main.asp. Users will need to run this HHUPD.EXE installer after they run the .msi installer.

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 (MDAC.MSM).

• ODBC Drivers
  
  
• OLE DB Providers
  
  
• ADO
  
  
• RDS

Important   The MDAC merge module does not actually contain any MDAC files. It simply provides a check for the installer. If MDAC is not installed on the user’s system, then a message dialog is displayed indicating that the user needs to also install these components. You will still need to include the actual MDAC redistribution setup with your application. This setup (MDAC_TYP.EXE) is included at the following Visual FoxPro 6.0 SP3 location:

<vfproot>\Distrib.src\System\

You can also obtain MDAC_TYP.EXE from the Microsoft web site. Users will need to run the MDAC_TYP.EXE installer manually after they run the .msi installer.

Shared Components

Often, applications consist of components that are shared by multiple applications. Visual FoxPro frameworks, foundation classes, and other shared files and class libraries are examples of these types of components. As described in the Visual Studio Installer documentation, it is recommended that these types of files be combined into merge modules, which can be included later with any application installer package. This ensures that files are always installed in a consistent manner.

The Visual Studio Installer also lets you combine files (as well as shortcuts, registry keys, and so on) into a common component. However, the Visual Studio Installer best practice recommendation is to make each file included in your installer project a component. One of the limitations of combining multiple files into a single component is that all files must be installed in the same directory on the target machine. A good example of when you might combine multiple files into a single component is Visual FoxPro binary files (for example, dbf/fpt, scx/sct, frx/frt, lbx/lbt).

COM Servers

A specific example of components that could be packaged into merge modules is a Visual FoxPro COM Server (both Local .exe and In-Proc .dll servers). You can then add your COM Server merge module to any VSI installer project.

Correctly installing and registering COM objects is necessary to take advantage of Windows installer rollback and advertising features. As explained in the VSI documentation, two powerful features of the Windows installer are the abilities to:

• Roll back an unsuccessful installation, returning the target machine to its preinstallation 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 rolling back component installation and registration if your product installation fails and component advertisement on the target machine, you must register installed COM objects by establishing the necessary associations. 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, the Windows installer cannot perform rollback installations and registration of self-registered COM objects, and it cannot advertise those objects. This is because self-registered COM objects do not pass their installation and registration information to the Windows installer.

To ensure that the Windows installer knows enough about your installed COM objects to perform a rollback on or advertise them, you must install those COM objects in a manner compliant with Windows installer requirements. With the Associations editor in Visual Studio Installer, you can install Windows installer-compliant COM objects.

Additionally, type library information for the COM Server must also be captured because it is also registered in the Registry. With Visual FoxPro, a type library can be bound inside of the .exe or .dll server file, or exist separately as a .tlb file.

When authoring a VSI setup to include a Visual FoxPro COM Server, you have two options for handling server registration:

Option 1: You can set the Register property for the COM Server file to vsifrSelfReg (1). This option performs the older style self-registration. However, you lose many of the Windows installer capabilities just mentioned. It is the easiest option for authoring your VSI setup.

Option 2: The recommended approach for registering COM servers requires a little more work. You will need to manually add Registry keys and COM Object associations to the VSI setup. Let’s walk through an example (note that all the sample files are included with the sample download at the top of this article):

1. First, add your COM server file(s) to the setup. This is either the .exe or .dll file you created. If you built this file using Windows NT® under Visual FoxPro 6.0 Service Pack 3 (SP3), you do not need to include the .tlb type library file because it is bound into the server file. Otherwise, you need to include this file. After adding these files to the project, make sure to set the Register property to 0 so that they are not self-registered during installation.

   You can optionally add the server’s .vbr file, which is used by CLIREG32.EXE to register a COM server remotely.

   Note   The Visual Studio Installer does not support post-install actions as the Visual FoxPro Setup Wizard does, so you need to run CLIREG32.EXE separately after the setup.

2. Open up the File System window from Target Machine node and select an install location for your server components. The Visual FoxPro 6.0 Setup Wizard typically installs COM servers in the Windows\OleSrv\ folder. You can choose to install to this location if you feel that your component may be shared by multiple applications. If you want to isolate your component specific for a single application, you can install it in the same location as the application.
   
   
3. Author the Registry keys necessary to register the COM server. You can obtain the information to do this by opening up the .vbr file for that server. This file contains all the Registry keys written out when one self-registers a COM server (for example, REGSVR32 foxdemo1.dll). The following .vbr file contents are from a sample COM server called FOXDEMO1.DLL (note that this sample has just one OLEPUBLIC server and is specific for a multithreaded .dll server):

   VB5SERVERINFO
   VERSION=1.0.0
   
   HKEY_CLASSES_ROOT\foxdemo1.foxsvr1 = foxdemo1.foxsvr1
   HKEY_CLASSES_ROOT\foxdemo1.foxsvr1\NotInsertable
   HKEY_CLASSES_ROOT\foxdemo1.foxsvr1\CLSID = {F802CDC0-D690-4603-9936-6860B86A3163}
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163} = foxdemo1.foxsvr1
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163}\ProgId = foxdemo1.foxsvr1
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163}\VersionIndependentProgId = foxdemo1.foxsvr1
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163}\InProcServer32 = foxdemo1.dll
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163}\InProcServer32\”ThreadingModel” = Apartment
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163}\TypeLib = {1995B333-9FA9-4819-A320-DA074AB37324}
   HKEY_CLASSES_ROOT\CLSID\{F802CDC0-D690-4603-9936-6860B86A3163}\Version = 1.0
   HKEY_CLASSES_ROOT\INTERFACE\{DB1D22E5-826B-47DF-95DD-516527BD6E8E} = foxsvr1
   HKEY_CLASSES_ROOT\INTERFACE\{DB1D22E5-826B-47DF-95DD-516527BD6E8E}\ProxyStubClsid = {00020424-0000-0000-C000-000000000046}
   HKEY_CLASSES_ROOT\INTERFACE\{DB1D22E5-826B-47DF-95DD-516527BD6E8E}\ProxyStubClsid32 = {00020424-0000-0000-C000-000000000046}
   HKEY_CLASSES_ROOT\INTERFACE\{DB1D22E5-826B-47DF-95DD-516527BD6E8E}\TypeLib = {1995B333-9FA9-4819-A320-DA074AB37324}
   HKEY_CLASSES_ROOT\INTERFACE\{DB1D22E5-826B-47DF-95DD-516527BD6E8E}\TypeLib\”Version” = 1.0
   
   ; TypeLibrary registration
   HKEY_CLASSES_ROOT\TypeLib\{1995B333-9FA9-4819-A320-DA074AB37324}
   HKEY_CLASSES_ROOT\TypeLib\{1995B333-9FA9-4819-A320-DA074AB37324}\1.0 = foxdemo1 Type Library
   HKEY_CLASSES_ROOT\TypeLib\{1995B333-9FA9-4819-A320-DA074AB37324}\1.0\0\win32 = foxdemo1.dll
   HKEY_CLASSES_ROOT\TypeLib\{1995B333-9FA9-4819-A320-DA074AB37324}\1.0\FLAGS = 0
   

If you take a close look at the .vbr file, you will see that there are four groups of Registry keys that we need to add. These are keys for PROGID, CLSID, INTERFACE, and TYPELIB. All of the keys fall under the HKEY_CLASSES_ROOT Registry hive. It is a good idea to open up the Registry using REGEDIT to see how the keys should appear. You can later run your .msi setup to see if the Registry keys are being written out properly.

• PROGID—the PROGID keys are used by COM when you create an instance of the COM server. For example, in the above server, one would call the following:

  oServer = CreateObject(“foxdemo1.foxsvr1”)
  

  The PROGID keys are simply added to your VSI project through the Registry window. Right-click the appropriate node to add new Keys and String Values. You can copy and paste values from the .vbr file to save time.

• CLSID—the CLSID keys (HKEY_CLASSES_ROOT\CLSID) require a little extra work because you will want to associate your COM server with these keys. You will first add most of the keys similar to the PROGID keys above using the Registry window.

  Note   A few Registry keys written out during a self-registration are not included in the .vbr file (Implemented Categories and Programmable). The sample includes these. You can also see them in the Registry using REGEDIT.

  Once you have entered all of the Registry keys except the one with the reference to the actual server file, you need to add a COM Object association for this file using the Associations window. The VSI documentation explains this. Make sure you enter the proper CLSID value.

  Note   The Windows installer actually adds an extra string value to this Registry key during install. This value may look a little weird, but it is needed by the Windows installer for features such as Advertising.

• INTERFACE—the Interface keys are entered just like the PROGID keys using the Registry window.
  
  
• TYPELIB—the last set of keys to add are the TYPELIB keys. Again, you will use the Registry window to do this (do not use the VSI Type Libraries option under the Associations window). The one tricky part is entering the name of the file under the WIN32 key because you don’t always know exactly where the file will be installed. The Windows Installer allows you to place custom properties or wildcards in the Value property. For example, you could set the value of the WIN32 key to the following:

  [TARGETDIR]foxdemo1.dll
  

  During the install process, the wildcard placeholder is replaced with the actual value of the folder specific to the target machine. In addition, you will need to use a Windows Installer property for the HELPDIR key. The Appendices below have some of the common Windows installer properties. Refer to the Windows 2000 Platform SDK for more details.

You are now done and simply need to build your .msi installer package or .msm merge module. It is always a good idea to thoroughly test any setup such as this where you have manually entered Registry keys.

Tip   If you are installing your COM Server onto a Windows 2000 or Windows 98 (Second Edition or later) machine, you should seriously consider installing the component directly to the application directory so that it is isolated from other applications. In order to do this, you must use Option 2 to register your component. The one difference to make in your setup is not to use the Associations window for handling the CLSID registry keys. Instead, you should simply add an entry in the Registry window with the name of your COM server but without a path. If no path is included, COM will first look in the application folder for that component. For more details on isolating components, go to http://search.microsoft.com/us/dev/default.asp and search on “DLL Hell.”

Localized Applications

The VFP6RUN.MSM file includes the standard language-neutral resource file (VFP6RENU.DLL), which is used for all English (US) shipping applications. If you want to include support for another localized resource file (VFP6Rxxx.DLL), simply drop that file into the project and install it in the Windows System folder. It does not need to be registered. You should set the File’s DoNotUninstall property to True. For example, include VFP6RDEU.DLL for the German run-time resource file.

Unsupported Scenarios

The Visual FoxPro 6.0 Setup Wizard should still be used for the following scenarios:

• Applications requiring post-executable actions.
  
  
• Applications requiring Microsoft Graph run-time files.
  
  
• COM Servers requiring DCOM and/or remote automation support (this can be done by manually adding Registry keys, but is not as flexible as Visual FoxPro Setup Wizard).

Distributing Your Application

When you distribute your application, you should still follow many of the same guidelines mentioned in the Visual FoxPro documentation. VSI setups (.msi files) use the new Windows Installer technology, which is available on certain platforms. The following steps are general installation instructions when distributing your application to customers. There are two basic scenarios to consider:

• Installer package built with the Installer with Windows Installer Loader Build Type option. In the near future, this is likely to be the type of installation package you will want to create because many of your customers will still be running on older Windows operating systems. The user simply needs to run the SETUP.EXE file to install the entire application. This bootstrap loader file first checks for and, if necessary, installs the Windows Installer, then it installs your .msi package setup.

  —or—

• Installer package not built with the Installer with Windows Installer Loader Build Type option. With these setups, the user already has Windows Installer installed on his or her machine. The user simply needs to run (double-click) the .msi package file to install it.

Install any additional required setups (users will need to run these separately):

• MDAC_TYP.EXE—if your application uses any MDAC components.
  
  
• HHUPD.EXE—if your application uses HTML Help.

Note   Building an installer with the Windows installer bootstrap loader creates these distinct files as part of your installer package. You must include all of these files on the media that you choose to distribute your application:

• Your .msi file.
  
  
• SETUP.EXE—the file that determines whether or not the Windows installer resides on the target machine and installs the Windows installer if necessary.
  
  
• SETUP.INI—the file that tells SETUP.EXE the name of your .msi file to install.
  
  
• INSTMSIW.EXE—the Windows installer for Windows NT machines. (Windows NT 3.51 is not supported.)
  
  
• INSTMSIA.EXE—the Windows installer for Windows 95 and Windows 98 machines.

Appendices

VFP6RUN Merge Module

The VFP6RUN.MSM merge module properly installs the necessary files to support your Visual FoxPro distributed applications, including COM servers, Active Documents, and normal Windows executables. As with the Visual FoxPro 6.0 SP3 Setup Wizard, run-time files are installed and registered in the Windows System directory. Because the VFP6RUN.MSM merge module is properly authored for Windows installer file installation and registration, it can take advantage of rollback and advertising features. The following files are included in the VFP6RUN merge module:

Reference Guide to VSI Merge Modules

Common Windows Installer Properties