In this section we first describe the basic structure and format of a Web Update Wizard script file. Then we provide a number of example scripts, with detailed explanations of how they work.
Not every Web Update Wizard keyword is illustrated in the examples - see the keywords reference page for more information on all the keywords. However, the examples will get you started with the Web Update Wizard and to train you to at least intermediate level in its usage.
Before you read this page you may find it helpful to follow through an example update in detail. This link describes in detail how to integrate the Web Update Wizard with your software, what happens during a typical update, and some of the Web Update Wizard's additional debug log options.
Example 1: As easy as it gets!
Example 2: Notifying the User that an update is available
with a custom message
Example 3: Letting the user choose whether they want to accept the update
Example 4: Conditional updates based on file version
number
Example 5: Updating several files at once using a Zip file
Example 6: Using an Installer file as the update file - the
Web Update Wizard downloads the installer and then runs it
Example 7: Updating the Web Update Wizard itself
Example 8: Customising the Web Update Wizard 'Look and Feel'
A script file is a simple text file which is located on your web server. Every time an update check is initiated the Web Update Wizard will download the script file, work through it from top to bottom, and process any updates that are required based on the contents of the script file.
A script file contains one or more sections.
A section is a collection of continuous lines relating to the download of a single file as an update. That single file could be an updated .exe of your application, or it could be a zip file which contains one or several updated files to support your application.
An update script can contain any number of update sections.
Each section must begin with a unique counter line, which is an integer greater than the previous integer used in the file. The integer must be enclosed by square brackets, as shown in the example below.
The counter value is used by the Web Update Wizard to determine whether an update section has already been processed on a client machine. It stores the counter of the last section successfully processed in the WebUpdateSvc4.ini file.
However, the Web Update Wizard has additional options which will give you greater control over whether updates are processed. You can make updates contingent on the version number or date/time stamp of any nominated file on the client computer. See the keywords RunAlways, CheckFile, CheckFileExists, FileDate and FileVersion for more information.
Important: Each section must be separated from the next section by a single, blank line. Blank lines within script sections are not allowed. If you want to have line spaces within an individual script section you must use empty comment lines - i.e. lines starting with the semi-colon (;) character.
This is an example script.
[1]
; This is a comment line
Filename=/Prophecy/Prophwin.exe
KillProcess=Prophwin.exe
Message=<body scroll="no>There is an optional Prophecy upgrade available.<p>Would¶
you like to update your Prophecy version now?</body>
Importance=Optional
Backup=Yes
¶
[2]
Filename=/Prophecy/Prophwin.chm
WindowTitle=Prophecy Client Help
Backup=No
Importance=Optional
Comment lines start with a semi-colon character ( ';' ). Each keyword line must be on a single line - no carriage returns are supported. (The "Message=" line in the example above has wrapped round for display purposes only.)
Other than a requirement for the counter integer ( '[1]' etc.) to be the first line of any section, you can normally enter the other keyword lines in any order - the Web Update Wizard determines when the actions implied by each keyword line should be executed.
You do not have to delete sections after each user has downloaded the updated file version, although you can do so in order to keep the script file size down (bearing in mind it will be downloaded each time Web Update Wizard runs). Sections which have already been completed will be ignored at the client computer end.
The sections must be ordered oldest to newest down the file, as shown in the example above. That is, the sections must be numbered and sorted in ascending order from top to bottom of the file.
The keywords reference page documents every keyword and provides usage further examples of each keyword in action. Many of the keywords included in the example scripts below have links to the specific section of the keywords reference page so that you can read about them in more detail, if helpful.
Please note that the counter line for each of the examples below is [1]. As discussed above, the counter needs to be one higher than the last one used - we've just used [1] in our examples for consistency.
[1]
Filename=http://www.mycompany.com/updates/MyApp.exe
KillProcess=MyApp.exe
This script updates MyApp.exe. Assuming that the Web Update Wizard has been launched from MyApp.exe, the Web Update Wizard needs to close MyApp.exe prior to updating it as Windows will not allow the replacement of an in-use file. The KillProcess keyword elegantly terminates all running instances of MyApp.exe prior to the updated file being written to disc, and restarts MyApp.exe once the updated version has overwritten the previous MyApp.exe file.
Assuming MyApp.exe was running when the Web Update Wizard update call was made, the user will see the following interactions:
[1]
Filename=http://www.mycompany.com/updates/MyApp.exe
KillProcess=MyApp.exe
Message=<body scroll="no" style="font-family:
Arial, Helvetica, sans-serif; font-size: 80%; color: Green;">Hello <USERNAME>,<p>There
is an <i>absolutely fabulous</i> new version of MyApp available<p>It
will now be downloaded and installed for you.</body>
This script is the same as Example 1, but in addition a dialog message box will appear containing the html text in the Message= keyword line.
The Message= line can either contain a single line of html text or the url of a web page which will be downloaded into the Web Update Wizard message box. Web Update Wizard dialog boxes use the Microsoft Internet Exporer web control to render the html.
Note the use of the <USERNAME> constant, which expands to the name of the logged on user at run time.
Assuming MyApp.exe was running when the Web Update Wizard update call was made, the user will see the following interactions:
[1]
Filename=http://www.mycompany.com/updates/MyApp.exe
KillProcess=MyApp.exe
Message=<body scroll="no" style="font-family:
Arial, Helvetica, sans-serif; font-size: 80%; color: Green;">Hello <USERNAME>,<p>There
is an <i>absolutely fabulous</i> new version of MyApp available<p>Would
you like to download and install it now?.</body>
Importance=Optional
This script is similar to example 2, except that the dialog containing your Message now contains 'Yes' and 'No' buttons, allowing the user to decline the update if they wish. Note that the Message needs to be amended as the user needs to be prompted whether they want to accept the update.
The Importance keyword line determines the format of the prompter dialog. Without Importance=Optional the dialog just has an 'OK' button. With it, the dialog has "Yes" and "No" buttons.
If the update is declined then it will be offered again next time a 'check for updates' request is made.
[1]
RunAlways
Filename=http://www.mycompany.com/updates/myapp.exe
FileVersion=2.0.0.3
Message=<body scroll="no">MyApp Version 2.0.0.3 is now available and will be downloaded</body>
KillProcess=MyApp.exe
This script uses the FileVersion keyword to check whether the version number of MyApp.exe on the user's computer is older than the version available for update. In this case, if the user is running V2.0.0.2 or earlier of MyApp.exe then an update will occur. Otherwise no update will occur.
The RunAlways option saves having to change the script section number each time a new update becomes available. The script runs every time, but an update only occurs if the FileVersion test is positive.
FileVersion always uses the name of the file in the Filename line to perform a version check against. If you are using Zipfile or want to version check on a different file you can use the CheckFile keyword.
[1]
Zipfile=http://www.mycompany.com/updates/updates.zip
KillProcess=MyApp.exe
Message=<body scroll="no">Hello <USERNAME>,<p>There
is a new version of MyApp available. Would you
like to download and install it now?</body>
Importance=Optional
If your update requires the replacement of several files, you may find the Zipfile keyword preferable to Filename. With Zipfile you upload a zip file to your server which contains all of the updated files. The Web Update Wizard downloads the zip file, unzips it, replicating the folder structure from the zip into the target folder. The keyword help for TargetFolder= lets you specify a different target unzip root folder should you need to - otherwise it is the folder of your running application.
This example shows how to download and run an installation program created with InstallShield, InnoSetup or any of the other software installation creation programs.
[1]
Zipfile=http://www.mycompany.com/updates/installer.zip
TargetFolder=<TEMPDIR>
Message=<body scroll="no">Hello <USERNAME>,<p>We
will now install your update...</body>
ExecAfter=<TEMPDIR>\mysetup.exe<Wait=Yes>
ExecAfter=cmd /C del <TEMPDIR>\mysetup.exe
The installer program, mysetup.exe, is zipped and uploaded to the target web server as 'installer.zip'.
The TargetFolder keyword lets us specify that we want the zip file unzipped to the user's TEMP folder. (If you are running the Web Update Wizard as a service application, this will in fact be the Windows\Temp folder rather than the user's TEMP folder, as the service runs in the SYSTEM security context. However, this will have no effect on the syntax of the script or how it runs at the user end.)
<TEMPDIR> is one of the folder expansion constants documented here.
We provide a custom Message and then launch the installer using the first ExecAfter keyword, again using the <TEMPDIR> folder constant.
The <Wait=Yes> syntax is required in this instance because we would like to delete the mysetup.exe installer from TEMP in the second ExecAfter= line after it has finished installing the update.
(Note the use of the command processor expansion of 'cmd'. If you need to run different ExecAfters for different versions of Windows on the client there are additional control constants you can use in your ExecAfter line - see the detailed keyword help for more information.)
Updating the Web Update Wizard itself represents a challenge, as a file cannot overwrite itself. The Web Update Wizard uses the same approach as an installer program to address this issue - the Windows MoveFileEx() API followed by a reboot.
This example illustrates usage of the MoveFileEx and Reboot keywords. Generally speaking, KillProcess and WindowTitle should meet your requirement for replacing in-use files and should be used in preference to MoveFileEx because they avoid reboots. However, updating the Web Update Wizard is one instance where a reboot is unavoidable.
[1]
Filename=http://www.mycompany.com/updates/WebUpdateSvc4.exe
TargetFolder=<TEMPDIR>
Message=<body scroll="no">Hello <USERNAME>,<p>There
is an update to the Web Update Wizard service. A reboot will be required.</body>
MoveFileEx=From=<TEMPDIR>\WebUpdateSvc4.exe|To=<SYSDIR>\WebUpdateSvc4.exe
Reboot
The new version of the Web Update Wizard service is uploaded to the 'updates' folder of the web server and added to the section in the Filename keyword line.
MoveFileEx works by saving the downloaded file into a different location to the currently running instance. It then sets up a special registry entry (or WinInit.ini file if running under Windows 98ME) which Windows processes on the next reboot, replacing the current version of WebUpdateSvc4.exe with the downloaded version.
Therefore we download the new version into the TEMP folder. The MoveFileEx line contains From= and To= path arguments, separated by a '|' character. The From= is the folder specified in the TargetFolder line and the To= is the location of the running instance of WebUpdateSvc4.exe - i.e. the Windows System32 folder.
The <SYSDIR> folder constant expands at run time to the client computer's Windows System32 folder.
Having set up the MoveFileEx operation in the registry, the Reboot line warns the user of the impending reboot and then reboots the PC when the user clicks the 'Yes' button on the reboot warning dialog.
If the user does not click "Yes" to reboot immediately immediate then the WebUpdateSvc4.exe will be replaced at the next reboot.
You will need to adopt this approach when updating WebUpdateSvc4.exe, wuw4.dll and WuWUI.exe. The Reboot line should only be used after all the MoveFileEx operations have been completed, otherwise the user will end up with mis-matched Web Upddate Wizard components. (Alternatively you can download all the components in a single zip. A single script section can contain as many MoveFileEx lines as you require.)
You can use an ExecAfter in a subsequent script process if you wish to delete wuwinstaller.exe:
Example 6 was fairly advanced! So here is one more example script - bit easier this time! Here we show how the look and feel of the dialogs can be controlled from your script.
[1]
Filename=http://www.mycompany.com/updates/MyApp.exe
Message=<body scroll="no" bgcolor="#FFFFFF"
background="http://mycompany.com/images/blocks.gif"><p><font face="Verdana,
Arial, Helvetica, sans-serif" color="#0000CC"> This is a heavily customised page,
showing what you can do if you let your html run away with you!</font></p><p>
<img src="http://mycompany.com/images/powerprogrammertiny.gif" align="right"></p><p
align="left"> <font face="Arial, Helvetica, sans-serif" size="2"> <a
href="http://www.dataperceptions.co.uk">Click here for more!</a></font></p></body>
Importance=Optional
KillProcess=MyApp.exe
Bitmap=<PROGRAMFILES>\MyApp\mybitmap.BMP
Icon=<PROGRAMFILES>\MyApp\myicon.ico
DialogBk=204,204,255
TitleBk=255,255,255,0,0,255
TitleTxt=255,255,255
Title=MyApp Corporation<Verdana>
Subtitle=Update Wizard
The default 'look' is shown first. The customised 'look' is shown second:
You can decide which is nicer! But the differences at least highlight the items you can change.
You can also use advanced Message= options to make the web control field cover the bitmap to the left ("<nobitmap>"), the graduated title area ("<noheading>") and overap the buttons ("<overlapbuttons>"). If you use all 3 in combination then the web control field covers the entire dialog, as in ...
... you will get a Web Update Wizard dialog that looks like this:
Please see the Campaign Manager help topic.