AppSearch in Wise Package Studio

A common requirement of an installation program is to search for existing files or registry data on the target system. To search for a file or directory on the target system it is necessary to add a record to the Signature table of the MSI database, which describes the file or directory being sought. In addition it requires a record to be entered in the AppSearch table. The AppSearch table has a foreign key to the Signature table and a property whose value will be set to the full path to the file, if found. These tables along with the relevant locator database tables allow Windows Installer to search for a particular file or directory during an installation. They may be used for example to determine whether the user has already installed a particular version of an application or a file.

The AppSearch Action searches the user's system using unique file signatures (specified in the AppSearch table) based on name, version, date size and language recorded in the Signature table along with one of the following locator database tables (in the order listed) for a suggested file location.

• CompLocator table:searches based on a component GUID
• RegLocator table:searches for a registry value
• IniLocator table: searches for information contained within an INI file
• DrLocator table: searches by querying the directory tree

If the file signature is listed in the CompLocator table, the suggested search location is the key path of a component.

If the signature is not listed in this table or not installed at the suggested location, the installer next queries the RegLocator table for a suggested location. If the file signature is listed in the RegLocator table, the suggested search location is a key path written in the user's registry.

If the signature is not listed in this table or not installed at the suggested location, the installer queries the IniLocator table for a suggested location. If the file signature is listed in the IniLocator table, the suggested search location is a key path written in an .ini file present in the default Windows directory of the user's system.

If the signature is not listed in this table or not installed at the suggested location, the installer queries the DrLocator table for a suggested location. If the file signature is listed in the DrLocator table, the suggested search location is a path in the user's directory tree. The depth of subdirectory levels to search below this location is also specified in this table.

The first time the installer finds the file signature at a suggested location, it stops searching for this file or directory and sets the corresponding property in the AppSearch table to the location of the file or directory.

Uses of AppSearch

The information contained in the property in the AppSearch table (this is a public property) can be used to determine the outcome of the current installation.

It can be used as a condition. Certain components, features or an entire product may require that a file or application is currently installed on the user machine. If the AppSearch locates the required information the condition will resolve to true and the installation will continue. If however the AppSearch fails to locate the required file a warning dialog may appear request that the user installs the file(s). Alternatively the prerequisite files may be installed automatically.

By entering the AppSearch property into the Directory table it is possible for the packager to specify the desired installation location of components currently being installed. It may be requested that certain files be installed based on the location of other files already installed on the user machine.

During an installation, you might want to remove existing files from the destination machine, to save on disk space or to avoid possible file conflicts between a previous installation and a new installation. In addition it may be required that files and folders created at run-time are removed. If we know the exact location of these files we can hard code the remove file table to find and remove the unwanted file. More commonly an AppSearch is used to locate the file. The AppSearch sets a property to the value of the path to the file. The Remove File table then uses that property to remove the file.

Performing an AppSearch Using DrLocator

The installer can search for a particular file, registry entry or directory during an installation. These searches are important in determining whether the user has already installed a version of an application, setting a property from a registry entry or locating unwanted run time files that may be left on the machine after an uninstall so they can easily be deleted.

1. Create an Empty MSI project.
2. In the Installation Expert- Features Detail - Files - add at least one file to the installation to create a component.
3. Create a file to search for e.g. In Notepad create mysearch.txt and save it to C:\Program Files.
4. In the Setup Editor click on Tables tab, then go to Property table, right click and select New - Row. Create a property called APP_TEST and set value equal to 1.

   This property, when set to 1, allows the user to make use of the DRLocator table and RegLocator table with the AppSearch table to search for and retrieve files paths or registry key values.

   

   Click to view.

   There are three tables that you need to populate to search for a file; AppSearch, Signature, and DrLocator

5. Select AppSearch table. Right click and select New Row. Under the Property field set the name of the property you want the search to populate (i.e APP_TEST).
6. In the AppSearch table the Signature is a name that will link the AppSearch table to the Signature table as well as the DrLocator table. Highlight Signature_ field and enter a signature name (i.e MyFile).
   
   

   Click to view.

7. In the Signature table right-click to create a new row. Under the Signature field enter the name of the signature as previously chosen in step 5 (i.e MyFile). Remember this name links all the tables together.
8. Still in the Signature table the FileName is set to the name of the file that you are searching for (a unique file name). You must also include the file extension.
   
   NOTE: FileName is case sensitive.
   

   Click to view.

   • If you want to look for certain versions of the file you can fill out the MinVersion and MaxVersion fields.
   • If you want to look for certain sizes of the file you can fill out the MinSize and MaxSize fields.
   • If you want to look for certain dates of the file you can fill out the MinDate and MaxDate fields.
   • You can also look for certain languages of the file by populating the Language field
     
     

     Click to view.

9. In the DrLocator table, again right click to create a new row. Under the Signature field set the name to the signature name previously chosen in step 5 (i.e MyFile).
   • In the DrLocator table the ParentDirectory can be null or you can populate it with another entry located in the Dr Locator table and then the path that you choose would be added to the parent directory.
   • In the DrLocator table the Path can be filled with a hard coded path to search for that file in that specified location.
   • If you leave both the ParentDirectory and the Path fields blank it will search all fixed drives on the user's PC.
   • In the DrLocator table the search depth is how deep you want the search to go down the directory structure to find the required file. If you set the depth to 0 then it will only give the files that match in root. For example, if you set it to 0 it will find C:\mysearch.txt, but will not find C:\Program Files\My App\mysearch.txt which has a search depth of 2.
10. The property that you have created in the AppSearch table (i.e APP_TEST) will populate with the location of the file if it is found.
11.  
12. To check to make sure that your file has been found you can display this Property on a dialog. You can do this by creating text on a dialog and the text you will display is [PropertyName]
13. Go to the Dialogs tab and highlight a dialog box, which will be displayed during your practice install/test. Select actual dialog box and right-click on this Dialog box, select Add, select Text
14. In the Properties text panel, tab down to the Control Text window and enter the Property name (i.e [APP_TEST]). Be sure to include the square brackets [ ] so the MSI knows to display the value assigned to the property and not just the text string 'APP_TEST'.
    
    

    Click to view.

15. Now Compile and Run. Your chosen dialog box should display the full path to the file you've been searching for (i.e the file added in step 3.)
    
    

    Click to view.

    NOTE: If result displays "1" go to Explorer - View - Options - View Folder - Show hidden file extensions e.g. mysearch.txt.txt

Remove an existing file during an installation

During an installation, you might want to remove existing files from the destination machine. One reason for this is to save on disk space. Another reason is to avoid possible file conflicts between a previous installation and a new installation. This may cause errors during installation or may cause files that have previous versions on the destination machine, not to be installed.

One of the main features of Wise for Windows Installer is for all files and references to the product to be completely removed on uninstall. On uninstall Wise for Windows Installer follows the installation script to remove any files or registry entries that were installed. Because the application may produce run time files that aren't contained in the install script, they get left behind on uninstall, along with their folders.

If we know the exact location of these files we can hard code the remove file table to find and remove the unwanted file. The problem with this is the installation path of the application may be changed at a later date, which would render the remove file entry redundant. We can overcome this problem by first using an AppSearch to locate the file. The AppSearch sets a property to the value of the path to the file. The Remove File table then uses that property to remove the file.

How To Remove A File Using AppSearch

Below is an example of a 'remove file', using AppSearch to initially locate the file.

Firstly create a new text file, call it mysearch.txt and place it in any folder on the destination machine.

1. The first part of the procedure is to locate the file mysearch.txt. We first populate the AppSearch table. Make sure to place the property name in caps. The signature field is a user-defined entry.
2. The next table is the DrLocator table. The DrLocator table holds the information needed to find a file or directory by searching the directory tree. The Signature column is an external key to the first column of the Signature table. This field may represent a unique file signature listed in the Signature table. If the value in this column is absent from the Signature table, then the search is assumed to be for a directory pointed to by the DrLocator table. If the parent field is left blank the search checks all fixed drives for the file to a dept specified by the depth column (i.e. depth 0 = C:\, depth 1 = C:\Program Files).
3. In the DrLocator table create two entries - one which searches for MyFile (MyFile returns the Path+FileName and another entry which searches for MyFileFolder (MyFileFolder returns the Path only). Note that MyFile is the parent of MyFileFolder.
   
   

   Click to view.

4. Our next table is the Signature Table in the 'Remove File Process'. In this table we specify the file name to be deleted (followed by its extension). We can specify versions, sizes, date or language of the required file. For this example the Signature Table should contain - Signature = MyFile and FileName=mysearch.txt
   
   

   Click to view.

5. Amend AppSearch Table to search for parent e.g. MyFileFolder which will return path instead of path + file name.
6. Now the file should have been located (if present) with the AppSearch routine above. The next step is to remove the file.
7. In the RemoveFile table each column should be populated as follows:
8. FileKey is just primary key do not use signature here - create primary key eg. Key1. We must select a component that is always installed as part of the MSI. A Component that is part of the Feature Complete can be chosen because the Complete Feature is always installed. If the file name is left empty here the Remove File Action will remove the specified folder, if it is empty.
   
   

   Click to view.

   FileName contains the file you want to remove
   DirProperty should contain name of AppSearch e.g. APP_TEST

The Install Mode Column can contain the following flags.

1. Removes file when associated Component is installed.
2. Removes file when associated Component is uninstalled.
3. Removes on the two above scenarios.

We should now have a fairly good idea how to remove files that were resident on the destination computer. We use the same operation to remove runtime files.

Performing An AppSearch Using Reglocator

Using the example of the WinZip.msi application package perform the following steps to create an AppSearch using the RegLocator table.

1. Create a copy of the WinZip.msi file and call it WinZip2.msi
2. Under Product Details in the Installation Expert generate a new product code.
3. Double click on the System Search link under Target System in the left hand frame.
4. Click 'Add' and choose 'Registry'.
5. Call the 'Property' REGLOCATE (ensure that you use all capital letters as this is a public property).
6. Under 'Operation' choose 'Read directory name from Registry'.
7. Set 'Root' to HKEY_LOCAL_MACHINE
8. Set 'Key' to the registry key you are going to search for i.e. SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\winzip32.exe.
9. Set the 'Value Name' to a specific value contained under this key. In the above example Path is the value name.
10. Go to the Setup Editor and click on the Tables tab. Open the Property table.
11. Add a new property called REGLOCATE and set its value to NO.
12. Go to Setup Editor, Product tab and select Launch Conditions.
13. Add a new Launch Condition setting the Condition to REGLOCATE ~= "NO"

    Set the Description to "Please Uninstall the previous version of WinZip"

14. Next go to the InstallExecuteSequence table in the Setup Editor. Ensure that AppSearch has a lower value than LaunchCondition.
15. Next go to the InstallUISequence table in the Setup Editor. Ensure that AppSearch has a lower value than LaunchCondition.
16. Compile the WinZip2.msi and to test it first install WinZip.msi. Now try to install WinZip2.msi on top. What error message do you get? It should correspond to the Description that you set in your Launch Condition.
17. Uninstall WinZip.msi and try to install WinZip2.msi. What happens now? The installation continues without an error message because the registry value that we were searching for does not exist.