Ch-Ch-Changes

What needs to be updated?

This is a question we are often asked. Unfortunately, it is a difficult question to answer, because it depends. It depends on the components changed, whether the Fox Team at Microsoft released a service pack to Visual FoxPro, whether you release source code outside of the main executable, whether you changed the architecture of your application from a monolithic EXE to a main EXE with APPs and DLLs, and a whole bunch of other possibilities. Everything also depends on the type of deployment, what is changing, what the customer already has installed, and how sophisticated the end-users are with respect to installing software.

The following sections list some of the possibilities you might encounter and options you might consider for an update deployment package.

Executables

Your updates likely include a new version of the executable files. This is typically what drives a release. What you release depends on the architecture of your application and what source is altered to include the new functionality or bug fix. If you have one executable, there is a very good chance you replace this file each time. If you release one main EXE and one or more APP files you may find only one of the APP files needs releasing. The same goes for apps architected with FXPs and other source code modules. DLL files might require registration with the operating system.

Runtimes

We always distribute runtimes in deployment packages used for initial installations. We also include them for full install updates. Possibly the customer has new machines or is installing your application on existing machines with no prior version loaded. One event triggering the need to distribute runtimes is an upgrade to Visual FoxPro. It is critical to update the runtime files if you install a new service pack and compile the application with this new service pack.

If you are deploying patch files (see the Upgrades, updates, and patches section in Chapter 5, ‚“Windows Installer Inside and Out ‚½), and you did not update your copy of Visual FoxPro, you do not need the runtimes in the distribution. Remember, patch files only update an existing application. BecauseVisual FoxPro applications require the runtimes, your deployment package installed the runtimes the first time. The patch file will not need the runtimes for the update.

Data and metadata

Updating data files can be a bit tricky and is one of the reasons we prefer releasing data separately from the application installation. You want to make sure new files are installed, existing files updated appropriately, and in this entire process ensure no customer data is lost or accidentally overwritten. This is why we stressed in other parts of this book, you might want to consider file level settings during an install so data files are not overwritten. Be careful when you include data updates in update releases.

Metadata can usually be overwritten every release. We say ‚“usually ‚½ because some developers have clients maintaining or extending their own metadata files. In these special cases, developers have to engineer a process to merge their new metadata with the existing metadata the clients have updated and maintained . If the client does not maintain the metadata, we recommend installing a fresh copy because you may have made changes in development you forgot about as the development cycle proceeded. There are exceptions to this rule, like the case where you have some major development of a new feature started and you need to deploy a quick bug fix for a different part of the solution. If metadata was not affected, it might be safer not to deploy the metadata in the update because the other development could have side effects on the bug fix.

Help file

A new Help file that is not part of the previous release may require not only the CHM file, but also the Visual FoxPro Help runtime files. If the runtimes were already installed as part of the previous release, you only need to distribute the Help file. One thing developers overlook in this regard is you can link to external files and Web sites outside of the Help file. If you include external links, be sure these files are included and the Web site links exist.

ActiveX controls

It is our experience commercial ActiveX controls do not change often so it is uncommon to see ActiveX controls updated. However, when they do change, or when you include a new ActiveX control in your application, you need to make sure it is included in the new setup.

Other

You may be recognizing the pattern established in the previous sections. There are a lot of ifs and different scenarios. It is impossible for us to cover every possibility here. The idea we are establishing is this: keep track of what you change, know what you installed at the client site, determine the differences, and build an install package to deploy the changes. Other files to consider are external report files (Visual FoxPro, Crystal reports , or another third-party product), database scripts, configuration files, images, icons, documentation, and PDFs. Review the list of files you marked excluded in the application project file.

Update architecture

You have several options available to deploy your changes: ship the individual changes to the client and have them copy them into the appropriate folders, create a new installation, or create a patch installation.

Shipping the individual files sounds like the easiest of options at first glance, but what if one of those files is an ActiveX file that needs to be registered? How many sites need to make the update? Shipping individual files might be fine for something like a single executable. It depends on the files shipped and the strength of the user to be able to follow instructions to complete the install. It might be you are doing the install and can easily handle even the most complex registration and know exactly which files install where. End users might not be able to handle even the simplest of tasks . It is a call you need to make when it is time to deploy.

Note ‚  

If you decide to replace an EXE by copying in a new version (outside of the Windows Installer) and the EXE launches from an advertised shortcut, the Windows Installer will repair the component (replacing the EXE with the previously installed version).

Creating a new install might make the most sense for deployments having more than a couple files, end users who like running SETUP.EXE and answering a couple simple questions, or deployments installed at numerous sites. How you accomplish creating an update install depends on the tool you use to create the deployment package. See the section later in this chapter called ‚“Upgrade installs ‚½ for more details on how to approach this scenario with a Windows Installer deployment tool.

The last option is to create a patch file. While you can accomplish this with a Windows Installer Patch file (MSP), you can also create a program (even a Visual FoxPro program) that packages the files and programmatically installs the new files needed for the update. We have seen developers copy updated files into a DBF with a binary memo field holding the new files. A program can scan the DBF and copy the new files to the appropriate location. If you prefer the Windows Installer technology, you can use the patch feature found in some packages to assist you in creating a patch file.

Version numbers

Most developers place a lot of meaning on application version numbers and others include version numbers only because they are available. We like to leverage the version number in several ways with our customers and find it helps in our ability to support them long term .

We keep track of changes made for each release so new developers can learn the history of the application. This application document is a log of changes made throughout a product ‚ s life cycle. Developers and customers alike can review the list of features included in each release. We can use this same information for the marketing material so potential customers can review the list of features, and see how quickly and frequently we add functionality to the application they are considering purchasing for their business.

We use internal build numbers with the development staff to make sure the test team is testing the latest version. Bug reports always should include a version and build number. First, it helps the developer understand when they potentially broke part of the application. Second, it helps to see when features were fixed. Third, it reinforces the test team is testing the current build. If they notice the build number is lower than the last build they tested , they know the version they are running is not the current version. Testers can also compare functionality between builds to understand the behavior of a problem and how it changed between the builds.

Version numbers help in supporting customers who report a problem or are looking for a new feature. They ensure customers are running the proper version (maybe they are only licensed for an older version) and the issue they raised may be fixed or enhanced in a newer version. They help you determine if the customer downloaded the latest version sent to them, whether they need to update their subscription, or pay for an upgrade.

Develop a system that works for you. We leverage all three version levels provided internally in Visual FoxPro applications (XX.YY.ZZZZ) and follow these basic guidelines:

• The first number is the major version (XX). This number is incremented when we include major new functionality.

• The second set of numbers is the minor version (YY). We increment this number when we make a minor enhancement to an existing feature or make a bug fix.

• The last number is the build number. This starts at zero and is incremented each time we compile the product to an executable (EXE, APP, or DLL). This number is meaningless to the customer except for the final version, but allows us to manage internal builds with the development and test teams .

We recognize other developers use different schemes as well. One we have seen more frequently than others is YYYY.MM.DD (year, month, and day). This is an interesting concept for software historically remembered by the date of a release. The Visual FoxPro incrementing version number does not support this natively, but developers can use the projecthook BeforeBuild method to change this to the current date.

Upgrade installs

Creating the upgrade install is one topic that seems to confuse developers. This topic is specific to the Windows Installer technology and is covered in detail in Chapter 5, ‚“Windows Installer Inside and Out. ‚½ How Windows Installer sees your install package in terms of upgrading a product already installed depends on the settings you make to the Package Code, the Product Version, the Product Code, and the Upgrade Code inside your favorite Windows Installer tool.

First and foremost, we recommend always keeping a copy of the Windows Installer database files (MSI extension) for all the installations. It makes the process of creating the upgrade/update install simpler because you need to include information from the original install package in the update project. We outline the options and setting changes necessary to create an update install package in Table 2 .

Table 2. Changes from the previous install to create small updates, minor upgrades, and major upgrades

Type of Install	Package Code	Product Version	Product Code	Upgrade Code
Small update	change	don ‚ t change	don ‚ t change	don ‚ t change
Minor upgrade	change	change	don ‚ t change	don ‚ t change
Major upgrade	change	change	change	don ‚ t change

The first step in creating the update install package is to copy the original or previous project file used to create the install. This is not the Visual FoxPro project file; it is the installer project file created by InstallShield Express, Wise for Windows Installer, or other favorite tool. Why not use the original project file? Simple, you are going to make some irreversible changes. If you need to regenerate the original installation for any reason, you are not going to be able to do so unless you have the original project. It is similar to the reasons many developers use a source code control tool. Maintain the history so you are able to review the settings and potentially rebuild the install if a customer reports a problem in an older version. If a new customer buys an older version, you have the ability to create it and ship it to them. Starting with a copy of the previous project file saves you from recreating it from scratch, has the file list, features, images, readme files, etc. It retains the original Upgrade Code, Product Version, and Product Code, which are important in determining what type of update or upgrade you are distributing.

The Package Code is generated for each build, typically by the install tool and is not something you should be concerned with unless you are manually creating the MSI database. The Upgrade code should only be generated for the first installation and never changed in a subsequent update. Otherwise the upgrade package does not find the previously installed version. The only two settings you really need to change are the Product Version and Product Code. Both of these settings are under the General Information section of InstallShield Express and the Product Details of Wise for Windows Installer (see Figure 10, 11 and 12 ).

Figure 10. You use the original settings of the Product Version and the Product Code if your changes are a small update.

Figure 11. You change the Product Version and leave the Product Code if your changes are a minor upgrade.

Figure 12. You change both the Product Version and the Product Code if your changes are a major upgrade.

The upgrade feature (Upgrade Path in InstallShield Express and Upgrades page in Wise for Windows Installer) is very important when performing a major upgrade for your customers. Both of the tools add an entry in the Upgrade table of the MSI database. This feature enables a search on the target system for the old install (based on its Upgrade Code), silently uninstalls it, and then installs the new product. If you do not include the upgrade feature, your users are presented with a message telling them a previous version is already installed and to uninstall the old version before installing the upgrade. This is not a friendly approach to upgrading to the latest version of your product. Many developers faced this problem the first time they upgraded their product using the InstallShield Express Visual FoxPro Limited Edition included with Visual Fox Pro 7.0.

Note ‚  

The Upgrade Path feature, used to create update installs, is not available in InstallShield Express Visual FoxPro Limited Edition shipping with Visual FoxPro 7. You need to upgrade to the limited edition version shipping with Visual FoxPro 8 or later, or get the full product from InstallShield or another Windows Installer tool like Wise for Windows Installer to get this functionality.

Do not be confused with the Windows Installer terminology and how you internally might classify a release. You might make a minor enhancement for a client and update the version from 2.1 to 2.2. Just because you consider this a minor upgrade internally, you can still install this update via the Windows Installer ‚“major upgrade ‚½ to take advantage of the silent uninstall and reinstall provided using the Upgrade Path functionality. The same goes for a small bug fix. Just change the Product Version, the Product Code, and create a new Upgrade Path entry.

Each entry in the Upgrade Path represents an earlier product to uninstall (shown in Figure 13 ). You need to create an entry for each potential version you want this upgrade to replace. For instance, if your user has version 3.0 and 4.0 installed and you are creating a new 5.0 install replacing both of the previous installs, create one Upgrade Path entry for the 3.0 install and one for the 4.0 install. The 5.0 deployment package searches for both and silently uninstalls whichever version it finds before installing the new version.

Figure 13. Each Upgrade Path represents a previous version potentially installed on the target computer. This install package example can remove two previous versions before installing the major upgrade.

Forcing the small update or minor upgrade can happen without forcing your user to uninstall the prior version. It requires some additional work and has some side effects you need to be aware might have adverse impacts on the install. To accomplish this you want to pass REINSTALLMODE=voums and REINSTALL=ALL switches to SETUP.EXE. The REINSTALLMODE=voums switch forces the Windows Installer Service to ignore the cached MSI package on the system and use your new MSI package. This way all your features previously installed on the product re-install from the new package.

  MsiExec.exe /I MyProject.msi REINSTALLMODE=voums REINSTALL=ALL  

OR

  Setup.exe /V"REINSTALLMODE=voums REINSTALL=ALL"  

Asking your users to provide these parameters to run the install might be too much for them to handle, especially if they are used to auto-running CD-ROMs starting the installation process. If you prefer, you can include the same settings as part of the SETUP.INI file generated as part of the setup files by most install tools. You need to modify this file each time you regenerate the installation package. This is one more thing to remember, but easier than having your user mistyping a parameter when they manually run the install. Add the following line in the SETUP.INI file:

  CmdLine = REINSTALLMODE=voums REINSTALL=ALL  

Normally this process replaces existing files only. Although it is possible to deploy new files and features using a small update or a minor upgrade, this is not always easy to do because there are a number of rules governing how these changes must be configured within the Windows Installer database. Also, you cannot deploy an update using REINSTALLMODE=vomus and REINSTALL=ALL if the previous version has been uninstalled ; the update won ‚ t install any features because none are present to be reinstalled. For these reasons, you may find it easier to deploy all but the simplest updates in the form of a major upgrade.

Uninstalling

You might be asking why we would include an uninstall section in this chapter. After all, isn ‚ t it the goal to have our customers use our software as long as possible? Possibly even forever? Maybe and maybe not. We have worked on projects with a dictated requirement that the application be uninstalled on a specific date. Granted, we have also worked on projects with an expected lifecycle of six months and they lasted more than six years . Regardless, hardware has an expected lifecycle and our users might recycle the hardware to another organization like a non-profit group and want their intellectual property removed before passing along the machine to the next generation of user.

Make sure your installation has an exit strategy. It could be it was copied to the machine and just needs to be deleted. The modern installers we address throughout this book have uninstall technology built in. Understand how it works and how the selections you make allow the uninstall to take place, but might not remove the all the files. You might have to include instructions to the users that certain files are not deleted and they need to delete these files using Windows Explorer.

We use the Add/Remove ReadMe file (shown in Figure 14 ) for additional instructions for the user. The problem with this is end users typically do not look into the support information for the application when they are uninstalling an application. To assist with this we include a section in the Help file detailing the extra steps necessary to completely uninstall the application. We also handle support calls as well to walk them through the process.

Figure 14. The Add/Remove Programs support link allows you to include an uninstall readme file. Use this to relay important details to users who uninstall your application.

It is possible to create a shortcut for the Windows Installer uninstall process, but it is highly recommended to have the users uninstall products through the Add/Remove Programs dialog. Definitely discourage users from uninstalling your applications by deleting the folder(s) where your application files are installed.