hcUpdateFramework - The Client Side

The hcUpdateFramework consists of 5 parts:

  1. ClientUpdateService
  2. Launcher
  3. Win/Register
  4. AutoUpdateServer
  5. Update Manager
The first 3 of which reside on the client machine.  In this article I will discuss this half of the framework.

1. ClientUpdateService

The ClientUpdateService is a Windows NT Service that runs under the local system account and is responsible for downloading updates from the AutoUpdateServer to the client machine. All update processing occurs in subfolders under the application installation folder which is typically C:\Program Files\{CompanyName}\{ProgramName}. The update folder structure consists of a subfolder called oddly enough; Updates which has 3 subfolders; Pending, Applied and Backup.  Please note that the initial implementation assumed Administrator rights to the installation folder.  For that reason, it may be necessary to install the application into a user folder (ie: C:\Users\<UserName>\AppData\Local\) if the user is running with Standard User permissions.

The ClientUpdateService polls the AutoUpdateServer at a predetermined interval (defaults to 15 minutes) which is specified in AutoUpdate.ini. A default INI file is created the first time the service is started, if one does not exist.

The INI file specifies the URI of the AutoUpdateServer, in addition to the polling interval.  The same INI file is used for all client side applications, and has the following settings:

[Shared]
UpdateRootDir=C:\Users\<UserName>\AppData\Local\MyCompany\MyApp
AppDir=C:\Users\<UserName>\AppData\Local\MyCompany\MyApp
UpdateServiceURI=http://www.myserver.com:8080/soap/IUpdateService
InstallationGUID=3B72F928-4B46-4098-942C-5309CC38ACF4

[Launcher]
AppToLaunch=MyApp.EXE

[Service]
LogAllMessages=1
SleepTimeInMinutes=15

The ClientUpdateService sends the current application manifest to the AutoUpdateServer as part of the IUpdateService.GetUpdate request. If an update is available, the AutoUpdateServer provides the update components with a new manifest as part of the response. The ClientUpdateService saves the new manifest, and all files in the response into a new Updates\Pending subdirectory named for the UpdateVersion. The service then tells the AutoUpdateServer that it has successfully received the update by calling the IUpdateService.UpdateReceived method.

This method passes the ApplicationGUID, LocationGUID, and UpdateVersion to the server. Afterwards the service sleeps for the specified interval before checking for another update. The ClientUpdateService will never download the same update more than once, because the AutoUpdateServer knows it has already received the update.

The ClientUpdateService has the ability to apply the updates, but normally user interaction is desired.

2. Launcher

The Launcher is a Win32 client application that is responsible for actually applying any downloaded updates, and providing the user with appropriate feedback. The Launcher can be renamed so it will replace the current application if it has already been deployed, and act as an intermediate EXE ensuring all existing shortcuts still function. It creates a default INI file the first time the program is started, if one does not exist. The INI file specifies the program it is to launch if no update is present, or after the update(s) have been applied, the application install directory, where to look for updates, and the URI of the AutoUpdateServer.

Although the functionality has not been tested recently, the Launcher is capable of applying multiple updates at once. It should be verified that it applies multiple updates in the correct order before relying on this functionality. On startup, the Launcher reads all subdirectories that appear under Updates\Pending. It then applies the update by loading the manifest, backing up each file into a subdirectory it creates under Updates\Backup\X.X.X.X (where the Xs represent the UpdateVersion), and copying each file in the manifest into the application install directory. If the manifest indicates that the file is a patch file, the patch file will first be used to create a file with the extension .NEW. The patched file will then be used to replace the version in the application install directory.

Errors are trapped along the way, and if any error occurs, the user is informed that the update failed and application may be unusable. No attempt is made to rollback the update. It is left for manual intervention in part to ensure tech support discovers why the update process failed, and because any automated rollback attempt is just as likely to fail. A complete copy of the previous version of all updated files can be found in Updates\Backup\X.X.X.X. Restoring users to a running version of application should be as simple as copying these files back into the installation folder, provided no database updates have occurred that would prevent the backup version from running.

If an update is successfully applied, the Launcher informs the AutoUpdateServer by way of the IUpdateService.UpdateApplied method. This method passes the ApplicationGUID, LocationGUID, UpdateVersion, UpdateResult, and UpdateLog to the server which records the information for viewing in the Deployment Manager.

3. Win/Register

There is actually a Console and VCL Windows utility which are a relatively recent addition the framework.  This utility is meant to be bundled and called as part of an initial install. It calls the IUpdateServer.RegisterInstall method with the ApplicationGUID.  Each application to be deployed is identified by a unique GUID.  This method returns an InstallationGUID which is saved in the application manifest for identifying the installation to the UpdateServer for future updates.

Since this article is getting a little long, in my next post I will cover the server side of the framework.

Leave a Reply