How to Create Update Program for Your App

To start creating an update program for your application, download Actual Updater and install it.

The Actual Updater package contains only two files: Updater.exe and Config.exe .

Updater.exe is the main update program which is used for checking for updates:

Updater.exe

Updater.exe uses the file "Updater.ini" (or "Uninstall.ini" in case you use the updater within Actual Installer) which contains information about your program: Name, Version, URL of Update Information File, and other.

Note: If you use Actual Updater with Actual Installer, please read this article.

These two files (Updater.exe and Updater.ini) must be located next to the main executable file of your app:

Explorer

To create "Updater.ini" and copy these two files into your app's folder use "Actual Updater Configuration Tool" (file Config.exe):

Actual Update Configuration Tool

Enter your Product Name, and select Main Executable file. If your app doesn't have it, just select any file from the folder where your application is located. In this folder will be created the update files.

In order to check for updates, Updater.exe should know the currently installed version of the application. There a few methods how to get this version:

What is GUID?
Product GUID is a reference number used as an identifier of your product.
Example: {FCB1CDDE-F768-4D43-B1A1-BC019502DBC5} is for Actual Updater
Most installers generate a unique product GUID for every application and write it to Registry during installation. Here is how to get it from some installers:
- Inno Setup: open script file and look for "AppId="
- NSIS: open script file and look for "!define MUI_PRODUCT"

Then select preferred options for the updater, and specify URL of Update Information File.

Update Information File - is a plain text file (e.g. update.txt) that contains the information about new version: new version number, link to download this version, and release notes (optional). Read more here.

You can create this file manually or by using "Actual Updater Configuration Tool". This file should be uploaded to your web server, so Updater.exe can access it. Example of update.txt file:
http://www.actualupdater.com/update.txt

Every time when you release a new version of your program, you should also update this file on your server.

After that, click the "Create Updater.ini" button. The Config Tool will copy the Updater.exe and Updater.ini files to the folder of the main executable file.

How Does It Work?

When Updater.exe is launched (as auto-check for updates, as "Check for Updates" shortcut from "Start Menu \ You App" or from your app menu "Help \ Check for Updates"), Updater.exe does the following:
1. Reads the program info from Updater.ini and extracts the currently installed version of program (from Regsitry, Main Executable, or Updater.ini);
2. Downloads the Update Information File (update.txt) from specified URL;
3. Compares new version number and currently installed version number of the program;
4. Prompts to download if it is newer.


update what's new

Options

Use Product Name as Updater Title - Instead of the text "Actual Updater" in the dialog / message titles, will be used your product name.

Allow User to Change Update Options - The user can change Update Options: turn on or off the automatic update function, allow silent updating, change the update frequency, enable or disable the feature Check for Updates on App Launch.

Automatically Check for Updates - Select when the updater checks for updates: on Windows startup, Once a Day, Once a Week, or Once a Month. When selecting "On Windows startup", the updater will be launched when Windows starts, is performed via Windows Registry (Run section). Other options are performed via Task Scheduler. Default time of running Updater.exe is 09:00. You can change this time via Updater Parameters. The task is created with the "RunLevel" option set to "HighestAvailable" - no UAC dialog will be shown; and the option "Run task as soon as possible after a scheduled start is missed" enabled.

Note: to let the user select the desired update frequency, launch Updater.exe with a parameter /O (this will open the Updater Options dialog, the option "Allow User to Change Update Options" must be enabled).

Use Smart Notification - If the user declines the new version update notification twice, there are several options available: the update program prompts the user to not being notified about this version; suggest to change the update frequency; or turn off the automatic update feature.

Update Method

The following methods are available to perform updating:

The update method can be changed using the update parameters (see below).

Add Parameters to New Version URL - Add additional parameters to the link to download new version. You can also use the function GETREGVAl[] to extract a value from Registry. Example:
?x=GETREGVAL[HKEY_CURRENT_USER\Software\MyCompany\Value]
So, if the new version link is, e.g. http://www.site.com/download.html , then this function add a value from Registry to the link . Will be: http://www.site.com/download.html?x=SOMEVALUE

Updater Parameters

Specify additional parameters in this field. Parameters are not case sensitive and can be separated by a space. With parameters you can change the Update Options. Some parameters can be used in the Update Info File, so you can change the initial settings. For example, if the updater was configured to use the Update Method "Open Link in Browser", you can change it to "Download Setup and Run" by adding -method1 to the Update Info File: Section [Update], Key "Parameters".
Parameters for Update Method:
-method0 - Open Link in Browser
-method1 - Download Setup and Run
-method2 - Download Main Executable only
-method3 - Download ZIP and Unpack

Check if Main Executable is running:
After the user confirms installation of the update, the updater will check whether the main executable file of the app is running, and prompt the user to close it. The check is not performed if the update method is "Open Link In Browser" or "Download Setup and Run". To allow the check if method is "Download Setup and Run", add parameter -CheckMainExeIfRunSetup.
If the option "Install Updates Silently" is enabled, then the updater will wait for the main executable file to close and then continue updating in silent mode.
To not check if Main Executable is running, add parameter -NoCheckMainExe
To force close the app (without prompting the user to close it), add parameter -ForceClose
To send the WM_CLOSE message to the app (without prompting the user to close it by the updater), add parameter -CloseMainExeNoMsg (the update will be canceled, if the main exe is still running after 10 seconds. To wait indefinitely, add -WaitInfinite ).
Beta feature: To send a custom message (wParam=1124 and lParam=100) to the app, add parameter -CloseMainExeSendMsg

-AllowChangeOptions - Same as the option "Allow users to change the updater options".
-AllowSilentUpdate - add this to allow the user to enable or disable the silent mode for the auto updates. Same as the option "Install updates silently"
-NoPromptAutoUpdate - when checking for updates with argument /A, and there is no update available, the Updater prompts the user to use the Auto update feature, if available. Add this parameter to disable this feature.
-ParamURL - if Update Parameters are specified in the "Update Info File", then only these parameters take effect (parameters from Updater.ini are ignored)
-ForceUpdate - Force update if a new version available. This will skip the update available message, and start downloading the new version. Then it will update the program in accordance with the specified Update Method.
-noSuccessUpdateMsg - Do not inform about successfull update
-NotifyBrowser - Show a message "The download link will be opened in your browser." when using the update method - "Open Link In Browser"
-noMsgBackgroundProcess - Do not show the message "The process will start in the background." before downloading files using the Updater (Downloader.exe is not used)
-dadmin - launch Downloader.exe as admin
-dparam[] - pass additional parameters to Downloader.exe . It's possible to pass parameters to the file that is downloaded (add /X and specify parameters for the file). /F - download multiple files. More info here.
-usefileversion - When using an option "Main Executable file" in "Get Currently Installed Version" will be used File Version instead of Product Version.
-envvar - replaces Environment Variables in the New Version Download Link.
-unknownlevel - add it if you don't know how your app will be installed - for "All Users" or "Current User only". Depending the install level, administrator privileges may be required for updating.
-taskparam[params] - Sets parameters for Task Scheduler, e.g. change the default time for running the task to 10:00: -taskparam[/ST 10:00]
-notaskwhenavailable - add this to remove the option "Run task as soon as possible after a scheduled start is missed" for Task Scheduler.

-optioncolor - Set the color of the Options link to Blue
-longbutton - Make wider the "Check for Updates" button (in case it does not fit the button size in another language)
-SimpleDialog - Use Simple Dialog box to inform about new version. Example of New Dialog
-noTopMost (deprecated) - By default, the update messages appear at the top level. Add this parameter, to not use it
-CRC32[value] (for example -CRC32[12345678]) - ensure the file is not damaged and downloaded completely. Otherwise, show error (exit code 9) - "CRC32 check failed: the file may not have been fully downloaded"
-noCheckResponce - do not check server response code
-IgnoreError - Show "no updates available" instead of connection errors
-SilentParam[] - specify a parameter to use the silent mode for installation
-noPromptOpenIfUpdated - do not prompt to open the app after a successful update
-ForceElevate - always elevate the update process
-DestExe - for the destination file use AppName.exe
-DestZip - for the destination file use AppName.zip
-SimpleVersioning - do not use Semantic versioning
-noParseVer - do not replace characters "," and "-" with "." in version string
-ZipUpdaterDir - for Update Method "Download ZIP and Unpack" - for destination use the Updater.exe folder (default is the main exe folder)
-ZipParentDir - for Update Method "Download ZIP and Unpack" - for destination use the parent folder
-RunSetupAdmin - for Update Method "Download Setup and Run" - run the file as administrator

-NoCheckAttr - by default, before updating, the program checks the main exe attribute, and if it is "Read Only", then the program tries to change it to "Normal". Add this parameter to not perform this action.
-MsgInSilentUpdate - show error messages when using the feature "Install updates silently"
-NoSilentZipForceClose - by default, when using the feature "Install updates silently" and Update Method "Download ZIP and Unpack", running exe files are closed automatically. Add this parameter to not perform this action.
-RunCmdAdmin - run commands (before or after update) as administrator
-RunCmdNoWait - do not wait for the commands (before or after the update) to complete
-RunCMDAfterSuccessUpdate - command to run after update is executed even if the update fails. to execute only on successful update, add this parameter

Parameters for the New Dialog box (with Release Notes / What's New):
-LargeDialog1 - set window size to 400 x 390 px.
-LargeDialog2 - set window size to 500 x 600 px.
-LargeDialog3 - set window size to 600 x 600 px.
-ShowCurVer - Show text "Currently you have version X" in the Update Available dialog box
-HideUpdateLater - Hide the checkbox "Update after I exit the app"
-HideWhatsNew - Hide text "What's New" in the Update Available dialog box
-ShowLast - Show Release Notes (What's New) for the latest version only
-noBrackets - Show versions without square brackets
-NoLogo - Hide the information logo
-IconUpd - Use the Actual Updater Icon in the New Version available dialog
-IconDef - Use the custom icon (add file "Updater.ico" next to the Updater.exe file) in the Update Available dialog box
-WhiteWhatsNew - Use white background for the What's New section
-NoBorderWhatsNew - No border lines for the What's New section
-noBeep - Do not play a sound in the "New version available" dialog box
-NoCaption - hide title bar
-Font[] - change font. Default is Verdana. Example: -Font[Tahoma]
-FontSize[] - change font size. Default is 8. Example: -FontSize[10]
-FontColor[] - change font color (integer value, example -FontColor[15790320], you can convert RGB or HTML color code in Actual Installer program - Interface - Template Editor)
-Font2[] - change font for the Release Notes (What's New) section. Default is Verdana. Example: -Font2[Tahoma]
-FontSize2[] - change font size for the Release Notes (What's New) section. Default is 8. Example: -FontSize2[10]
-FontColor2[] - change font color for the Release Notes (What's New) section.
-Color[] - background color for the New Dialog box
-Color2[] - background color the What's New section
-HTML - ability to use HTML tags for the What's New text
-DarkTheme - use the dark theme
-SysTheme - use the system theme

Parameters for the feature Check for Updates on App Launch. This feature is available only when using the updater within Actual Installer.
-LWait - The checking for updates will be performed after the main executable file is closed
-LaunchAppAfterCheck - Main executable file will be launched after checking for updates
-Ladmin - Launch the main executable file as administrator
-Lparam[] - Pass command-line parameters to the main executable file, for example: -lparam[/S]
-SetCurrentDir - Set the current directory to the Updater.exe directory


Command Line Parameters

When Updater.exe is launched with no parameters, it displays the Product Details dialog. To check for updates, the user should click the "Check for Updates" button.

Updater.exe supports the following command-line parameters (arguments):

/S - Check for updates in the silent mode. A message appears only if an update is available. No other messages appear (including connection error). This argument is recommended to use when you want to automatically check for updates when your application starts. To make it, add a code to launch Updater.exe with the /S argument into the startup section of your application (see examples below).

/A - Automatically check for updates when the updater starts without displaying the Product Details dialog. Standard messages appear: the update is available, no updates, or errors. Use this argument when the user wants to check for updates from your program, for example, using the menu "Help \ Check for Updates".
Example: Updater.exe /A

/Q - Quiet mode (super silent), no messages, only exit codes (see below). This simply checks whether an update is available or not.

The following arguments are supported by the Pro version only:

/F - Force update if available. Same as the parameter -ForceUpdate . This will skip the update available message, and start downloading the new version. Then it will update the program in accordance with the specified Update Method. If the option "Use Downloader" is selected, then the following arguments can be used with /F - /Y (until v5.3 used /S) - silently download the new version, then launch it in the normal mode; /Z - silently download the new version, then launch it in the silent mode (/S argument is added to the setup program. To use other argument, specify it in parameter -SilentParam[]).

/O - Open the Options dialog. If specifid "/O i", where i - is a number, then also sets the default item for the option "Automatically Check for Updates": i=0 sets "on Windows startup", i=1 - Every Day, i=2 - Every Week, i=3 - Every Month

/Init - This activates the auto update feature (via Registry or Task Scheduler) when using the Automatically check for updates feature. The update options (method, frequency) are used from the Configuration file (Updater.ini). Add a command to execute Updater.exe /Init at the end of your app Installation, or execute it once from your app.

/Remove - This deactivates (removes) the auto-update settings (Registry Keys or Task from Task Scheduler). Add a command to execute Updater.exe /Remove at the beginning of your app Uninstallation.

Note: If you use Actual Installer, you don't need to execute commands: /Init and /Remove. The setup program will make it automatically.


/CHECKAUTORUN - Checks if the option "Automatically Check for Updates on Windows startup" is enabled (return code is 10) or disabled (return code is 11). Cannot be used with argument /S

/AUTORUNON i - Turns on the option "Automatically Check for Updates" - for i=0 uses "on Windows startup", i=1 - Every Day, i=2 - Every Week, i=3 - Every Month

/AUTORUNOFF i - Turns off the option "Automatically Check for Updates" - for i=0 uses "on Windows startup", i=1 - Every Day, i=2 - Every Week, i=3 - Every Month

/AUTORUNAPP i - if i=0, then turns off the feature "Automatically Check for Updates on App Launch"; if i=1, turns it on.

If you want to show a custom message when an update is available, then make the following: 1: launch Updater.exe with the /Q argument and wait for the updater to finish (use the Wait flag for the launch function); 2: check its exit code, and if it is 5 (which means the update if available) ask the user to install the update; 3: if the user confirms to install the new version, launch Updater.exe with the /F argumenth.

Here are some code examples on how to launch Updater.exe with the argument "/S":

C++ Code:

#include "Shlwapi.h"

ShellExecute(NULL, NULL, "Updater.exe", "/S", NULL, SW_SHOWNORMAL);

Delphi Code:

//don't forget to include ShellAPI into USES section

ShellExecute(0, 'open', 'Updater.exe', '/S', nil, SW_SHOWNORMAL);

VB.NET: C#:

Process.Start("Updater.exe", "/S");

VB.NET: C#:

Dim pHelp As New ProcessStartInfo
pHelp.FileName = "Updater.exe"
pHelp.Arguments = "/S"
pHelp.UseShellExecute = True
pHelp.WindowStyle = ProcessWindowStyle.Normal
Dim proc As Process = Process.Start(pHelp)

C#:

string command = "Updater.exe";
string arg = "/S";
ProcessStartInfo start = new ProcessStartInfo(command, arg);
Process.Start(start);

C++:

Process::Start("Updater.exe", "/S");

Exit Codes

Updater.exe returns the following exit codes:

0 - No updates available

1 - Error: Configuration file not found (Updater.ini or Uninstall.ini)

2 - Error: Configuration file does not contain Product Name or URL of Update Info File

3 - Error: Unable to connect to the update server (unable to download Update Info File)

4 - Error: Incorrect Update Info File. Make sure that Update Info File is a plain text file, not HTML, RTF, or other type

5 - Update is available

6 - Canceled by user

7 - Error: Cannot extract files from ZIP

8 - Error: Cannot update (download failed or access denied)

9 - Error: CRC32 check failed: "the file may not have been fully downloaded"


Advanced features are available in Actual Updater Pro.