Advanced Installer Updater
Advanced Updater is an executable tool whose roles are to check for updates, inform the user of their presence and offer to download and install them. After launching the Updater, it checks if a newer version of the application exists by using a predefined rule.
When enabling automatic updates capability to your application, a copy of the Updater (having the name you specify) and the INI configuration file will be inserted into the install package.
1. Using the Updater
The Updater should be launched from within your application with one of the command line options in the ‘Updater options’ section. For example, you could add a menu option that will launch the Updater. To do that just execute the Updater tool with the "/checknow" command line, when that menu option is selected.
You need to pass arguments one by one. Only one command line with
/ is accepted at a time. For example, if you need to make a log file
while updating your application, first you need to execute the /set loglevel
"Error|Debug" command, and then you can use
/checknow
Here is a C# example:
Process
process = Process.Start(updaterModulePath, "/set loglevel
Error");
Process process1 = Process.Start(updaterModulePath,
"/checknow");
When launched, the Updater automatically downloads from the URL location specified in the "Update URL" field (Updater), the updates configuration file. After the INI file is downloaded the Updater checks for newer versions of the application if they exist the user is informed.
2. Updater options
The Updater has the following command line options:
| Command-line option | Functionality |
|---|---|
| /checknow | The Updater is launched and shows a dialog box, checks for updates and automatically informs the user if any updates are available. |
| /silent | The Updater searches silently for updates at the interval specified in the Configuration dialog - "Check Frequency" field (Updater). If the check frequency has passed and updates are found, the Updater will be launched with full UI and display them to the user. Otherwise, it will exit immediately. The silent switch has the purpose of hiding the Updater messages which inform that it is searching for updates and that no updates have been found, which appear when using "/checknow". |
| /silentall | The Updater will search silently for updates and automatically install all updates; this has the same effect as the /silent option if the user has selected the "Check and automatically install all updates" option in the configuration dialog. If the check frequency has not passed or there are no updates available, the Updater will exit immediately. |
| /silentcritical | The Updater will search silently for updates and automatically install only the critical ones. This has the same effect as the /silent option if "Check and automatically install critical updates" was selected in the configuration dialog. If the check frequency has not passed or there are no updates available, the Updater will exit immediately. |
| /justcheck | The Updater checks if new updates are available and gets a return code (see the Updater return codes section). This check is silent without UI. Start the Updater using /checknow, /silent, /silentall or /silentcritical if you want to download and install updates. |
| /set retryattempts <retryattemptslitmit> | Specifies how many times the Updater can try to reconnect to the server and check for updates if the initial check failed. The recommended value for <retryattemptslitmit> is between 0 and 6, with 0 meaning that no attempt to reconnect to the server will be made. The timeout between the checks is 30 seconds. |
| /set rememberpassword <username> <password> | Sets the authentication credentials of <username> and <password>. These credentials are encrypted, stored per-user on the client machine and are used when a proxy or web server requires authentication. You can call this command multiple times to have the Updater remember multiple passwords. |
| /set loglevel <attributes> | Updater logging is disabled by default, run this command to enable it. This command
line sets the Updater log level with the specified attributes. The log file is named
"updater.log" and created in the folder where the updates are downloaded. You
can combine the following attributes by separating them using the pipe character
("|") and enclosing them using quotes ("Error|Debug"):
|
| /set autoupdatepolicy <policy_type> | Set the policy for the Updater by choosing to Disable | Prompt | AutoAll
| AutoCritical. Only one option at a time can be used. Example: updater.exe /set autoupdatepolicy Disable |
| /runservice | Enables the Updater to run as a service. It can only be used if you want to manually install the service required by our Install updates without elevation support. The Updater service should be configured to start using the /runservice command line argument. |
| /configure [HWND] | The Configure dialog will be displayed allowing the configuration of the Updater. In this dialog, the user can specify the download folder, the check frequency, enable or disable the automatic update option. This command line could be used with an optional parameter that specifies the parent window handle (HWND) for the "Updates Options" dialog. This parameter is of unsigned integer type. |
| /set proxy <IP:PORT> or <name:PORT> | Sets a proxy server for the Updater. The poxy name is saved in per-user registry hive and will be used when running the updater in any mode. |
| /set downloadsfolder <folder> | Specifies a folder that will contain the downloaded files. |
When using the /silent, the Updater will check for updates at its first launch. After that, a check is performed only if the specified frequency has passed (usually 2 days). If the Updater is launched after the check frequency passes and finds any updates, it will prompt the user. Otherwise, it will exit.
A toast notification: "All updates were installed successfully" is
displayed when the Updater runs in /silentall or
/silentcritical modes, the Updater Wizard is minimized and all
updates were installed successfully.
Updater command line switches
| Command-line switch | Functionality |
|---|---|
| -nogui | The Updater is launched without user interface. It can be used with the /silentall and /silentcritical command line options and it's incompatible with -reducedgui. |
| -reducedgui | The Updater is launched with basic user interface (simple progress and error handling). It can be used with the /silentall and /silentcritical command line options and it's incompatible with -nogui. |
| -nofreqcheck | The frequency check is skipped. It can be used with the /silentall and /silentcritical command line options. |
| -justdownload | The Updater returns after downloading the updates without installing them. It can be used with the /silentall and /silentcritical command line options. To install the downloaded updates, call the updater again with any of the /checknow, /silent, /silentall or /silentcritical command line options |
| -url <location> | Instead of using the Updates Configuration File url from the Updater configuration INI file, the Updater will use the one specified in the <location>. It can be used with the /checknow, /silent, /silentall, /silentcritical and /justcheck command line options. |
| -licensendate <date> | This switch can be used with /justcheck and it verifies if the maintenance plan is valid. <date> has the form DD/MM/YYYY and returns 0 or 0xE0000028 (see the Updater return codes section). |
| -startminimized | The wizard starts minimized and updates notifications are shown by a balloon tooltip in tray. This switch can be used with /checknow and /silent options. |
| -minuseractions | Minimizes the user interaction. The dialogs "Please Wait..." and "Error" will not be displayed. It can be used with the /checknow command line option. |
| -licenseid <license_id_string> | Helps to specify the license ID string that is used for License Check directly from the command line. You cannot specify both the license ID string and registry path from where to extract license ID. |
| -licensecheckurl <license_check_url> | Helps to specify the license check URL used for License Check directly from the command line. License check URL specified in command line has priority over the one specified in Updates Configuration File. |
| -dumpdetected <file_path> | File where the information about the detected updates is stored. The format of the file is the same as the format of Updates Configuration File. It can only be used with the /justcheck command line option. If the file already exists it will not be overwritten. |
| -critical | Can be used only with /justcheck, so that the Updater silently checks only for critical updates. |
| -installready | Only available for /justcheck command, it determines if updates are found and have been downloaded. For return codes, see the Updater return codes section. |
| -restartapp <application_executable_path> | Full path to an executable that will be launched if no updates are found, frequency check interval has not passed or an error occurs (no Internet connection, etc.). The executable will not be launched if the updates are installed successfully. It can be used with the /checknow, /silent, /silentall, /silentcritical and /justcheck When used with /justcheck a toast notification will be displayed. |
| -restartappcmd <application_command_line_params> | This switch works together with -restartapp to specify the command line parameters which will be passed to the executable. |
| -startappfirst | This switch works together with -restartapp. It allows the application to start first and then perform the check for updates. |
| -showaitdlg | Shows the "checking for updates" dialog. It can be used with the /silentall and /silentcritical command line options. |
Examples
- updater.exe /silentall -nofreqcheck
- updater.exe /checknow -url http://www.example.com/updates.aiu
- updater.exe /set loglevel "Error|Debug"
3. User authentication
You can restrict the user access to the updates configuration file or an update file using username/password authentication. The user will be prompted to enter the password, and the Updater can remember the password if the user chooses to do so.
The password sent by the Updater to the server is sent as plain text and is not
secured.
4. Automatically download and install updates
This option is enabled by selecting the "Check and automatically download and install" option from the "Configure" dialog, giving you have two choices Critical or All.
5. Automatically close the updated application
The Updater can automatically close the updated application. The path to the application that must be closed is specified in the configuration file in the "AutoCloseApplication" entry.
6. Updater return codes
The return codes can signal status information or errors and can be Updater specific errors or Windows generic errors.
Status Information
- 0 - Found updates for the application or the updates match /justcheck filters like -installready or -critical.
- hex: 0xE0000011 / decimal: -536870895 - No updates are available for the application or there are no updates matching /justcheck filters
- hex: 0xE0000019 / decimal: -536870887 - Updater was called with /silent, /silentall or /silentcritical command line options and automatic updates are disabled.
- hex: 0xE000001A / decimal: -536870886- Updater was called with /silent, /silentall or /silentcritical command line options and according with frequency check interval, time until next update check was not elapsed.
- hex: 0xE0000028 / decimal : -536870872 - Updater was called with /justcheck and updates were found but are outside the license maintenance plan.
Updater specific error codes
- PATH_EXPAND_ERROR (hex: 0xE0000001 / decimal: -536870911) - Unable to expand a dynamic path.
- CONFIG_FILE_NOT_FOUND hex: (0xE0000002 / decimal: -536870910) - Unable to find the Updater configuration file.
- UNDEFINED_CONFIG_FILE_FORMAT (hex: 0xE0000003 / decimal: -536870909) - The updates configuration file format is invalid.
- UNDEFINED_FILE_VERSION (hex: 0xE0000004 / decimal: -536870908) - The Updater is unable to extract a file version.
- UNABLE_TO_SAVE_FILE (hex: 0xE0000005 / decimal: -536870907) - The Updater is unable to save a file, so make sure that the current user has write permissions in the save location. Try using the default path for updates by setting the "Download updates in this folder" field to [CommonAppDataFolder][Manufacturer][ProductName]\updates\ if the issue persists.
- INVALID_COMMAND_LINE (hex: 0xE0000006 / decimal: -536870906) - The command line is not recognized.
- INVALID_CLIENT_CONFIG (hex: 0xE0000007 / decimal: -536870905) - The Updater configuration file is invalid. It is required that certain entries must not be empty.
- INVALID_SERVER_CONFIG (hex: 0xE000000E / decimal: -536870898) - The signature of the updates configuration file is missing or is invalid.
- ERROR_INVALID_UPDATE_ENTRY (hex: 0xE0000014 / decimal: -536870892) - The updates configuration file is invalid. It is required that certain entries must not be empty
- ERROR_URL_NOT_FOUND (hex:0xE0000018 / decimal: -536870888) - The updates configuration file or an update file may be missing from the web server.
- ERROR_ALREADY_RUNNING (hex: 0xE0000027 / decimal: -536870873) - An instance of the Updater is already running.
- ERROR_LICENSE_CHECK_INSTALL_DENY (hex : 0xE0000029 / decimal: -536870871) - This error code is returned when updates install is not allowed by the license check script.
- ERROR_CHECK_FREQ_NOT_ELAPSED (hex : 0xE000001A / decimal: -536870886) - This error code is returned when calling updater with /justcheck and check frequency has not passed.
The above decimal values are in signed 2's complement form. This is the form used in the
log files.
Windows error codes
- Check the Windows SDK documentation to see error description.
Topics
- Updater Diagram
The diagram and steps of how the updater works. - License Check
Updater license check option. - Updates Configuration File
A presentation of the structure of the server updates configuration file.