User's Guide - Chapter 1: The TrueUpdate Model

The TrueUpdate Model

Like any system that involves client-server interaction, updating software is a sophisticated process. It involves advanced technologies and protocols and rules that, without a clear and defined plan, would seem incredibly daunting to employ.

TrueUpdate is specifically designed to make the entire update process as simple to understand and as easy to accomplish as possible. Much of this is due to the unique update model that TrueUpdate employs. TrueUpdate provides the framework that makes it possible--in fact, easy--for you to build an update for your software.

Before you start working with TrueUpdate, however, it is important to understand the way TrueUpdate works.

What Does TrueUpdate Do?

At its simplest, TrueUpdate is an updater of software. It determines whether an update is available, downloads the required files, and then uses them to perform the update.

Anything that falls within that broad definition is possible with TrueUpdate. All of the details are in your control, from the specific methods used to detect the installed version, to the steps that are taken to actually update the software. An update can be as simple as making a subtle change to a registry key, or it can involve downloading and applying multiple patch files from a geographically selected download location.

Most commonly, however, TrueUpdate will be used to perform these basic functions:

          Determining the version that is installed

          Deciding whether an update is available

          Deciding whether an update is required

          Acquiring the appropriate patch file

          Applying the patch to update the installed version

Other Uses for TrueUpdate

The above steps describe the most common use of an updater like TrueUpdate. However, TrueUpdate is an incredibly flexible tool. In addition to handling the countless variations on the update process that are possible, TrueUpdate can be used to perform many other tasks--including some that are completely unrelated to updating software. For example, you could use TrueUpdate as a communications tool, automatically detecting and displaying a new "message of the day" from a central location. Or you could use it as a general development environment, taking advantage of its sophisticated system actions and wizard-like screens to build standalone configuration utilities. The possibilities are indeed limitless.

The TrueUpdate Client

The TrueUpdate Client is the client application that will actually perform the update process. It is generated when you build your TrueUpdate project. This is the "updater" that you will distribute to your users in order to provide the update ability.

In other words, the TrueUpdate Client is the program that does the work of your update. Everything in your TrueUpdate project--from the project settings that you configure, to the server-side scripts that you create--either directly affect how the TrueUpdate Client is built, or serve as instructions that define how it performs the update.

The TrueUpdate Client is a compact, self-contained application, without any external dependencies such as .Net, Java, or any other needlessly complicated technologies. It takes advantage of standard Internet protocols and encryption methods to perform the update process in a robust and secure way.

It’s also designed to be mindful of privacy needs. The TrueUpdate Client doesn’t require any information to be sent to the server at all--everything from the installed version detection to the decision about whether an update is required is handled entirely at the client end. This client-pull method completely avoids the privacy issues that revolve around other methods that require detailed information about the user’s system and installed software to be transmitted to a remote location.

Of course, TrueUpdate can still communicate with a remote location if you need it to; in fact, it has built-in actions to submit information to standard web scripts using both unsecured and secured transfer protocols. However, this functionality is entirely in your control; a TrueUpdate Client will never send anything to a server unless you specifically design it to do so.

The TrueUpdate Client is also designed to keep itself up to date. It does this by automatically downloading any updated versions of its client data or executable files that it finds at the TrueUpdate Server. (The latest versions of these files are included in the server configuration files that are uploaded to each TrueUpdate Server location.)

TrueUpdate Servers

A TrueUpdate Server is any location where the TrueUpdate Client can download the server configuration files that tell it how to perform the update. This can be a standard HTTP server, a standard FTP server, or even a folder on your local area network.

Note that this is completely independent of any specific hardware platform, operating system, or server software. TrueUpdate doesn’t lock you into any proprietary server technology. In fact, it doesn’t require you to run anything on a server at all.

All you need to create a TrueUpdate Server is a place to put your server configuration files where the TrueUpdate Client will be able to get them. "Creating" the server involves nothing more than uploading a handful of files and adding the new location in your TrueUpdate project settings.

For example, if you upload the server configuration files to your company’s web server, and add the location in your project settings, you’ve just created a TrueUpdate Server. Want another TrueUpdate Server for redundancy? Upload the files to another web server, or to an FTP server, or to a folder on your network. You could even copy the files to a USB key and pass it around the office--anywhere that your TrueUpdate Client can access the files is a valid TrueUpdate Server location.

Because TrueUpdate Servers use standard Internet protocols, you are free to take advantage of the full range of server technologies available to you. Whether your server is an old PC in your basement, or a fully load-balanced and distributed server farm in a high-security building, the choice of where and how to host your files is entirely up to you.

Note: For more information on TrueUpdate Servers, please see Chapter 6.

Server Configuration Files

Server configuration files provide the server-side component of the update process in TrueUpdate. This handful of files contain all the information the TrueUpdate Client needs in order to keep itself up to date and to perform the actual update of your software.

Specifically, the server configuration files allow each client to:

          Update its client-side data and executable files if newer versions become available

          Determine what version of your software is currently installed

          Determine whether an update is required

          Take the steps required to update the installed software if it is out of date

The server configuration files are generated whenever you build a project. They are completely project-specific--the server configuration files that you build in one project will only work with a TrueUpdate Client generated from that same project. In other words, TrueUpdate Clients and server configuration files from different projects are incompatible.

Note: TrueUpdate Clients are only compatible with server configuration files from the same project.

The Update Process

Here is a description of a typical update process in detail.

1.       The TrueUpdate Client welcomes the user to the update by displaying an appropriate screen or popup dialog box.

2.       The client then attempts to download the server configuration files from the first server in its list of TrueUpdate Servers. (By default, it will attempt to connect to each server location in the list until it succeeds.)

3.       Once it connects to a server location, it checks to see if the location contains a newer version of the client data or client executable file. If it does, the client downloads the appropriate server configuration files (e.g. the .ts2 or .ts3 file, or both), and then restarts in order to use the new version of itself.

4.       Assured that it is up to date, the client next downloads the server script and screens, which are contained in the .ts1 server configuration file.

5.       After loading the server screens into memory, the TrueUpdate Client runs the server script.

6.       The first function of the server script is to determine what version of the target software is currently installed on the user’s system. This version is generally referred to as the installed version.

7.       Once the installed version has been determined, the server script compares it to a target version. The target version represents the desired version of the software--i.e. the version that the script was designed to update the software to.

8.       If the above test determines that the installed version is already current, the server script informs the user that they already have the latest version, and then exits.

9.       If on the other hand the test determines that an update is required, the server script proceeds with the actual update process. While the actual update method will vary from project to project, the most common method involves downloading a single executable patch file and then running that file with appropriate command line options.

10.   If the patch file returns a value that can be used to determine whether it succeeded, the server script will usually check this value and then inform the user of the success or failure of the update.

11.   If the patch file doesn’t return any such information, the server script will either wait for the patch to finish and then inform the user that the update process is complete, or simply exit silently and let the patch continue on its own.


Scripts are a key component of TrueUpdate. In fact, the entire client-server interaction is scripted, and the built-in screens implement their functionality using scripts triggered by various screen events.

This is a very important feature, because it exposes the implementation to you for modification. In other words, the scripted nature of TrueUpdate makes it possible for you to completely control the behavior of your update.

A script is essentially a list of instructions for the TrueUpdate Client to follow.
Each script contains a sequence of commands, called actions, which work together to perform a specific task. A script can contain a single action, or any number of actions. These actions combine to form a series of steps that are performed sequentially, with one action following another. The sequence of actions can either occur in a direct and straightforward manner, or--by taking advantage of control structures like "if" and "while"--can incorporate sophisticated techniques such as decision-making, branching and looping.

Note: Scripts are ultimately just text documents that follow a specific syntax. The actions and control structures in a script are represented by specific keywords, which the TrueUpdate Client interprets as instructions that tell it what to do. You can edit these instructions as easily as you would edit any other text.

Script Tabs: Client vs. Server

Each TrueUpdate project contains two main scripts: a client script, and a server script. In the TrueUpdate development environment, these two scripts are represented by the Client Script tab, and the Server Script tab.

The scripts are divided according to where they are stored. The client script is built into the TrueUpdate Client application, and the server script is stored in one of the server configuration files.

Together, these two scripts implement the client-server interaction and control the entire update process.

The Client Script

The client script’s job is to introduce the user to the update, and download and run the server script.

Downloading the server script is done using the TrueUpdate.GetServerFile action. Since this action involves downloading files, it is usually called from a client screen (e.g. the Download Server Script screen) so that progress can be shown.

Once the server script is downloaded, it can be executed using the TrueUpdate.RunScript action.

The Server Script

The server script’s job is to determine whether an update is required, and then to actually perform the update--either by running a series of actions or by launching a separate installer or patch file.

Because it is downloaded each time your TrueUpdate Client connects to a TrueUpdate Server, you are free to modify the server script at any time--even after the TrueUpdate Client has been distributed.

This separation between the client and the server scripts is an essential feature of TrueUpdate. It allows you to adjust the update process for your software at any time, without any modifications to the client at all. In other words, it allows you to modify your update process without having to redistribute new clients to your users.

Screens: Client vs. Server

Screens are the individual windows that make up any wizard-styled update. When you navigate through an update by clicking the Next and Back buttons, you are navigating from screen to screen.

Note: Each screen has a number of events, with associated scripts that get executed when the corresponding events are triggered. By modifying these scripts you have full control over the functionality of the screens in your project.

Like the client and server scripts, the screens in your project are divided into two main areas. In the TrueUpdate development environment, these areas are represented by two screen panes, which by default are tabbed together in the upper right corner of the program window. There is one screen pane for the client-side screens, and one for the server-side screens.

The Client Screens

When you build your project, the screens on the Client Screens pane are packaged with the TrueUpdate Client and are accessible to the end user without having to download anything from the Internet. These screens cannot be updated without updating the client itself.

The Server Screens

The screens on the Server Screens pane are stored in a server configuration file. These screens are accessible to the end user only after the client has downloaded the server configuration files. Because the screens on the Server Screens pane are downloaded whenever the TrueUpdate Client connects to a TrueUpdate Server, you are free to change them after your client has been distributed.

Updating An Existing Client

The client script and client screens are stored within the client’s data file, which is normally distributed initially with your software.

Generally, it is preferable to write the client script in such a way that it does not need updating after the client has been distributed. If changes are made, the client will need to be restarted in order to update itself.

Of course, there may be an occasion when you need to add actions to your client script or to add another screen after your client has been distributed.

Not to worry; TrueUpdate has been designed to handle such cases. Every time your project is built, three server configuration files are generated. One of these files (the .ts1 file) contains the server scripts and server screens. The other two server configuration files contain the latest versions of your client data file (.ts2) and client executable (.ts3). This allows each client to automatically update itself if you have made changes to the client script and screens.

Here’s how it works: Whenever a TrueUpdate Client connects to a TrueUpdate Server in order to begin the update process, it first checks to see if the .ts2 and .ts3 files on the server are newer than the client’s current data file and executable. If either of the files is newer, the client downloads the new file, replacing the existing file with the new version. Remember that in order to replace either of these files, however, the client needs to restart itself; therefore, if at all possible, it is better to avoid updating the client script and client screens after the client has been distributed to your users.