Software Update Wizard - Keywords Reference

Description

The Software Update Wizard gives you several alternative methods for determining whether an update is required on a client computer.  The simplest method is to use the counter in the script, described here, and compare it with a counter which is maintained on the user's computer.  If the counter in the script is greater than the counter on the user's computer the update section will be processed.

The counter in the script has the format: [nn] (where 'nn' is an integer number).  Note that this counter is stored internally as a UINT, so the maximum counter value is 4294967295.

The last complete update counter variable is maintained by the Software Update Wizard in the WebUpdateSvc4.ini file - for example:

[www.dataper.demon.co.uk/prophecyupdate.txt]
Counter=6

Therefore, the last successful update in this example was update '[6]'.  The next update which will be actioned on the example PC is '[7]'.

Example:

[7]
;This is the next update section which will be processed
...

See also: RunAlways with FileVersion= , FileDate= , CheckFile= , CheckFileExists=  and FileMD5= for more sophisticated ways to check for updates.   However, this keyword is still required in every script section, although the actual value of the integer is not used to determine whether an update is required.  It is still required because the script parser uses the [nn] keyword line to mark the start of a script section.

Default 

This keyword is compulsory, and must appear as the first line in any section.

Description

This optional keyword is useful for testing your server update scripts, prior to deployment.

If you include this keyword line in a server script update file section, the update in that section will be processed by the Software Update Wizard, regardless of the value of [an integer] in your script or the value of the 'Counter=' value in the relevant section of the WebUpdateSvc4.ini file.  The FileDate / FileVersion tests (if present) will be processed in all cases and will determine whether an update is processed.  (If not present the update will be processed every time an update check is initiated.)

Therefore, if the section is processed because the Testmode keyword has been used, but the FileVersion or FileDate test fails (because the file version on the user's PC is the same or newer than the parameter part of the FileVersion / FileDate test) then the update will not be made.

Remember to remove this line before deploying the script, unless you want the section to be evaluated every time an update check is made.

Example:

N.b. This keyword performs an identical function to the RunAlways keyword.

Default

A comparison will be made between the latest "Counter=" value in the user's WebUpdateSvc4.ini files and the update will only be processed if the value in the ' [an integer] ' line in your script is greater than the value from the user's INI file.

Description

This optional keyword causes a script section to always be processed, irrespective of the value of the 'Counter=' value versus the corresponding value in the user's WebUpdateSvc4.ini file.

Therefore, an alternative to using  'Counter=' values to 'keep score' you may find it preferable to use a single script section in your script, which is evaluated each time and determines whether an update is needed using the CheckFile, CheckFileExists, FileDate, FileVersion and FileMD5 keywords.  (See here for a description of the Software Update Wizard™'s logic for determining if an update is required.)

Example:

[1]
Filename=http://www.myserver.com/MyApp.exe
RunAlways
FileVersion=2.0.0.0
Message=Hello <USERNAME>,<p>There is a newer version of MyApp.exe available.
etc..

N.b. This keyword performs an identical function to the Testmode keyword.

Default

The Software Update Wizard will determine whether the 'Counter=' value is higher than the last processed counter in the user's  WebUpdateSvc4.ini files and the update will only be processed if the value in the ' [an integer] ' line in your script is greater than the value from the user's INI file.

Description

Provides an alternative WebUpdateSvc4.ini file section label to the one the Software Update Wizard uses by default. It can be any (unique) text you like.  If you do not use this keyword then the url of the update script will be used as the section label in the WebUpdateSvc4.ini file.

Some Software Update Wizard users generate their server script files using PHP and this keyword will be of particular value to these users. If you are not dynamically generating your server script files you probably do not need to use this keyword.

Note that all keywords are unique (i.e. apply only to) the update section in which they are included. To use the same IniSectionID in subsequent update sections you must repeat the IniSectionID line.

For more information on the Software Update Wizard INI files, please click this link.

Example:

Default

The default WebUpdateSvc4.ini file section label is used, which is the url of the update script.

Description

The virtual path (from <wwwroot>) on the server to the file that is to be downloaded by the Software Update Wizard, or its full URL, including the "http://" part..

Example:

or..

As the file is downloaded the user will see a download progress dialog box. If you would like to suppress the display of this dialog box (i.e. the download occurs completely invisibly) you can append the optional text <noui> to the virtual path provided in the Filename= line, as in:

Filename=http://www.someotherserver.com/subfolder/webupdatefile.exe<noui>

Notes :

• Each update script section may include one, and only one Filename line.  If the update script section includes a Filename line it cannot include a Zipfile line.
• If you want to downloaded additional files within the same script section you should use one or more AdditionalFile lines.
• The leading forward slash is required in instances where you do not provide the full URL. If you omit it the file to be downloaded will not be found.
• If you do provide the full URL, then you must include the "http://" part, otherwise the URL will not be correctly recognised and the update will fail.
• Keywords are case-sensitive.  If you get the case of this keyword wrong then the section will not be processed.
• If you are running the Software Update Wizard as a service then the downloaded file will be created in the security context of SYSTEM/Administrator. This is the normal scenario, as the logged on user should not normally be able to delete/ change files in the types of folder locations which are normally updated by the Software Update Wizard, such as 'Program Files' or 'Windows'. However, if you need the downloaded file to be created in the logged on user's security context, so that they have rights to change / delete it then you should append the optional text <AsUser> to the Filename line:
  
  Filename=/webupdatefile.exe<AsUser>
  

Default

This keyword is compulsory, except where you are deploying a zip file (see Zipfile= below).  Remember that you must prefix the path using a leading '/' character, as shown in the examples above, to indicate the <wwwroot> folder or provide the full URL of the update file.

Description

Instead of supplying a file to download using the Filename= keyword, you can supply the path and name of a zip file on the server - e.g. /Prophecy/MyUpdates.zip (which points to the virtual web server folder <wwwroot>/Prophecy), or the full URL of the zip file, including the " http:// " part.. 

The Software Update Wizard will download the zip file and unzip it.  Any folder structure contained in the zip file will be reproduced as subfolders of the folder supplied in the TargetFolder= keyword line, or, if no TargetFolder= keyword is supplied, off the folder in which the application which calls the Software Update Wizard application is running.

Example:

Zipfile=/subfolder/webupdatefile.zip

or

Zipfile=/webupdatefile.zip

or

Zipfile=http://www.someotherserver.com/subfolder/webupdatefile.zip

The leading forward slash is required when you do not provide the full URL. If you omit it the file to be downloaded will not be found.

By default, the Software Update Wizard does not permanently save the downloaded zip file to disc. However, should you want to also save the downloaded file to the client computer, you can append the additional text "<SaveAs=xxxx>" to the "Zipfile=" line.  For example:

Zipfile=/wuw/NOTEPAD.zip<SaveAs=<CLIENTFOLDER>\notepad21.zip>

This line causes the Software Update Wizard to unzip the contents of the zip file AND to save the zip file to the folder equating to <CLIENTFOLDER> on the user's PC with the filename "notepad21.zip", overwriting any previous version of this file.  All of the folder constants supported by the " ExecBefore= " keyword are available within the context of  the "Zipfile=" "<SaveAs=..." functionality.

No unzip utility is needed on the user's machine to benefit from this functionality. The Software Update Wizard has the unzip capability built in as standard.

As the file is downloaded the user will see a download progress dialog box. If you would like to suppress the display of this dialog box (i.e. the download occurs completely invisibly) you can append the optional text <noui> to the virtual path provided in the Zipfile= line, as in:

Zipfile=http://www.someotherserver.com/subfolder/webupdatefile.zip<noui>

While the file is being unzipped the user will see an 'Unzipping...' progress dialog. If you would like to suppress display of this dialog you can append the optional text <noprogress> to the Zipfile line, as in:

Zipfile=http://www.someotherserver.com/subfolder/webupdatefile.zip<noprogress>

Note that the position of the <noprogress> option in the keyword line compared to the <noui> option is not significant and that the 2 options can be used individually or in combination.

Notes

• Each update script section may include one, and only one Filename line.  If the update script section includes a Zipfile line it cannot include a Filename line.
• If you want to downloaded additional files within the same script section you should use one or more AdditionalFile lines.
• Keywords are case-sensitive.  If you get the case of this keyword wrong then the section will not be processed.
• If you are running the Software Update Wizard as a service then the downloaded files will be unzipped / created in the security context of SYSTEM/Administrator. This is the normal scenario, as the logged on user should not normally be able to delete/ change files in the types of folder locations which are normally updated by the Software Update Wizard, such as 'Program Files' or 'Windows'. However, if you need the unzipped files to be created in the logged on user's security context, so that they have rights to change / delete them then you should append the optional text <AsUser> to the Filename line:
  
  Zipfile=/webupdatefile.zip<AsUser>

Default

Each section in the Web Update script must contain either a Filename= or a Zipfile= keyword line.

Description

Example

1. The full URL of the download file.  (If you would like the existing version of the file backed up before it is overwritten you can append the <Backup> switch to the url part of the keyword line, as in AdditionalFile=http://www.myserver.com/extradll.dll<Backup>| etc....).  (Please note that the relative URL syntax you can use to specify the filename of the download file in the Filename and Zipfile keywords is not supported for AdditionalFile and that the full URL, including the "http://" part must always be provided for each AdditionalFile line.)
2. The target folder for the download, using the same folder substitution options as for the TargetFolder keyword.
3. The version, MD5 or date criterion, described below.  If the file on the user's computer is older than the version or datestamp in the AdditionalFile line then the file will be updated.  For version and date criteria, if the value in the AdditionalFile line is the same or newer then the file will not be updated, irrespective of any other files which are updated within the entirety of the update section in which the AdditionalFile line resides. If the MD5 of the file on the user's computer is the same as that of the MD5 quoted in the AdditionalFile line then the file will not be updated, irrespective of any other files which ar updated within the entirety of the udpate section.  (If you would like the file to be updated without performing a Version, MD5 or Date check you must use the syntax <NA> for this item.)
4. The custom text you would like displayed in the advisory message box which appears, based on the text in the Message= keyword line.  (Note that the custom texts are concatenated for each AdditionalFile line and then substituted into the Message= text in replacement for the tag <AdditionalFiles>.  If <AdditionalFiles> is not found within the Message= text then the concatenated text from the AdditionalFiles lines will not be displayed.)
5. The (optional) MD5 check for the file referred to in the AdditionalFile line.

Default

Description

The standard workflow of the Software Update Wizard is to check for an update first and to download the update file second.  However, if you would prefer to download the update file first and notify the user second then you can use the Predownload keyword, which downloads the update files first and then notifies the user of the update.

The syntax is:

Predownload[<md5 of update file in Filename or Zipfile line>]

Note that if you are downloading the update file before notifying the user of the update then it probably makes sense to run the download silently, using the "<noui>" option for the Filename, Zipfile and AdditionalFile keywords.

Example 

Default

If this keyword is not used then the download happens after the user is advised of the update.

Description

An optional keyword that lets you change the default timeout value used by the WinInet libraries to download the update files from your webserver.

The default server timeout value is 30 seconds.  In the majority of cases this value should be adequate and is the default value set by Microsoft in WinINet.dll versions 7.x and 8.x.  However, if you have very large update files or an unreliable connection then you can use this keyword to increase the timeout interval.

Specify the number of seconds required as a timeout interval in this keyword line.

Example:

ServerTimeout=90

This line changes the server timeout used for downloading the update files to 90 seconds.

Description

The default download speed for update files is 'as fast as possible'.  However, particularly when your script downloads the update files before notifying the user, via the Predownload keyword, you may wish to throttle back the download speed to avoid slowing down the user's internet speed.  The Throttle keyword allows you to cause the download to pause for a specified number of seconds after a specified number of megabytes of the update file have been downloaded.

The syntax is:

Throttle=<number of seconds to wait>,<number of megabytes downloaded>

Note: This setting will persist if there are multiple update sections in your script.  If you want to change the Throttle setting in a second update section just use another Throttle line.

Example

Throttle=10,3

This will cause the download to pause for 10 seconds after every 3Mb of the update file has been downloaded.

Default

Description

An optional keyword which forces the Software Update Wizard to perform an MD5 integrity check with the downloaded file update referenced by Filename or Zipfile, before any further deployment of the downloaded update file.

If the downloaded update file MD5 signature is not the same as that specified in this keyword line the script posts an error box to the user and no further action is taken. On the assumption that the integrity of the downloaded file has been compromised the Software Update Wizard also deletes the downloaded update file.

Note that, as with all other keywords, the 'MD5' keyword is case-sensitive. That is, you must use "MD5" rather than "md5".

Example:

If the computed MD5 from webupdatefile.zip is the same as the MD5 specified in the keyword line the update will proceed as normal. If the MD5 is different the error message will be posted and the update will be aborted.

There are numerous free utilities available to compute the MD5 value for a file. If you do not have one already, we use the one available here: http://onlinemd5.com.

Default

The update will occur without any integrity checks on the downloaded file being made.

Description

An optional keyword, which lets you specify the background colour used for the Software Update Wizard dialog boxes, in terms of their Red, Green and Blue values.

Examples:

DialogBk=255,255,255

DialogBk=0,0,0

The first example sets the background colour to pure white, and the second sets it to pure black.  The maximum range for an individual red, green or blue value is 0 to 255.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default

Pure white

Description

An optional keyword, which lets you specify the text colour of the progress message in the Software Update Wizard 'downloading' dialog box, in terms of their Red, Green and Blue values.

Example:

DialogTxt=255,255,255

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all download dialogs in update script section.

Default

Navy.

Description

An optional keyword, which lets you specify the colours used in the graduated title bar on the Software Update Wizard dialog boxes, in terms of their Red, Green and Blue values.  You need to specify 6 values - the first 3 are the 'from' colour (i.e. the first colour) and the second 3 are the 'to' colour.

Example:

TitleBk=255,255,255,0,0,0

The example sets the first colour to pure white and the second to pure black.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default

All the screenshots in this help file use the default colour scheme, except where specifically indicated in the text.

Description

An optional keyword, which lets you specify the text colour of the large (left-hand) text displayed in the graduated title bar on the Software Update Wizard dialog boxes, in terms of their Red, Green and Blue values.

Example:

TitleTxt=255,0,0

This sets the text colour to pure red.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default

Black

Description

An optional keyword, which lets you specify the path on the user's PC or on the web of the bitmap which is displayed on the left hand side of the Software Update Wizard dialog boxes.

The default bitmap is 92x180 pixels / 96dpi.  Any bitmap you use should probably be no wider than 92 pixels, but could be a little taller - see any screenshot in this help file for how 92x180 pixels displays.  A larger bitmap will be painted at 100% scale from the top left hand corner of the default bitmap's screen position.

Examples

Specify a bitmap located on the client PC:

Specify a bitmap located on a web address:

Note that the Software Update Wizard determines whether the bitmap is located locally or on the web based on the first 7 characters of the text to the right of the '=' character.  If they are "http://" then it assumes the file is located on the web, otherwise it assumes the file is located locally on the user's PC.

Folder Expansion

You can use the any of the folder substitution variables when you specify your Bitmap path:

Therefore, the following keyword line in your server update script file...

Bitmap=<PROGRAMFILES>\MyApp\MyFlashyBitmap.bmp

...will expand at run time to...

Bitmap=c:\Program Files\MyApp\MyFlashyBitmap.bmp

... or whatever path the user's Program Files folder is registered to on the local machine.

If possible, we recommend using an icon file which is already present on the user's computer rather than downloading it from a URL, as this will speed up the update process for the user.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default

All the screenshots in this help file use the default colour scheme, except where stated.

Description

An optional keyword, which lets you specify the path on the user's PC or on the web of a Windows icon file (*.ico) to replace the default Wizard icon displayed on the left hand side of the graduated title bar on the Software Update Wizard dialogs.

We recommend that you use a standard size, 32 x 32 pixel icon, although the Software Update Wizard will scale your icon (up or down) to fit into the default 32 x 32 pixel size shown in the screenshots in this help file.

You can use the same path substitution variables for specifying your custom icon as for the Bitmap= keyword.

Examples:

Note that the Software Update Wizard determines whether the icon file is located locally or on the web based on the first 7 characters of the text to the right of the '=' character.  If they are "http:// " then it assumes the file is located on the web, otherwise it assumes the file is located locally on the user's PC.

If possible, we recommend using an icon file which is already present on the user's computer rather than downloading it from a URL, as this will speed up the update process for the user.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default

All the screenshots in this help file use the default colour scheme and icon.

Description

An optional keyword, which lets you specify the larger text item which is displayed on the left hand side of the graduated title bar of the Software Update Wizard dialog boxes.

Example

Title=My App Web Update

You can also, optionally, change the font / font size used, by appending "<Fontname,height>" to the title text, as shown in the following examples:

Set font to Tahoma, retain default font height (=20):

Title=My Update<Tahoma>

Set font to "Impact" and font height to 22 (logical units):

Title=My Update<Impact,22>

Note: there must be no spaces in the "<fontname,height>" part.  Also, remember that the user may not actually have the specified font installed on their machine.  In these instances the font mapper will default to a device-independent typeface.... which may not look too nice!  To research fonts installed with various versions of Windows, use the database at http://channels.microsoft.com/typography/fonts/.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

If you would like to use the current year as part of your title you can use the substitution variables "[YYYY]" and "[YY]" to display the current calendar year in your title text.  Therefore, if the current calendar year is 2014 and your title line is "Title=MyApp for [YYYY]" then the displayed title at runtime will be "MyApp for 2014".  The "[YY]" variant substitutes in the 2-digit year number instead.

When Actioned

Applies to all dialogs in update script section.

Default

"Software Update Wizard"

Description

If you would like to use the current year as part of your title you can use the substitution variables "[YYYY]" and "[YY]" to display the current calendar year in your title text.  Therefore, if the current calendar year is 2014 and your title line is "Title=MyApp for [YYYY]" then the displayed title at runtime will be "MyApp for 2014".  The "[YY]" variant substitutes in the 2-digit year number instead.

The default justification for the subtitle text is right-justified.  You can force the justification to left-justified (starting immediately beneath the start of the first letter of the title text) or center-justified by appending the text "[LEFT]" or "[CENTER]" to the text string passed via this keyword.

The text is rendered with a background shadow by default.  You can cause the shadow not to be drawn by appending the text "[NOSHADOW]" to the keyword text.

Example:

Subtitle=© MySoftwareCompany 2015

Subtitle=© MySoftwareCompany 2015[LEFT]

Subtitle=© MySoftwareCompany 2015[CENTER][NOSHADOW]

The first example causes the text "© MySoftwareCompany 2015" to be shown, right-justified, in the sub-title area.  The second example causes the same text to be shown, left-justified.  The third example causes the same text to be shown centre-justified and without the default shadow being rendered.

You can also change the font name and font height of the font used to display this item, using the same syntax as for Title=.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default

Blank (no subtitle is shown)

Description

Sets the text colour of the subtitle text which is displayed at the bottom of the graduated title bar of the Software Update Wizard dialog boxes.  The three required numbers are the red, green and blue components (with values of 0-255).

Example

SubTitleColor=255,255,0

When Actioned

Once the colour haas been set via this option all subsequent message boxes will use the colour, until it is changed by a subsequent update section in your script.

Default

The default colour is light grey.

Description

Example

ScrollingLink=Visit PowerProgrammer now!>>http://www.powerprogrammer.co.uk

ScrollingLink=

The first line sets the content of the scrolling link. The link will be displayed on all subsequent Software Update Wizard message boxes through to the end of the currently processing update script. The text up to >> is the text which is displayed in the scrolling link control on the message box. The text after the >> is the URL which will be launched when the user clicks the link.

Therefore the second line should be used in a subsequent script section if you want to reset (i.e. remove) the scrolling link, so that the message boxes in the subsequent section do not have the scrolling link. Alternatively, you can set a new scrolling link using the syntax of the first example.

Default

The scrolling link control will not be displayed.

See also: Customising the 'Look and Feel' of the Software Update Wizard Dialogs

Description

The default size of the Software Update Wizard message boxes used by, for example, the Message or FinalMessage keywords is 447 x 321 pixels.  However, if you would like to make the message boxes larger or smaller this keyword lets you scale the width and height proportionately, where a scale of 100 (percent) is the default size.

The change of scale applies to the entire processing of the current update script and every message box apart from the download progress dialog box is affected.

If you would like to be more selective in resizing your message boxes you can use the "<MessageBoxScale=x,y>" tag within the html of your message box text, as described in the keyword help for Message.  Using the "<MessageBoxScale=x,y>" tag within the html of your message box text overrides any MessageBoxScale keywords for the specific message box in which the html is displayed.

Example

In the first example the message boxes will be 50% wider and 20% taller than the default message box dimensions.  In the second example the width and height will be 80% of the default message box dimensions.

Description

This keyword displays a system tray icon when updates are taking place. In addition, a bubble is displayed for around 10 seconds when the tray icon first appears.  Thereafter a tooltip appears if the user's mouse hovers over the tray icon:

 

The screenshots shows the default messages.  You can customise the bubble and tooltip text using optional ShowSystemTray syntax:

ShowSystemTray=Show|<Tooltip text>|<Bubble text>|<Bubble title text>

The system tray icon will disappear automatically once the script has finished processing, or you can make it disappear in a subsequent script section with the following syntax:

ShowSystemTray=Hide

You can also have a new system tray text for each update section, as shown in the following syntax:

Note that the ShowSystemTray=Hide in section [2] in the example is required and must precede the new system tray message in the script section.

Default

Description

If the update file referred to in the Filename= or Zipfile= keyword lines resides in a password protected folder on your web server then the Software Update Wizard will pop up a standard authentication dialog to prompt the user for authentication details.  If your server supports challenge and response type authentication then the login name and password will be as secure as any network authentication can be.

However, if you would prefer to embed the authentication details into your Software Update Wizard script so that the user does not have to supply them, you can use the LoginAs= and Password= keywords.  This way the authentication process becomes completely transparent to the client user.

There are 2 usage options for the LoginAs= and Password= keywords:

1. 'Hard coded' - i.e. the login name and password are hard coded within your script (see Example 1 below).  The Software Update Wizard then uses these details when it launches the download request contained in the Filename= or Zipfile= keyword lines.  (The downside of this method is that anyone can discover the login name and password by typing the URL of your update script into their browser, assuming they know it.)
2. Retrieved from a registry key (see Example 2 below).  Here, the script file specifies the registry keys containing the login name and password.  The Software Update Wizard retrieves the contents of these keys and then launches the download request from the Filename= or Zipfile= keyword lines using the retrieved authentication details.
   
   Note that the registry key referred to is retrieved in the security context of the logged on user.

In addition, it is possible to encrypt either the 'Hard coded' login/password or the registry keys, so that casual readers of your script are unable to read the LoginAs and Password lines.  The Software Update Wizard Project Manager utility has an 'Encrypt..' button.  When you click it you will be able to encrypt the login and passwords for the update files folder on your web server:

You enter the LoginAs / Password into the edit fields.  The 'Encrypt' button then encrypts them.  The 'To Clipboard' button copies the correct syntax for the encrypted LoginAs/Password keyword lines to the Windows clipboard, ready for you to paste into your update script.  The pasted text, based on the dialog screenshot is:

LoginAs=>><[FF89][0063][0035][003A][FFD0][FFA0][002E][0043]
Password=>><[FFAD][0011][FFC9][FFF0][FFE0][FFD3][FFA4][FFE9][FFF9][FFC8][005C][002C][0009][FFDF][0024][004C][004D][FFD3][FFFE][FFBF][004D][000A][FFAB][FFE8][0067][FFEF][FFBC][001B][0058][FFC5][0078][004C]

When Actioned

As part of the download request for the URL specified in the Filename= or Zipfile= keyword line.

Default

If the server folder requires authentication from the user to access its contents the standard Windows authentication dialog will appear and collect the user's authentication details.

Example 1 - Hard Coded Use of LoginAs= and Password=

[4]
Filename=http://www.yourserver.com/update.exe
LoginAs=fred
Password=turkey703

Example 2 - Using Registry Keys in LoginAs= and Password=

[4]
Filename=http://www.yourserver.com/update.exe
LoginAs=HKEY_CURRENT_USER\Software\YourCompany\YourApp\\LoginAs
Password=HKEY_CURRENT_USER\Software\YourCompany\YourApp\\Password

This script section goes to the registry keys shown below and reads their contents:

It then uses them to download the update.exe file from the Filename= line.

The registry key names can be whatever you like.  If the text to the right of the '=' character starts with the characters "HKEY_' then it is assumed to refer to a registry key, otherwise it is assumed to be the hard coded value.

Description

Normally the Software Update Wizard maintains a log file, WebUpdateSvc4.log in the user's System32 folder, which retains a record of updates which have been made.

The 'LoggingOff' keyword switches off all logging.  'LoggingOn' switches it back on.

Bear in mind that if you switch logging off there will be no audit trail on the user's computer of the updates that have been made.

The logging setting persists within the context of the overall update script.  If, in the course of processing the first update in the script, logging is switched off, it will remain off until processing of a section that contains the 'LoggingOn' keyword.

Next time a script is processed, however, the logging setting reverts to the default, which is 'On', unless the first section processed again sets it to 'off' with a 'LoggingOff' keyword.

Default

Description

Please note that using the SuperLogging keyword starts verbose logging at the start of the section in which the keyword is found.  The verbose startup details which are available in global SuperLogging mode will not be captured if SuperLogging is set to off in the WebUpdateSvc4.ini file.  The following comparison shows the information differences:

Globally ON in WebUpdateSvc4.ini:

08/08/17 13:03:24 ** Waiting for WuWUI to start...**
08/08/17 13:03:24 WuWUI started!
08/08/17 13:03:24 WebUpdateSvc4.exe is running as a SERVICE under account SYSTEM.
08/08/17 13:03:24 The user's name is Peter Boulton
08/08/17 13:03:24 The folder of the calling process is 'G:\MSDEV\Projects\WebUpdateSCP\Release\'.
08/08/17 13:03:24 The platform is: MajorVer=6, MinorVer=2, BuildNo=9200, PlatformID=2, CSDVersion=
08/08/17 13:03:24 64 bit Windows = Yes
08/08/17 13:03:24 The proxyserver string is '' and the ProxyBypass string is ''.
08/08/17 13:03:24 Running WebUpdateSvc4.exe from location 'C:\Windows\SysWOW64\WebUpdateSvc4.exe'
08/08/17 13:03:24 WuWServiceVer=4.8.1.0
08/08/17 13:03:24 Remote desktop (WTS) session ID = 1
08/08/17 13:03:24 Initiating licence file checks..
08/08/17 13:03:24 Trying to open licence file in location '<application folder>'...
08/08/17 13:03:24 Finished licence file checks - result = Pass
08/08/17 13:03:24 A language file is already loaded into WebUpdateSvc4.exe from a previous run - no need to reload!
08/08/17 13:03:25 Language file '<path>\deflang.tab' loaded into WuWUI
08/08/17 13:03:25 !!!! Software Update Wizard called in standard mode. !!!!
08/08/17 13:03:25 Initiating update script download on url http://www.powerprogrammer.co.uk/SuwScript.txt
08/08/17 13:03:25 Download starting:-Download=http://www.powerprogrammer.co.uk/SuwScript.txt<tempname><noui>
08/08/17 13:03:25 Download finished. WuWUI returned "Loc=C:\ProgramData\WuW2F5E.tmp".
08/08/17 13:03:25 .. finished loading update script
08/08/17 13:03:25 Starting DoUpgrade fn..
08/08/17 13:03:25 Starting to parse update file ..

Globally OFF in WebUpdateSvc4.ini:

08/08/17 14:21:33 Language file <path>\deflang.tab loaded into WebUpdateSvc4.exe.
08/08/17 14:21:33 Setting SuperLogging to YES for current update section only. (Its previous setting was 'N'.)
08/08/17 14:21:33 Parsing section [1]...
08/08/17 14:21:35 Folder substitution: "<USER:TEMPDIR>" expanded to "C:\Users\PETERB~1\AppData\Local\Temp"
08/08/17 14:21:35 MessageBoxBoilerPlate returns OK
08/08/17 14:21:35 Finished parsing section
08/08/17 14:21:35 Removing block being processed from todo memory stack..
08/08/17 14:21:35 Finished memory stack cleanup
08/08/17 14:21:35 Checking whether an update is needed..

Example

Default

Description

Example

Default

Description

The update section will only be processed if the platform (i.e. operating system) version is greater or equal to the specified platform version in this keyword line.

The platform specification is based on the values returned by the Windows API GetVersionEx() function. (See also : http://msdn2.microsoft.com/en-us/library/ms724834.aspx.)

Click here for a summary of the platform values for each Windows platform.

Example

This means the updates section will only be processed for Windows Vista or later. (Note: You must use commas to delineate the fields and there must be no spaces.)

Default

The section will run on all platforms, unless PlatformMax is specified.

Description

The update section will only be processed if the platform (i.e. operating system) version is less than or equal to the specified platform version in this keyword line.

The platform specification is based on the values returned by the Windows API GetVersionEx() function. (See also : http://msdn2.microsoft.com/en-us/library/ms724834.aspx.)

Click here for a summary of the platform values for each Windows platform.

Example

This means the updates section will only be processed for Windows Vista or earlier. (Note: You must use commas to delineate the fields and there must be no spaces.)

Default

The section will run on all platforms, unless PlatformMin is specified.

Description

If the file specified by either the Filename= or Zipfile= keyword line in a script section already exists on the user's PC and has a date and time stamp which is older than the one specified in this keyword line or the file does not already exist on the user's PC then the update will be processed.

If you would prefer the update to be made only if the file specified by either the Filename= or Zipfile= keyword line already exists on the target computer and is older than the date specified in the FileDate line then you should add a CheckFileExists line to your update section:

In the script above, the update will only be processed if it passes both the FileDate and CheckFileExists conditions.

Note that the counter variable determines whether this comparison is made - i.e. if the counter variable in the script is greater than the counter variable in the user's WebUpdateSvc4.ini file then the "FileDate=" comparison will be made, otherwise it will not be made.

(Tip: You can force the FileDate= check to be made every time, irrespective of the counter variable, using the RunAlways keyword.)

(Please see here for a summary of the Software Update Wizard™'s logic for determining if an update is required.)

Syntax

You must specify the date/time stamp using the "yyyy/mm/dd/hh/mm/ss" format, as shown in the example:

This keyword is optional.

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default

If this keyword is not used then the update file is downloaded irrespective of whether it is newer or older than the file on the user's machine.

See Also:

FileVersion, FileMD5

Description

If the file specified by the Filename= keyword line in a script section already exists on the user's PC and has a file version number which is the same or newer than the one specified in this keyword line then the update will not be processed. If the version on the user's PC is older than the version in the FileVersion= line or it does not already exist then the update will be processed.

If you would prefer the update to be processed only if the target folder already contains the file in question but the version in the target folder is older than the specification in the FileVersion line then you should add a CheckFileExists line to your update section, as shown in Example 2 below.

Note that the counter variable determines whether this comparison is made - i.e. if the counter variable in the script is greater than the counter variable in the user's WebUpdateSvc4.ini file then the comparison will be made, otherwise it will not be made.

(Tip: You can force the FileVersion= check to be made every time, irrespective of the counter variable, using the RunAlways keyword.)

Note that the Software Update Wizard compares the version numbers from left to right as separate integers.  Therefore version 2.0.0.0 is deemed newer than version 1.999.999.999.

If the same update script section contains both a 'FileVersion=' and a ' FileDate=' keyword lines then the update is processed only if both tests are passed - i.e. on an AND basis.

(Please see here for a summary of the Software Update Wizard™'s logic for determining if an update is required.)

Example 1:

FileVersion=1.0.0.6

Example 2:

[1]
RunAlways
Filename=http://www.myserver.com/myapp.exe
FileVersion=1.0.0.6
CheckFileExists=<CLIENTFOLDER>/myapp.exe

In the above script, and update will only occur if myapp.exe already exists on the user's computer (the CheckFileExists line) and if the version on the user's computer is older than version 1.0.0.6.  Without the CheckFileExists line the update would occur if the file was older than 1.0.0.6 or it did not exist on the target computer.

Example 3:

In the above script an update will occur if the version of myapp.exe running on the user's computer is earlier than version 1.1.0.0.  In other words, only the first two parts of the running application's version number will be compared with the FileVersion= text.

Similarly, FileVersion=1.1.8 would update for versions prior to 1.1.8.anything.

Note :

This keyword is optional.

The following is an extract of a resource script for an executable.  The Software Update Wizard uses the highlighted item to obtain the version number:

1 VERSIONINFO
FILEVERSION 5,1,2600,0
PRODUCTVERSION 5,1,2600,0
FILEOS 0x40004
FILETYPE 0x1
{
BLOCK "StringFileInfo"
{
    BLOCK "040904B0"
    {
       VALUE "CompanyName", "Microsoft Corporation"
       VALUE "FileDescription", "Notepad"
       VALUE "FileVersion", "5.1.2600.0 (xpclient.010817-1148)"
       VALUE "InternalName", "Notepad"
        VALUE "LegalCopyright", "© Microsoft Corporation. All rightsreserved."
       VALUE "OriginalFilename", "NOTEPAD.EXE"
        VALUE "ProductName", "Microsoft® Windows® OperatingSystem"
       VALUE "ProductVersion", "5.1.2600.0"
    }
}

Or, right clicking on the file in Windows Explorer, you will see:

When Actioned

Prior to downloading the file specified in the Filename keyword lines.

Default

If this keyword is not used then the update file is downloaded irrespective of whether it is newer or older than the file on the user's machine.

Description

This keyword is one of the 3 ways of determining whether an update is required based on the update file specified in the Filename line of the update script.  The 3 ways are:

1. The file version number (see FileVersion).  This is the best approach for updating executables and dlls, which have standard embedded file versions.  An update occurs when the file version referred to in the script is newer than the version on the user's computer.
2. The date stamp of the file (see FileDate).  Use this option to update files that may change on the user's computer that you would like to update.  The update occurs when the last modified date of the file on the user's computer is older than the date specified in the FileDate line.
3. The MD5 of the file.  An update occurs where the MD5 of the file on the user's computer is different to the MD5 quoted in the FileMD5 line of the script.

(Please see here for a summary of the Software Update Wizard™'s logic for determining if an update is required.)

Example:

The script section will be processed if the MD5 of the file in the Filename line of the update script has a different MD5 to the MD5 quoted on the FileMD5 line.

Notes:

• You can use all 3 tests, (FileVersion, FileDate and FileMD5) in the same script section.  The update will only occur if all 3 conditions are met - i.e. on and AND, AND, AND basis.

When Actioned

Prior to downloading the file specified in the Filename keyword lines.

Default

If this keyword is not used then the update file is downloaded irrespective of its MD5 value.  

Description

This keyword lets you determine whether a script section will be processed based on the version number, MD5 and / or date/time stamp of any file on the user's PC, rather than the file specified in the Filename or Zipfile lines, as in FileVersion, FileDate and FileMD5 described above.

If the file on the user's computer is older than the version or date specified in the CheckFile line, or the MD5 of the file is different to the one specified in the CheckFile line, or the file does not already exist on the user's computer, the CheckFile test will determine that an update is required.

You can use as many CheckFile lines within an update section as you like.  The update will be actioned only if all of the CheckFile tests determine that an update is required.

The default behaviour is that CheckFile determines an update is required if the file exists and is older than the version or date specified in the CheckFile line or has a different MD5, or if the file does not already exist on the target computer.  If you would prefer the update to be made only if the file already exists on the target computer and is older/different MD5 then you should use the CheckFileExists keyword line, as well as the CheckFile line, as shown in Example 5 below.

The folder constants available in the TargetFolder= keyword are also available for use in this keyword.

Note that the counter variable determines whether this comparison is made - i.e. if the counter variable in the script is greater than the counter variable in the user's WebUpdateSvc4.ini file then the comparison will be made, otherwise it will not be made.

(Tip: You can force the FileDate= check to be made every time, irrespective of the counter variable, using the RunAlways keyword.)

(Please see here for a summary of the Software Update Wizard™'s logic for determining if an update is required.)

Example 1:

The script section will be processed if the file anyfile.txt does not exist on the user's PC or if it does exist but the date/time stamp (Date Modified) of the file on the PC is older than the date specified in the " ...<Date=yyyy/mm/dd/hh/mm/ss> " part of the CheckFile line.

Example 2:

The script section will be processed if the specified file does not exist on the users PC, if a version number cannot be successfully extracted from the file, or if the version number of the file on the user's PC is older than the version specified in the CheckFile line.

The Software Update Wizard compares the version numbers from left to right as separate integers.  Therefore version 2.0.0.0 is deemed newer than version 1.999.999.999.999.

Example 3:

• If the file does not exist then the script section will be processed.
• If the Modified Date of the file on the user's PC is newer than the date specified in the script, the script section will not be processed, irrespective of the version number test.
• If the Modified Date of the file on the user's PC is older than the date specified in the script, AND the version number is older, then the script section will be processed.

Example 4: 

CheckFile=<CLIENTFOLDER>\anyfile.dll<Version=2.0.0.0>¶
<Date=2004/12/01/23/00/00><MD5=92dc76c855035c16f1a40a7ce57ad9f6>

• If the file does not exist then the script section will be processed.
• The update will only be processed if:
  
  • The version of anyfile.dll on the user's computer is older than V2.0.0.0
  •  AND the last modified date of anyfile.dll on the user's computer is older than 23.00 on 1st December 2004
  • AND the MD5 of the version of anyfile.dll is different to the MD% quoted in the CheckFile line.

Example 5:

The script section will be processed if the file anyfile.dll exists in the specified folder on the user's computer and if the version of anyfile.dll on the user's computer is older than that specified in the CheckFile line.  If anyfile.dll does not already exist in the specified folder then the update section will not be processed.

Example 6:

This script section will cause an update to be processed if the version of anyfile.dll is earlier than 2.0.0.0.  The <Version=2.0> in the script means only the first 2 components of the standard 4 component version string (i.e. nn.nn.nn.nn) are evaluated versus the version of the file on the user's PC.

Notes:

• You may use multiple instances of CheckFile= within a single script section.  The section will be processed only if all the tests are passed.
• This keyword is optional
• Click this link for more information on how the Software Update Wizard reads the file version number.
• You may use the SubmitVariable keyword to substitute paths in the CheckFile line from text strings in the registry - see SubmitVariable.

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default

This keyword is optional.

Description

This keyword lets you determine whether the script update script should be processed, based on whether one or more specified files already exist on the user's PC. The update section will only be processed if all the specified files already exist. In addition, the optional "<NOT> " syntax causes the reverse to occur - an update is only processed if the specified file is NOT present on the target computer.

This condition is evaluated on an AND, AND, AND basis with CheckFile, FileVersion, FileDate and FileMD5 keywords - i.e. all the tests need to pass in order for the update relating to the current script section to be processed. If any single test fails the section will not be processed.

(Please see here for a summary of the Software Update Wizard™'s logic for determining if an update is required.)

Example 1:

The section will only be processed if mydll.dll exists in the same folder as the <CLIENTFOLDER> Software Update Wizard constant expands to. (See ExecBefore= for a list of Software Update Wizard constants.)

Example 2:

CheckFileExists=<CLIENTFOLDER>\mydll.dll
CheckFileExists=c:\A folder\licence.txt

The section will only be processed if both files exist on the user's computer.

Example 3:

CheckFileExists=<NOT><CLIENTFOLDER>\mydll.dll
CheckFileExists=c:\A folder\licence.txt

The section will only be processed if mydll.dll is NOT present on the target computer and is licence.txt is present.

Note: You may use the SubmitVariable keyword to substitute paths in the CheckFile line from text strings in the registry - see SubmitVariable.

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default

This keyword is optional.

Description

Example

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default

This keyword is optional.

Description

A message which will appear on the client PC, prior to the download being actioned.

The message text in this keyword must be a single line of html or a URL, where the "http://" part is required. The html or URL will be rendered by the Internet Explorer web control.

You can use the constant "<USERNAME>" in your message to provide some degree of personalization to the message - the name of the logged on user will be substituted for "<USERNAME>" when the message box appears. 

You can suppress the web control scroll bar using the "scroll=no" attribute syntax for the <body> tag, as in:

Therefore the following line generates the message box seen immediately below:

Message=<body scroll="no">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>

Note that there is a special case scenario where you may wish to advise your users if there is actually no new update applicable to them.  This situation is described in the FAQ - click here for more information.

The Message= keyword is optional.

The 'Yes' and 'No' buttons will appear if there is an Importance=Optional keyword line within the section being processed.  If there is no " Importance=Optional " keyword line then the dialog box will just have an 'OK' button.

If you use the <AllowPostpone> option in the Importance= line as described below there will be 3 buttons on the message box:

The 'Options..' button allows your user to decline the update this time but to specify a date on or after which they will again be prompted for the update (assuming it is still in the update script at that time):

If the user selects 'No' on the message box the update will not be processed this time.  However, assuming the section is still in the script next time an update check is made, they will again be offered the update, unless you also use the Permanent option in your Importance= line.

Note that the following (case-sensitive) 'tags' may be used in the html used to drive the web control on the dialogs:

You may use these tags in combination. You can put them anywhere in your html - the Software Update Wizard will identify and remove them from the rendered html.

See also:

• Additional help on customising the look and feel of the Software Update Wizard
• Keyword help for MessageBoxBoilerPlate
• Using multiple languages in the Software Update Wizard

When Actioned

After the update script file has been downloaded from the server and checked against the counter variable, but before any update files are downloaded.

Default

If no message is provided then the update will happen automatically, ( irrespective of the information in the Importance= keyword).

Description

Provides a template that all message boxes displayed by the Software Update Wizard will use (i.e. via Message, FinalMessage or any of the informational messages posted through the update process).

The template uses any standard html.  Insert the text '[!Content!]' into the place in the template text where the individual message should go.

Example:

<body scroll="no" style="border:0px;">[!Content!]</body>

When Actioned

This keyword is actioned when the update script is first parsed and will persist through further update script sections within the same script file until it is changed by a subsequent script section.

Default

If this optional keyword is not used then the default message box style will be used.

Description

Lets you control whether the update is compulsory for all users or optional.  If it is optional the user will be given the opportunity to accept or reject the update, based on the text you supply on a Message= keyword line within the script section being processed.

Example: 

Importance=Optional

• A Message= without anImportance= makes the update compulsory.  The  Message= notification dialog will just contain an 'OK' button.
• A Message= with anImportance=Optional makes the update optional.  If the user declines the update this time they will still be prompted next time.    The  Message= notification dialog will contain 'Yes' and 'No' buttons to allow the user to accept or refuse the update.
• A Message= with anImportance=Optional<AllowPostpone> makes the update optional and allows the user to choose a future date to next be prompted to update (providing the script section is still in the update script at that time.  The  Message= notification dialog will contain 'Yes', 'No' and 'Options..' buttons, letting the user accept the update, refuse it this time, or refuse it but specify a date in the future when they would next like to be prompted for this update (assuming the update section is still in your update script).
• No Message= keyword line, irrespective of whether there is an Importance= line in the update section makes the update compulsory.

There is an additional syntax option, which lets you skip not only the current script section, but also one or more script sections which follow the current section, when the user declines the update proposed in the 'Message=' keyword line.

For example:

[3]
Filename=/wuw/MyProg.exe
Message=Would you like to update to version 2 of MyProg?
Importance=Optional <Else[5]>

[4]
; There is no need to process this update section
; unless section [3] is also processed
Filename=/wuw/DependentDLL.dll

[5]
Filename=/wuw/SomeOtherUpdate.exe
Message=Would you like an optional update of SomeOtherUpdate.exe?
Importance=Optional
... etc.

If the user clicks the 'No' button in response to the message displayed through processing section [3] then the<Else[5]> part of the keyword line will cause the script to completely skip section [4] and start processing section [5].

In the above example, section [5] is optional too.  Therefore:

• If the user declines the update in section [5], then the next time the script is processed it will start processing at section [3] again.  This is because the counter in WebUpdateSvc4.ini (which records the highest section to have been successfully completed) will not have been updated (because none of the script sections actually completed).
• If the user accepts the update in section [5] then the counter in WebUpdateSvc4.ini will be updated to reflect section [5] having been processed and sections [3] to [5] will never again be processed for that user.

Therefore, in the above example, declining update [3] will cause it to be re-offered to the user next time, unless section [5] is accepted and successfully updated.

As a further permutation, you can make the effect of having declined an update permanent, so that the user is never prompted again for that update irrespective of any following interaction with the Software Update Wizard.

For example:

[3]
Filename=/wuw/MyProg.exe
Message=Would you like to update to version 2 of MyProg?
Importance=Optional <Else[5]Permanent>

[4]
; There is no need to process this update section
; unless section [3] is also processed
Filename=/wuw/DependentDLL.dll

[5]
Filename=/wuw/SomeOtherUpdate.exe
... etc.

In this example, section [3] is still optional, but if the user answers 'no' when the dialog box offering the update appears then the Software Update Wizard counter will be permanently updated with the result that this section will never be processed again.  The first possible section to be processed in this or any future Software Update Wizard run will be (in the example shown above) section [5].

Default

The default for updates is compulsory.  To make an update optional you must include the line 'Importance=Optional' and provide a Message= line.

Description

If  Yes then the target file is renamed with a *.bak file extension, otherwise it is overwritten by the update.

Example:

This keyword is optional and applies only to files updated as a result of a Filename= keyword within the script section.

When Actioned

After the updated version of the target file has been downloaded but before the existing file is overwritten.

Default

No backup will be made.

Description

Lets you specify the target folder into which the updated file will be downloaded.

You can use any of the Software Update Wizard folder expansion constants in this keyword.

If the target folder does not exist, the Software Update Wizard will create it.

Examples:

TargetFolder=<WINDIR>

TargetFolder=<CLIENTFOLDER>\MyAppFolder

TargetFolder=c:\Program Files\SuperApp

Default

If no TargetFolder line is provided, the updated file will be downloaded into the same folder as the application hosting the Software Update Wizard dll or the wuwstub.exe program.

A Note about UNCs

A TargetFolder can be a UNC (Universal Naming Convention) path.  

The UNC must be in the format:

TargetFolder=\\Servername\folder1\folder2

or

TargetFolder=\\Servername\folder1\folder2\

Description

Windows does not permit the replacement of in-use files.  Therefore if your application needs to update itself it needs to be closed by the Software Update Wizard. 

This keyword will send a Windows WM_CLOSE message to each application containing the text you specify in its application title bar (see examples below).  If the application does not close (i.e. respond to the WM_CLOSE by terminating) within the default time of 5 seconds then it will be forcibly terminated by the Software Update Wizard.  You can override the timeout interval by appending <Timeout=xxx> to the keyword line, wherexxx is the number of milliseconds  between issuing the WM_CLOSE message and the application being forcibly terminated by the Software Update Wizard.

Note that forcible termination means that the user will lose any changed data in the application that is being terminated.   A well-behaved application should respond to the WM_CLOSE message and allow the user to save their data before closing.  This means that your timeout interval must be long enough to allow all changes to be saved before the application is forcibly terminated.

(Tip:  If your application saves any unsaved changes before issuing a call to the Software Update Wizard it will be able to close in response to the Software Update Wizard's WM_CLOSE message without further user intervention.)

If you append the text <NOWARN> to this keyword line then running instances will be closed without the user being prompted.  Otherwise the user will be advised that the Software Update Wizard would like to close the specified application.

In instances where the user is likely to need to save data before the application closes it therefore makes sense to allow the warning message to be posted.  The target application will not be forcibly closed while the warning message box is displayed.  The WM_CLOSE message will be issued as soon as the warning message box is dismissed  If the application is still open after the WM_CLOSE timeout it will be legitimately forcibly closed by the Software Update Wizard.

To summarise, the sequence is:

1. Unless you have used the<NoWarn> option in the WindowTitle keyword line, the Software Update Wizard will post a message box warning the user that it will be closing down the targeted application.  The Software Update Wizard will wait until the user has dismissed this message box before continuing.
2. The Software Update Wizard sends a WM_CLOSE message to your application.
3. If, for whatever reason, your application does not respond to the message within the specified timeout interval the Software Update Wizard will forcibly close it (using the TerminateProcess() Windows API).

Examples:

WindowTitle=Notepad

WindowTitle=Notepad<NOWARN>

WindowTitle=Notepad<Timeout=15000>

The first example posts a warning message that Notepad will be closed down, and then closes it down.  If there is unsaved data in Notepad then it waits the default 5 seconds before terminating without saving.

The second example closes Notepad without any warnings.  If there is unsaved data then the user will have 5 seconds to save it before it is forcibly closed.

The third example does the same as the second, except that the user has 15000 milliseconds (i.e. 15 seconds) to save any unsaved work before Notepad is forcibly terminated.

Be aware that if you are using Software Update Wizard to update a dll file, for example, you will need to ensure that all applications which are using that dll are closed, using multiple occurrences of the WindowTitle= keyword line.

Restarting Applications that have Been Closed

If you have used the Filename= keyword in your script then the Software Update Wizard will attempt to relaunch the applications closed by this keyword after the download and all the ExecAfter= keywords have been executed.  

It will not do this for a Zipfile= type update. In this instance you must use a specific ExecAfter= command to relaunch your application. For example:

This is what happens when the above update file is processed:

• You get told a new version is available.
• You get told the existing version of SuperProgram needs to be closed, and it is.
• The zip file is downloaded and unzipped
• SuperProgram is relaunched from the folder which launched the original update process in the logged on user's security context (see ExecAfter=).

Default

This keyword is optional.

If not included in a section, no applications will be closed by Software Update Wizard.  If the file that is being updated is in use by Windows then Software Update Wizard will report a file in use error to the user.  (You should not let this happen!)  See also MoveFileEx= and Reboot keywords for how to replace in-use files.

See Also

The KillProcess keyword offers a similar mechanism for closing running applications.   For technical reasons PowerProgrammer recommends using KillProcess in preference to WindowTitle.  (KillProcess was added in Version 3.0 of the Software Update Wizard, but WindowTitle was retained for backward compatibility.)

Description

Windows does not permit the replacement of in-use files.  Therefore if your application needs to update itself it needs to be closed by the Software Update Wizard.  Once the application file has been updated by the Software Update Wizard it then needs to be restarted.  This keyword handles the whole process - closing the specified applications before the update and restarting them after the update.  In addition, it is possible to have KillProcess close the specified applications but to not automatically restart them using an optional flag described below.

This keyword is a more recent alternative method to WindowTitle= for closing a running application.  It allows you to specify the filename of the in-use application rather than the text contained in its title bar.

When you use this keyword, all running instances of the specified filename will be terminated.  The Software Update Wizard initially sends a WM_CLOSE message to the window of the target application  (if it finds one).   This should cause the target application to ask the user to save any outstanding changes.  A default of 5 seconds later the application will be terminated.  (Alternatively, your application could auto-save / prompt the user to save changes before the call to the Software Update Wizard is made.)

If the application does not respond to the WM_CLOSE method within the timeout period the Software Update Wizard will forcibly close it using the Windows TerminateProcess() API.

You can provide a longer timeout by appending a timeout in milliseconds to the KillProcess line:

The example above waits for 10 seconds before terminating MyApp.exe.

By default, the Software Update Wizard will post a message box warning the user that the application will be closed for updating and the application will not be closed until the user has dismissed the message box.  You can suppress the display of this message box by appending <nowarn> to the KillProcess line, as in:

The default behaviour of KillProcess is to automatically restart the specified applications.  However, if you would prefer not to restart an application which KillProcess has closed (e.g. you need to pass command line arguments to restart the process correctly) then you can append the "<norestart>" option to your keyword line.  The Software Update Wizard will then close the application if it is running but will not try to restart it after the update process has completed.  If you need to restart your application using command line arguments then you would use the ExecAfter keyword line.  For example:

[7]
Filename==http://www.mycompany.com/updates/MyApp.exe
KillProcess=MyApp.exe<norestart>
ExecAfter="<TARGETFOLDER>\MyApp.exe" -r -i

KillProcess  provides a more effective method for the applications which were terminated to be restarted after the update has taken place and we recommend using KillProcess wherever possible, in preference to WindowTitle=.

You can provide multiple KillProcess lines within a single script section.

To terminate all instances of MyApp.exe and MyOtherApp.exe prior to updating, you would include the following keyword lines:

[7]
Filename=http://www.mycompany.com/updates/MyApp.exe
KillProcess=MyApp.exe
KillProcess=MyOtherApp.exe
... etc..

Remember that if you are replacing dll files used by your application you will have to apply KillProcess to all the applications which depend on the dll files being replaced.

See also:

You can execute any number of external processes immediately after the process(es) specified in the 'KillProcess' keyword line(s) using one or more ExecAfterKillProcess= keyword lines.

Summary

1. The Software Update Wizard downloads the updated file version referred to in the Filename or Zipfile keyword line for the script section.
2. Unless you use the <nowarn> option, a message box will be posted warning that the application will be closed in order for the Software Update Wizard to update your application to the new version.
3. A Windows WM_CLOSE Windows message will be sent to each instance of the application referred to in the KillProcess line(s).
4. If the target applications do not close within the specified timeout the Software Update Wizard will forcibly terminate them using the Windows TerminateProcess() API.
5. The target application file is then updated to the new version and the new version is automatically restarted by the Software Update Wizard.

Default

This keyword is optional.

If not included in a section, no applications will be closed by Software Update Wizard.  If the Software Update Wizard finds it is unable to replace an in-use file with one it has downloaded it will post a message box asking the user to close the file.  The message box will be repeated until the file is free to be updated.  To avoid the possibility of infinite loops (because, for some reason, the user is unable to close the in-use file), you should always use KillProcess in your update scripts, unless you are totally convinced it is unnecessary.

Description

Lets you launch a process on the machine running the Software Update Wizard prior to the target files being updated.   Also supports launching Windows Powershell scripts.

Multiple ExecBefore= keyword lines are permitted within a single script update section .  The ExecBefore= processes are launched in the order in which they appear in the update script.

Note that the scope of this command is the context of an individual Script section.  Therefore, if you have 2 sections, each with its own 'ExecBefore=' keyword line, then each 'ExecBefore=' will be processed as part of the section.

You may pass any number of command line arguments to an 'ExecBefore=' command.  The following rules allow Software Update Wizard to separate the arguments from the filename:

1. If the filename path has no spaces then the first space in the 'ExecBefore=' line denotes the start of the command line arguments.
2. If the filename path does contain any spaces it must be enclosed in double inverted commas ("). The first space after second " character denotes the start of the command line arguments.

Folder Constants

You can use the Software Update Wizard folder expansion constants in 'ExecBefore=' command lines:

Therefore, for example, the command ExecBefore="<WINDIR>\notepad.exe" will be expanded to either C:\WinXP\notepad.exe or C:\Windows\notepad.exe depending on the version of Windows the user is running.

Launch and continue, or launch and wait till launched process has completed

You can control whether the script should pause until the launched process terminates or continue execution immediately after launching the process.  

If you want the script to pause until the launched process terminates, you should append the text <Wait=Yes> to the end of the command, as shown below:

ExecBefore=c:\WinNT\Notepad.exe readthis.txt<Wait=Yes>

If you use <Wait=Yes>  to wait on completion of the launched process you can also test its exit code with the additional option flag <QuitOnFail>.  This option uses the standard exit code convention where '0' represents successful completion of the launched process and any other return code is interpreted as failure.  Therefore if a non-zero exit code is received from the launched process this option causes the rest of the update process to be abandoned - effectively terminating the update process and a message to be written to the WebUpdateSvc4.log file.  As the target application will not have been updated then the next update check will attempt to perform the whole update again.

Using Long File Names

If the path contains long file names which contain spaces, you must remember to enclose it in double inverted characters.  For example, say your ExecBefore command is:

If <CLIENTFOLDER> expands to, for exampleC:\Program Files\MyAppFolder then the above syntax will fail.  The correct syntax is:

In other words, use the same syntax as you would using the Windows 'Start' -> 'Run' dialog box.

Only execute for specified Windows Version

You can (optionally) specify which versions of Windows the command will be launched for, using either <MaxVer= x,x,x> or <MinVer= x.x,x> in the ExecAfter/ExecBefore keyword line.  If the version of Windows on the Client machine passes the MaxVer/MinVer test the command will be run, otherwise it will be ignored.  If you use neither MaxVer nor MinVer then the command will always be run.

The " x,x,x" part of the syntax corresponds to values for the following items:

1. Windows Platform - 16bit Windows, Windows 9X or Windows NT and descendants.
2. Windows Major Version
3. Windows Minor Version

The possible values are listed here.

For example, the following command will only be run for Windows Vista or later platforms:

ExecBefore=wuwNTClient.exe<MinVer=2,6,0>

The following command will only run on Windows 98ME platforms:

ExecBefore=setup.exe<MaxVer=1,4,90>

Suppress command window

If you are using this keyword to execute a console command (e.g. to run a DOS command) then you can suppress the display of the command window using the "<SW_HIDE>" flag:

ExecBefore=cmd /C del "<CLIENTFOLDER>\oldsetup.exe"<SW_HIDE>

Running Windows Powershell Scripts

You can run Windows Powershell scripts or commands from an ExecBefore or ExecAfter.  You can execute a single command, a script file via a file and path on the user's computer or a script file url.  If the host computer does not have Powershell installed (e.g. Windows XP) then the ExecBefore/ExecAfter will be ignored.

The default execution policy for Powershell is 'Restricted' on most computers.  This prevents all Powershell scripts or commands from being executed.  However, the Software Update Wizard uses the elevated status of the Software Update Wizard service to temporarily set the host's execution policy to unrestricted for the duration of the execution of the Powershell script in the ExecBefore\ExecAfter.  It then resets it to whatever it was prior to the ExecBefore/ExecAfter on completion.  This is as secure as it possibly can be.  However, if the limited time that Powershell scripts can be run is not acceptable to you then unfortunately you won't be able to use this Software Update Wizard feature.

The syntax for each type of Powershell command source is as follows:

• Executing a single command:
  
  ExecAfter=Powershell New-Item -Path 'c:\temp\New Folder' -ItemType "directory"<AsUser>
  
  This command creates the folder 'New Folder' in 'c:\temp', using the logged on user's security context.  The text 'Powershell' is what the Software Update Wizard uses to identify the line as a specific Powershell syntax line.  It is case-sensitive.
  
  You can use the service's elevated security context (default = SYSTEM) to affect folders / locations the logged on user does not have rights to by omitting the '<AsUser>' option.  Note that it is not necessary to use a '<Wait=Yes>' option because the Software Update Wizard automatically adds it.  (This is because the Software Update Wizard has to wait on Powershell scripts to complete in order to be able to reset the default execution policy to its starting value without affecting the ability of the script to actually run.)
  
  The standard folder substitution variables are supported in this syntax option.
  
• Executing a script that already exists on the user's computer:
  
  ExecAfter=Powershell -File c:\temp\createfolder.ps1
  
  This command executes the Powershell script file 'c:\temp\createfolder.ps1' in the Software Update Wizard service's security context (=SYSTEM).  All other properties of this option are identical to executing a single command, described in the previous point.
  
• Executing a script from a URL:
  
  ExecAfter=Powershell http://www.mycompany.com/createfolder.ps1
  
  This option downloads the file in the URL, executes it in Powershell (in the SYSTEM security context because the '<AsUser>' option has not been used) and then automatically removes the file on completion.  All other properties of this option are identical to executing a single command.
  

Security Notes

Note that the security context of the processes launched will be as follows:

Because the Software Update Wizard Service runs in the SYSTEM security context, the default behaviour of ExecBefore / ExecAfter is to launch the specified processes in the SYSTEM context also.

However, if you append <AsUser> to the keyword line the process will then be launched in the context of the logged on user - for example:

ExecBefore="<CLIENTFOLDER>\MyApp.exe"<AsUser>

The processes will inherit the logged on user's rights.

When Actioned

After the updated file is downloaded but before the existing files are updated. If you use the MD5= keyword but the downloaded file fails its MD5 integrity check the processes specified in the ExecBefore= keyword lines will not be executed.

Default

The script continues without waiting for the process launched by an ExecBefore command to finish.  If you want the script to pause until the launched process terminates, you should append the text <Wait=Yes> to the end of the command, as shown here:

ExecBefore=c:\WinNT\Notepad.exe readthis.txt<Wait=Yes>

Description

'ExecAfterKillProcess=' is exactly the same as 'ExecBefore=' except that it executes immediately after the processes specified in 'KillProcess=' have been terminated.  Remember to use the '<Wait=Yes>' option to ensure that the specified process(es) have finished executing if any subsequent steps in your update script depend on completion of the ExecAfterKillProcess= step.

When Actioned

Immediately after the processes specified in 'KillProcess=' have been terminated.

Default

No processes will be executed if not included in the section.

Description

'ExecAfter=' is exactly the same as 'ExecBefore=' except that it executes as the last process of a section, rather than the first.

Therefore, the same folder constants, operating system filters, wait flag, security context and Powershell script execution options apply.  (See 'ExecBefore=' above for full documentation of all the options available from the ExecAfter keyword.)

This keyword is particularly useful if, say, the file that is being handled within the section is an installation program containing your updated software.

Multiple ExecAfter= keyword lines are permitted within a single script update section.  They are launched in the order in which they appear in the update script.

Please read the keyword help for ExecBefore in the preceding section before proceeding.

More information:

Note that there is a special situation where an addition to the ExecAfter syntax is required.  The Software Update Wizard's counter is incremented once all the keyword lines in a section have been successfully executed.  Suppose you launch an installation program in your ExecAfter, with a<Wait=Yes> flag.  The Software Update Wizard will launch the installation program and will wait until that process has finished before continuing (and incrementing the counter).  But what if the installation program triggers a reboot?  In this instance, the counter will never be incremented.  To address this situation, you should use the<BlockDone> flag.  When this flag is used in combination with<Wait=Yes> the Software Update Wizard counter will be incremented before the install program is launched.

The syntax in full for this situation would therefore be:

ExecAfter="<CLIENTFOLDER>\setup.exe"<Wait=Yes><BlockDone>

ExecAfter=<WINDIR>\notepad.exe G:\TEMP\demo_SQL.txt<AsUser>

ExecAfter="G:\TEMP\Long folder\my app.exe" "Peter Boulton" admin UK<AsUser>

Important Information on Launching Installers from Software Update Wizard scripts

• Make your installer 100% 'silent' (i.e. no interface / progress window etc.).  Most installer applications support command line flags such as '/S' or '/SILENT' to suppress their user interface.  You must use these options in your ExecAfter command line for the installer.  As the installer does not create any windows the interactive services detection by Windows does not apply and the installer runs successfully.
  
• Use the '<AsUser>' option in your ExecAfter and accept that the user will be prompted by Windows to elevate and run your installer, using a Windows User Account Control dialog.
  
• Don't deploy updates using installers.  You should find using the Zipfile keyword to AdditionalFile keywords allows you to deploy your updated application files equally flexibly, with a smaller download file size.  Any additional settings changes can be implemented via one or more Powershell commands/scripts or SetReg keywords.

Please bear in mind that this issue is caused by Windows security policy.  The Software Update Wizard or any other alternative automatic updates solution cannot circumvent the way Windows works in this respect (nor should it be able to, as this would constitute a serious security vulnerability in Windows).  Therefore, whichever auto-updates software solution you use will have to operate in one of the three ways described in this section.

When Actioned

After the update file has been downloaded.

Default

As 'ExecBefore='

Description

Example

DelTree=<CLIENTFOLDER>\somefolder

DelTree=<CLIENTFOLDER>\somefolder<Before>

DelTree=<CLIENTFOLDER>\somefolder<Before><FilesOnly>

When Actioned

Default - if not used

Description

When Actioned

Default - if not used

Description

Example

• The registry root key - HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE etc.
• The path to the required registry key.  If it does not already exist it will be created.
• The name of the registry value name you want to write to.  If it does not already exist it will be created.  If you just want to write to the "(Default)" (i.e. not to a registry value name) then the field must be included and should be blank - as in '...ws\Advisor||"Thi...'.
• The value you want to write to the registry value data.

Writing to a REG_SZ type registry value data field is identical to REG_DWORD but you must enclose the required text in quotes:

SetReg=HKEY_LOCAL_MACHINE|Software\Data Perceptions\Prophecy\Prophecy for Windows\Advisor|NewTextKey|"A textual field"

The '<AsUser>' Flag

64 Bit / 32 Bit Filtering

When Actioned

Default - if not used

Description

Description

When Actioned

After the update file has been downloaded and the ExecAfter commands have been launched. 

Default

This is an optional keyword line.  If you do not use it no information will be transmitted by the Software Update Wizard.

Description

Example:

NoSuccessMessage

Default

A default success message will be generated.

Description

See Message= for an example of the syntax used - just substitute FinalMessage= for Message=.

When Actioned

After all the keyword lines (except  'Reboot') have been processed

Default

The standard download success message will be displayed, unless you also use the ' NoSuccessMessage= ' keyword.

Description

The Software Update Wizard offers two options for addressing the issue of replacing in-use files (i.e. files which are in use by Windows and therefore cannot be updated):

• Use the WindowTitle or KillProcess keywords to close all instances of the application(s) responsible for the target file being in use.  In most cases this is the recommended route because it does not require a reboot.
• The MoveFileEx keyword, which causes the in-use file to be updated with the new one after the next reboot.  This should be used where the WindowTitle or KillProcess keywords are inapplicable. For example, you could use MoveFileEx to update the Software Update Wizard version itself (see here for more information on updating the Software Update Wizard itself) or to replace a DLL which cannot be unloaded promptly in response to a WindowTitle or KillProcess keyword lines.

Example

As you can see, you can use the same constants as for the ExecBefore / ExecAfter keywords.  TheFrom part is the downloaded updated file and theTo part is the existing file.  The From and To elements are separated by a '|' character.

Each script section may have as many MoveFileEx lines as required.

The way in which locked files are updated differs between Windows 9x platforms and NT based platforms.  The Software Update Wizard will determine which operating system it is running on and take the appropriate action:

When Actioned

After the ExecAfter commands have been completed and before the SubmitForm command.

Default

This is an optional keyword.  If you do not use it then no file updates will be actioned for the next reboot.

Description

Prompts the user and then reboots the PC if the user clicks the 'Yes' button:

Example 1

 This example causes a prompted reboot.

Reboot

Example 2

This example causes an automatic (i.e. unprompted) reboot:

Reboot<nowarn>

When Actioned

After all the other keywords in the script section have been interpreted and actioned.

Default

No reboot will occur

Description

Lets you launch a Campaign Manager script from within an update script section.

The Software Update Wizard can be used either for campaign management, or for updating software via the web. However, in a situation where both features are required and need to be launched sequentially from your application you should use this keyword, rather than 2 successive calls to the Software Update Wizard from your software. Why? For the following reasons:

1. It lets you tie an individual campaign script to a particular script section, or to all script sections (see examples below)
2. It saves one call to the Software Update Wizard from your application, and lets you plug in a campaign when required by just adding this keyword to your standard update script.
3. If you launch an update script followed immediately by a campaign manager script from your application the Software Update Wizard may still be busy processing the update, so that the campaign script will be ignored. This does not happen if you use theCampaignManager= key word in your update script.

When Actioned

Example 1: Before the specified update block gets processed

[7]
Filename=http://www.myserver.com/newfile.exe
CampaignManager=http://www.myserver.com/campaign.txt<Before>

Example 2: After the specified update section gets processed

[7]
Filename=http://www.myserver.com/newfile.exe
CampaignManager=http://www.myserver.com/campaign.txt<After>

• The user has not previously updated via section [7]
• The script section was successfully processed

Example 3: Always launch the campaign script, even if no updates are required

[99999]
Message=You already have the latest version!
CampaignManager=http://www.myserver.com/campaign.txt

[99999]
CampaignManager=http://www.myserver.com/campaign.txt

Default

No campaign script will be launched.

Description

Example

Default

Description

Example

Default

Description

Example

Default

Description

Description

Example

XML_FileVersion=<WINDIR>\NOTEPAD.EXE

This keyword line will add the following tag to the generated XML file (providing an update is required from the script section in which the keyword line resides):

<FileVersion Name="C:\Windows\NOTEPAD.EXE">6.0.6000.16386</FileVersion>

Default

The XML file generated by pass 1 of the 2-pass process will not contain any <FileVersion> tags.

Description

Example

This keyword line will add the following tag to the generated XML file (providing an update is required from the script section in which the keyword line resides):

<Dependency>OfficeUpdates</Dependency>

The text to the right of the '=' sign in the keyword line is simply added as a tag to the generated XML file.

Default

The XML file generated by pass 1 of the 2-pass process will not contain any additional tags.