Software Update Wizard - Keywords Reference


Quick Links:

View alphabetical list of keywordsView categorised list of keywords

Please note that all Software Update Wizard keywords are case-sensitive.

Keyword

Usage

[ aninteger ]
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.

Testmode
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:
Testmode

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.

RunAlways
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.

IniSectionID=
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:
IniSectionID=anythingyouwant
Default

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

Filename=

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:
Filename=/subfolder/webupdatefile.exe

or..

Filename=/webupdatefile.exe

 

or..

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

 

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.

Zipfile=

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.

AdditionalFile=
Description
This keyword is additional to the Filename and Zipfile keywords and lets you download one or more additional files (using multiple AdditionalFiles lines) within a single script update section.

You can specify a separate target folder for the file, independently of the TargetFolder for the overall section.

You can make each AdditionalFile line perform the update (or not) depending on the existing file's version, MD5 value or datestamp versus the value in the script.

You can provide a description of the additional file, which can be displayed (using tag substitution as shown in the example below) in your Message= notification boxes.

Finally, you can provide an optional MD5 value for the file, which causes the Software Update Wizard to only persist the updated file if its MD5 stamp matches.

Note that the AdditionalFile lines within an update section will only be evaluated if the section itself needs to be actioned.  If the Software Update Wizard determines that the section does not need to be actioned based on the Filename/Zipfile and related checks then the AdditionalFile lines within the section will be ignored.

The files downloaded as a result of AdditionalFile are always downloaded after the file downloaded by the Filename and Zipfile keywords.  Multiple AdditionalFile lines in the same script are executed/downloaded in the order in which they appear in the script section, i.e. from top to bottom.
Example
[1]
RunAlways¶
Filename=http://www.myserver.com/mainupdate.exe¶
FileVersion=2.0.0.0¶
AdditionalFile=http://www.myserver.com/extradll.dll|<CLIENTFOLDER>|Version=7.0.6.1| There is also a new dll for you!|6E3B68B8ADC77FB1283AED789E6656AA¶
AdditionalFile=http://www.myserver.com/newdata.dat|<CLIENTFOLDER\data|<NA>| In addition, there is an update of your data file.¶
Message=We are updating your version of Mainupdate.exe. <AdditionalFiles>  Thank you for using our software!¶

(Please note that we have included ¶ characters in the example above to make line endings clearer.  In addition, the '|' character (ascii 124), which is used to separate the parameters within an AdditionalFile line, is displayed in red for better clarity.)

Each AdditionalFile line has the following components, separated by a '|' character:
  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.
Note that only item (5) is optional.

The Version or Date syntax for parameter 3 can be either "Version=n.n.n.n" or "Date=yyyy/mm/dd/hh/mm/ss".  See FileVersion for more information about how the Software Update Wizard handles versions and file datestamps. The MD5 syntax for parameter 3 is "MD5=7c8fcc84793de6007d1f7d19d8aae7f9" where "7c8fcc84793de6007d1f7d19d8aae7f9" is the MD5 of the file referred to in the AdditionalFile line.

Tip: a download progress dialog box will be launched sequentially for each AdditionalFile update.  In order to avoid the user seeing multiple 'flashing' download progress dialogs we recommend that you use the <noui> option for the smaller files - e.g. AdditionalFile=http://www.myserver.com/extradll.dll<noui>|<CLIENTFOLDER>|Version=7.0.6.1| There is also a new dll for you!

Default
This keyword is optional.
 
Predownload
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 

[1]
Filename=/DBA.exe
Predownload[4c2a96ec42cce780de3a0a420a2eaf2e]
... etc. ...

Default

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

ServerTimeout
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.

Throttle
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
If not included in the script the downloads will operate at maximum speed.
 
MD5=
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:
[3]
Zipfile=http://www.someotherserver.com/subfolder/webupdatefile.zip
MD5=388B8FBC36A8558587AFC90FB23A3B99
etc..

 

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.


DialogBk=
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

DialogTxt=
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.

TitleBk=
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.

TitleTxt=
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

Bitmap=
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:

Bitmap=c:\Windows\mybitmap.bmp

 

Specify a bitmap located on a web address:

Bitmap=http://www.mycompany.com/mybitmap.bmp

 

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.

Icon=
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:
Icon=<PROGRAMFILES>\MyApp\MyIcon.ico

 

Icon=http://www.mycompany.com/MyIcon.ico

 

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.

Title=
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"

Subtitle=
Description
Optional subtitle text which is displayed at the bottom of the graduated title bar of the Software Update Wizard dialog boxes.

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)

SubTitleColor
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.

ScrollingLink=
Description
This is an optional line which adds a scrolling link to the bottom of the Software Update Wizard dialog boxes.  The link scrolls continuously until the user moves their mouse over it, when it stops.  If they click the link it opens in Internet Explorer.  When they move their mouse away again the link restarts its scrolling from right to left across the bottom of the dialog box.



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

MessageBoxScale=
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
MessageBoxScale=150,120

MessageBoxScale=80,80   

 

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.

ShowSystemTray=
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:

[1]
...
ShowSystemTray=Show|Processing update 1|Processing the first update|Update 1
...

[2]
...
ShowSystemTray=Hide
ShowSystemTray=Show|Processing update 2|Processing second update|Update 1
...

 

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
No system tray icon is displayed.
LoginAs=

 

Password=

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:

Encryption dialog from Software Update Wizard Project Manager Utility

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]

Note that the Software Update Wizard will interpret the text LoginAs=>><[ and Password=>><[ as encrypted lines.  Do not omit the 'decoration' to the right of the '=', as otherwise the login names and passwords will be interpreted as unencrypted text and decryption will not occur.
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.

LoggingOn

LoggingOff

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
Logging will be On.

(See also: SuperLogging INI file setting and SuperLogging keyword.)

SuperLogging

Description
As described in the SuperLogging INI file setting help text, switching SuperLogging on in the WebUpdateSvc4.ini file captures a significantly higher level of detail of Software Update Wizard update process activity.  Whereas the INI file setting applies globally, the SuperLogging keyword within an update section applies only to the update section in which it is found and the prior global setting is applied after each update section is completed.  In other words, if the user has the global INI section setting set to 'N' (=no verbose logging) you can switch it on for the duration of an update section by including this keyword in the section.

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
   [55]
  RunAlways
  SuperLogging
  ... etc...
Default
The default setting will be the one specified in the WebUpdateSvc4.ini file.

PollInterval=
Description
The Software Update Wizard polls for incoming update requests from clients at regular intervals.  If no incoming request is detected it goes back to sleep immediately, thereby consuming negligible cpu.

This keyword allows you to change the polling interval of the Software  Update Wizard Service, in milliseconds.  The default is once per 3 seconds (=3000).  If you use this option to change the default the new setting will persist in the user's WebUpdateSvc4.ini file under 'WuWSettings' --> 'PollInterval'.

Please note that polls really do involve negligible cpu.  Although polling every 3 seconds sounds a lot your users will not notice any slowing of their computer as a result of running the Software Update Wizard Service.

However, if you would prefer a longer polling interval then you can use this setting, which applies globally to all applications which use the Software Update Wizard.  The new setting applies immediately and persists until it is changed again in a subsequent update script section.

This keyword is ignored if you are using the Software Update Wizard in application mode.  See Architecture of the Software Update Wizard.

Example
PollInterval=1000

The syntax example above changes the polling interval to once per second (i.e. 1000 milliseconds).
Default
  The existing polling interval is used.


PlatformMin=
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
PlatformMin=2,6,0


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.

PlatformMax=
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
PlatformMax=2,6,0


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.

FileDate=
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:

[1]
RunAlways
Filename=http://www.myserver.com/myapp.exe
FileDate=2008/9/18/16/15/00
CheckFileExists=<CLIENTFOLDER>/myapp.exe

 

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:

FileDate=2012/9/18/16/15/00

 

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

FileVersion=
Description
This keyword lets you determine whether an update is necessary based on the version number of the file referred to in the Filename= section.  If you are using the Zipfile option for your update file please see the CheckFile= keyword.

Most Windows applications, dlls and ocx's have version numbers, which you can access by right-clicking on their filename in Windows Explorer, selecting 'Properties' from the popup menu and then clicking the 'Properties' tab.

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:

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

 

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.

FileMD5=
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:
FileMD5=d3f1ffc471adaec1d20e658d3c46667f

 

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.  

CheckFile=
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:
CheckFile=<CLIENTFOLDER>\anyfile.txt<Date=2004/12/01/23/00/00>

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:
CheckFile=<CLIENTFOLDER>\anyfile.dll<Version=2.0.0.0>

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:
CheckFile=<CLIENTFOLDER>\anyfile.dll<Version=2.0.0.0><Date=2004/12/01/23/00/00>
  • 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:
CheckFile=<CLIENTFOLDER>\anyfile.dll<Version=2.0.0.0>
CheckFileExists=<CLIENTFOLDER>\anyfile.dll

 

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:
CheckFile=<CLIENTFOLDER>\anyfile.dll<Version=2.0>
CheckFileExists=<CLIENTFOLDER>\anyfile.dll

 

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.

CheckFileExists=
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:
CheckFileExists=<CLIENTFOLDER>\mydll.dll

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.

Message=

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.

More..

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:

<body scroll="no">This web browser control has no scroll bar!</body>

 

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:

Tag What it does
<nobitmap> The web browser control expands horizontally to cover the full width of the dialog box.
<noheading> The web browser control expands vertically to cover the graduated title area of the dialog box.
<overlapbuttons> The web browser control expands vertically to cover the area where the OK or Yes/No buttons are usually displayed. The buttons are painted on top of the web browser control.
<MessageBoxScale=x,y> Scales the entire parent dialog box by a width and height percentage.  For example, including the tag "<MessageBoxScale=120,130>" scales the parent dialog box to 120% of its default width and 130% of its default height.  This tag overrides the default scale for the single dialog box in which the tag is used.

 

 

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:

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).

MessageBoxBoilerPlate

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>
This simple template causes the message boxes displayed by the Software Update Wizard to be displayed without the default vertical scroll bar and without the border between the web browser control and the dialog window that contains it.  When the Software Update Wizard needs to display a message the specified text is inserted into the template to replace the text "[!Content!]".

Note that the constant "[!Content!]" is case sensitive and must be provided.

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.

Importance=

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.

Backup=

Description

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

Example:
Backup=Yes

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.

TargetFolder=

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\


WindowTitle=

Description

Note: this keyword has been retained for backward compatibility.  We recommend that you use the KillProcess keyword to automate the closing and restarting of your application during an update.  Please be aware that WindowTitle only checks and closes windows running in the same security context as the Software Update Wizard service application - normally SYSTEM.  KillProcess is able to close and restart applications running in any security context and is the recommended replacement for WindowTitle.

However, if you absolutely need to be able to close a window based on its title text then you can use the following ExecBefore line:

ExecBefore=Powershell Get-Process | Where-Object { $_.MainWindowTitle -like 'National*' } | Stop-Process<AsUser><SW_HIDE>

This line will cause all windows containing the wildcard text 'National*' to be closed.  The '<AsUser>' Software Update Wizard flag causes the process to run in the context of the currently logged in user.

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:

[1]
Zipfile=/wuw/MyUpdate.zip
Message=There is a new version of SuperProgram available!
WindowTitle=SuperProgram<Timeout=1000>
ExecAfter=<CLIENTFOLDER>\SuperProgram.exe

[9999]
Message=You already have it!

 

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.)

KillProcess=
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:

KillProcess=MyApp.exe<Timeout=10000>

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:

KillProcess=MyApp.exe<Timeout=10000><nowarn>

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.
Summary
To summarise, this is what happens when the Software Update Wizard finds a KillProcess line in a script section:

  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.

ExecBefore=
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:

ExecBefore=<CLIENTFOLDER>\MyApp.exe

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

ExecBefore="<CLIENTFOLDER>\MyApp.exe"

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:

WebUpdateSvc4.exe as Windows Service:
 

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>
WebUpdateSvc4.exe as standard Windows executable application
 

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
If not included in a section then no processes will be launched.
 

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>

ExecAfter=
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>
Here are some more syntax examples:
ExecAfter=<WINDIR>\notepad.exe G:\TEMP\demo_SQL.txt<AsUser>
The example above launches the file g:\temp\demo_SQL.txt into Windows Notepad in the user's system security context. (Important: If you are running the Software Update Wizard as a service application you should always remember to use the <AsUser> option because Windows Vista or later will intercept any attempts by a service application, or processes launched from a service application, from interacting with the user.  The <AsUser> flag causes the launched process to be launched in the security context of the logged on user.  Therefore no security warnings will be posted by Windows - the desired user experience.)
ExecAfter="G:\TEMP\Long folder\my app.exe" "Peter Boulton" admin UK<AsUser>
This example shows the correct approach to long file names and command line arguments.  The path to the executable is enclosed by double inverted commas.  If a command line argument has spaces it too should be enclosed by double inverted commas.

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.

A typical scenario for using the <QuitOnFail> option is where you use an ExecAfter to launch an installer.  Say the user cancels out of the installer, causing it to exit with a non-zero exit code.  In that instance, you would not want an update success message box to be shown and you would not want any further update script keywords to be actioned.

Important Information on Launching Installers from Software Update Wizard scripts
Some Software Update Wizard users prefer to use the Software Update Wizard to deliver their software updates in standard Windows installers using a 'Filename=http://www.mycomany.com/setup.exe' type keyword line to download the installer and to then launch the installer using an ExecAfter.  This method is fully supported by the Software Update Wizard, within the security constraints of the Windows operating system.

However, an issue arises when the installer is launched using the security context of the  Software Update Wizard service application, SYSTEM.  Microsoft has prevented service applications from interacting with the user's desktop since Vista because it is a security loophole.  Therefore, if you launch an installer (or any other application that has a user interface) from a Windows service, Windows will normally intercept it and post an 'Interactive Services Dialog' or task bar notification.  The user has to 'notice' this, agree to action it, go to a separate desktop that opens, run the interactive application and then close the separate desktop.  This is very far from ideal in a software update context and ideally needs to be avoided.

The only way to avoid the 'Interactive Services Dialog' / notification is via one of the following routes:
  • 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='

DelTree=
Description
This keyword lets you recursively delete a folder structure, much like the (old) DOS command, deltree. It will delete all the files and folders within the specified folder path, including the specified folder itself, including files that have the read-only or system attributes set.  However, it will fail to completely delete the tree structure if any of the files within it are open and in use.

You can use any of the Software Update Wizard folder substitution tags in a DelTree keyword line.
Example
DelTree=<CLIENTFOLDER>\somefolder
This keyword line will deletesomefolder and all folders beneath.  It will be executed after the ExecAfter commands have been launched.  If you prefer the DelTree to be executed at the start of the update process, immediately after the ExecBefore commands have been launched, append the tag <Before> to the keyword line, as shown in the next example:
DelTree=<CLIENTFOLDER>\somefolder<Before>
The <FilesOnly> option flag allows you to use this keyword to recursively delete all the files in the specified tree whilst leaving the folder structure intact:
DelTree=<CLIENTFOLDER>\somefolder<Before><FilesOnly>
The <FilesOnly> option flag in the example line above causes only the files within the nested folder structure to be deleted, retaining the full folder structure.  
When Actioned
If you do not use the <Before> tag then the folder tree will be deleted immediately after any ExecAfter keyword lines and before any KillProcess lines. (See also DelTreeAfterKillProcess to execute after processes have been killed). If you use the <Before> tag then the folder tree will be deleted immediately after any ExecBefore keyword lines.
Default - if not used
No folders or files will be deleted!
DelTreeAfterKillProcess=
Description
This keyword performs the same function as DelTree <CLIENTFOLDER>\somefolder<Before> except that it is executed immediately after all the KillProcess lines in the update script have killed the specified processes and before the update process begins.

The <FilesOnly> option flag performs exactly as in DelTree and allows you to use this keyword to recursively delete all the files in the specified tree whilst leaving the folder structure intact.
When Actioned
After  KillProcess and before the file update in the script is made.
Default - if not used
No folders or files will be deleted!
SetReg
Description
Allows you to set a registry key value. If the key does not already exist it will be created.  You can limit the action to 32-bit Windows, 64-bit Windows or either, as described below.  You can perform registry operation using either the security context of the Software Update Wizard service (e.g. to update a registry key the logged on user does not have rights to) or using the security context of the logged on user (e.g. to update a setting under the user's HKEY_CURRENT_USER branch).  You can include any number of SetReg lines in a single update script section.
Example
This SetReg shows the minimum required syntax to create / write the value '17' to a registry key whose data type is type REG_DWORD:

SetReg=HKEY_LOCAL_MACHINE|Software\Data Perceptions\Prophecy\Prophecy for Windows\Advisor|NewKey|17

Note that the syntax breaks the statement down into separate fields, delineated by '|' (ascii 124) characters (highlighted yellow in the example syntax above).  The fields are:
  • 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
The preceding examples will all be executed in the security context of the Software Update Wizard service application (assuming you are running as a service) - i.e. SYSTEM.  This is ideal for writing to HKEY_LOCAL_MACHINE even if the logged on user does not have rights to write there.

However, if you use the same syntax as above to write to HKEY_CURRENT_USER you will find that the command succeeds but writes to the HKEY_CURRENT_USER associated with SYSTEM, the security context the Software Update Wizard service runs in.  To update the logged on user's HKEY_CURRENT_USER you must include the "<AsUser>" option flag:

SetReg=<AsUser>HKEY_LOCAL_MACHINE|Software\Data Perceptions\Prophecy\Prophecy for Windows\Advisor|NewKey|17

64 Bit / 32 Bit Filtering
By default, the SetReg feature writes the specified key/value irrespective of whether it is running on a 32 bit or 64 bit host.

However, you can constrain the operation to either 32 bit only or only 64 bit only hosts using the optional flags '<32bit>' and '<64bit>'.  If your SetReg contains neither option flags it will be executed on 32 bit and 64 bit hosts.  If it contains just the '<32bit>' flag it will only be executed on 32 bit hosts.  If it contains just the '<64bit>' flag it will only be executed on 64 bit hosts.

The following SetReg will be executed for 64 bit platforms only:

SetReg=<64bit>HKEY_LOCAL_MACHINE|SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Software Update Wizard (Redist)|DisplayVersion|5.2

The following SetReg will only be executed for 32 bit platforms:

SetReg=<32bit>HKEY_LOCAL_MACHINE|SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\Software Update Wizard (Redist)|DisplayVersion|5.2
When Actioned
After all ExecAfter commands have been launched and before the final success message (if used) is displayed.
Default - if not used
No registry changes will be made!
SubmitVariable
Description
Used to declare lookup variables to registry strings, which are then substituted for the variables in CheckFile, CheckFileExists, ExecAfter, ExecBefore, SubmitForm and TargetFolder keywords.

This keyword is explained in more detail here.
SubmitForm=
Description
The Software Update Wizard can generate an (optional) http: GET or POST request to a web server, as if the information had submitted from an html form on a web page.  This powerful feature allows you, the software developer,  to transparently receive confirmation that your customers have successfully updated their software using the Software Update Wizard.  Please follow this link for further information.
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.

NoSuccessMessage
Description
Suppresses the display of the automatic Software Update Wizard download success message box. 

However, if you are supplying a FinalMessage= override in your script then this keyword has no effect.  That is, it only suppresses the default success message box.
Example:
NoSuccessMessage
Default

A default success message will be generated.

FinalMessage=
Description
Lets you provide your own text to be displayed in a Software Update Wizard message box, after all the keyword lines (except  'Reboot') have been processed for the update file section.
 

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.

MoveFileEx=
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
MoveFileEx=From=<CLIENTFOLDER>\MyApp.ex_|To=<CLIENTFOLDER>\MyApp.exe

 

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:

 

Platform Action
Windows 9x Creates an entry in the WinInit.ini file.  This file is processed at boot-up by Windows 9x and handles replacement of in-use files.

There is a (Windows) limitation on how this functionality is implemented - it can only process short (8.3) filenames.  Therefore the files being updated in this way on Windows 9x platforms must have 8.3 filenames.

Note that the folder path you supply in the MoveFileEx keyword line can (and should) be the long version of the folder path.  The Software Update Wizard will convert it to the short version on the user's PC at runtime.  Only the file name should be an 8.3 name.

>Windows 9x Uses the Windows API MoveFileEx function to create appropriate registry entries to handle file update at the next reboot.  This method does not have the same 8.3 filename limitation as the WinInit.ini route on Windows 9x platforms.
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.

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

CampaignManager=
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
You have 3 options to control the point at which the Campaign Manager script is launched, as demonstrated in the following examples:
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>

In this example, the campaign is launched before any other commands in section [7].

The campaign script will only be launched if the user has not previously updated via section [7].

If the user has already received the update in section [7] the campaign script will not be launched.

This option gives you the opportunity to launch different campaign scripts from different script sections.

Note that<Before> is the default option for this keyword. If you omit<Before> or<After> from the keyword line then<Before> will be used.

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>

In this example, the campaign is launched after section [7] has been successfully processed. Therefore it will only be launched if:
  • 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
As explained in the FAQ section, it is possible to post a message box confirming that the user's software is already up to date and that no updates are required this time, by posting script section at the bottom of your update script with a 'Message=' keyword line.

If you also add a CampaignManager= line to this section then the campaign script will be launched each time the server script is run, irrespective of whether any updates are required, as shown in the following example:

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

If you want to launch a campaign in this way but do not require the message, you can simply have aCampaignManager= keyword line in this section:

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

Default

No campaign script will be launched.

Group=
Description
This keyword is used in 2-pass update scripts and allows you to link an update section to a named group of updates.  When the controlling application for the 2-pass update parses the XML file which the first pass generates it can then specify which update groups should be processed in the second pass.  (Please see the help topic 2-Pass Updates.)


A Group name can be any alphanumeric text value.
Example
Group=dllupdates2
Default
If you are using 2-pass updates then this keyword is required.  If you omit it the section with be ignored and will not be included in the generated XML file.

If you use this keyword in single-pass updates it will simply be ignored.
Priority=
Description
This keyword is used in 2-pass update scripts and allows you to assign a numeric priority value to the update section in which the keyword line resides.  It is not used by the Software Update Wizard, but is included in the XML file generated by the first pass scan.  Your application can then parse the XML file and decide which updates need to be processed based on their priority, if that is what you want your application to be able to do.  Otherwise, your application can ignore the priority tag.
Example
Priority=5
Default
The Priority tag in the XML file generated by the first pass will be -1.  If you use this keyword in single-pass updates it will simply be ignored.
ShortMessage=
Description
This keyword is used in 2-pass update scripts and allows you to specify the short message which will be written to the XML file if the section in which it resides needs to be processed in the second pass.  It allows your controlling application to pick up a short description of the update to present to the user.
Example
ShortMessage=Updates for Printing Component
Default
If you do not include a ShortMessage line in a 2-pass update script section then the ShortMessage tag in the XML file generated in the first pass by the Software Update Wizard will be blank (empty).

The line will be ignored if you include it in a single pass update script.
LongMessage=
Description
This keyword is used in 2-pass update scripts and allows you to specify the long message which will be written to the XML file if the section in which it resides needs to be processed in the second pass.  It allows your controlling application to pick up a long description of the update to present to the user.

All other properties and behaviours are as ShortMessage
XML_FileVersion=
Description
This keyword is used in 2-pass update scripts and allows you to add a file version tag for any file on the user's computer to the XML file of available updates which is generated by the first pass.

Note that the tag will only be added to the generated XML file in the first pass if an update is actually applicable.

You can include any number of XML_FileVersion lines in an update script section.

You may use any of the Software Update Wizard's folder substitution variables.  (See TargetFolder.)

If the file referred to in the XML_FileVersion keyword line exists on the target computer and it has a version string then the version string will be written to the generated XML file in a <FileVersion..> tag.  If the file exists but it does not have a version string then the text "MissingVersionData" will be written to the <FileVersion..> tag.  If the file does not exist then the text "NotFound" will be written to the <FileVersion..> tag.
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.

XML_Spare=
Description
This keyword is used in 2-pass update scripts and allows you to add any number of user-defined informational tags to the XML file which is generated by the first pass of the update script.

You can use this option if the Group or Priority values for each update section are insufficient for your controlling application to determine which updates it would like the Software Update Wizard to process on the second pass or to help your controlling application with its interaction with the user.

Note that the tag(s) resulting from using this keyword will only be added to the generated XML file in the first pass if an update is actually applicable.

You can include any number of XML_Spare lines in an update script section.
Example
XML_Spare=<Dependency>OfficeUpdates</Dependency>

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.