Getting Packages

The process of retrieving an update from a network resource is controlled by the Update Controller.  The Update Controller is a component placed in your application.  The Update Controller contains three properties that determine how updates are retrieved.

 

Update Location

The network URI that identifies where to look for updates.  For all AppLife Cloud applications, the update location should be https://www.applifeupdate.com.

 

ApplicationID

Every application has a unique guid identifier.  The update controller ApplicationID will match the application If of your AppLife Cloud application.

 

Version

The Version property identifies the version of the software requesting an update.  Versions are of the form <Major>.<Minor>.<Build>.<Revision>.  When updates are published, they can be made available only for specific previous versions, allowing for a great deal of flexibility in software update package management.

 

When an update check is performed, the Update Controller looks for updates at the specified Update Location that targets the version of the client  If there is an update available, information about the update can be displayed to the user.  The update can also be downloaded and applied.

 

Versioning

In order to determine the availability of an update, the current software version must be known.  AppLife Update supports two mechanisms for determining the current software version. You can use either the Version property of the Update Controller, or the assembly version of the host executable.

Update Controller Version Property

If you use the Version property of the update controller, you can set the version property programmatically.  This version number does not need to match the assembly number of the host application.  This versioning scheme is commonly used to enable updating without being required to re-build the application assembly being updated.  It is also used when a sub-component of an application is being updated separately from the main application.  The UseHostAssemblyVersion property must be set to false in order to use this versioning technique.

Host Assembly Version

The current client version can be determined by reading the .Net Assembly Version of the host application.  This value is set by the .Net framework [assembly: AssemblyVersion] attribute. To use the host assembly version, set the Update Controller UseHostAssemblyVersion property to true.  When using the host assembly version, the Update Controller Version property is ignored.  

 

Synchronizing the Update package version with a file

To automatically set the update version while building new updates, you can link the update version of newly created update packages to a file on your build system.  When linked, the update version of new updates is automatically assigned to the assembly version or file version of the designated local file.

 

Check for Update

Methods on the Update Controller are used to Check for Update.  If there is an update available, the information about that update is presented.

Intervening during a Check for Updates

Through the UpdateFound event of the Update Controller, implementers can intervene when an update is discovered.  This might be necessary to check licensing or validate a specific client’s eligibility to receive an update.  From within this event handler, an implementer can allow the update, cancel the update, or even choose from a list of the possible earlier updates for the specific target being update

Custom Data

For each update, a publisher can set a Custom Data text property.  This property is available to you during a Check for Update operation and can be used for special custom processing or decision making.  Kinetic Jump does not use this property for any actions and you can freely use it to customize your update discovery process.

Downloading

When an update is found to be available, the update package is downloaded and placed into a temp folder.  As the file is being downloaded progress indication is provided to the user.  A download can be canceled by the user.

Cached Downloads

An update package is cached as it is being downloaded.  When the download is complete, it is available to be applied.  If an update was previously downloaded and cached without being applied, the update can be applied without asking the Update Controller to download the update package again.  From the Update Controller’s CurrentUpdate property, an integrator can identify whether the current update is already downloaded by referring to the IsDownloaded property.

Resuming a Failed Download

Downloaded update packages are cached to disk during the download process.  If your network connection is lost during an update download, the next download attempt will resume from where the previous download failed.  If an update download was completed, but not applied, the update package will be persisted and ready for the next update attempt.

 

To specify a preferred folder to download update packages, you can set the PreferredDownloadPath property of the Update Controller prior to downloading the update.  You must ensure that the designated folder exists and that the user performing the update has permissions to write to the preferred directory.

Download Verification

Upon successful download of a discovered update, the downloaded file is verified to be intact and that it came from the same publisher that supplied the application being updated.  This is accomplished using the RSA Crypto Service Provider Sign Data functionality.  When a new application is created, an RSA public-private key pair is created.  The private key is used to sign the update package after it is built.  The public key is placed in the PublicKey property of the Update Controller.

When a new update package is created, the resulting file is signed using the RSA Crypto Provider and the private key of the update project.  The signature of the package is retrieved with the update package.

When the hosted application downloads the update package, the signature and public key are used to verify that the downloaded file has not been changed, and that it came from a source that had the proper private key.  If any changes were made to the file, or if the update package had been created without the appropriate private key, the verification will fail and the update package is discarded.

Note:  This verification process assumes the sanctity of the private key.  If a private key is compromised, AppLife Update would not be able ensure the update package file originated with the original software publisher.

Proxy Servers

Many networks today use proxy servers to control internet access.  On these networks, a client application looking for the Uri identified by the UpdateLocation property of the Update Controller might have to navigate first to a proxy server.  The application must know the network location of the proxy server for this to occur.  The AppLife Update Controller supports automatic proxy detection as well as manual proxy settings.

By default, Automatic Proxy detection is enabled.  To set manual proxy information, properties must be set on the Update Controller.  A user interface to allow a user to interact with these settings, and a persistence mechanism are not provided by AppLife Update.  Implementers needing this functionality must provide this within the hosting application.

 

Update Controller Proxy Properties

AutoDetectProxy (true by default)

Proxy Address

Proxy Domain

ProxyUseDefaultCredentials

ProxyUserName

ProxyPassword

Proxy Domain

 

BypassProxyOnLocal

Automatic Update Chaining

Updates chains are made when the current version must first apply one or more updates before the highest available update can be applied.  This commonly occurs when dated application installers are used to install your application, or when your application is infrequently used.

The default behavior of AppLife Update would result in the intermediate update versions being discovered and applied individually.  You can enable automatic chaining.  When automatic chaining is enabled, all available updates are downloaded in a single process, and each update is sequentially applied before your application is restarted as the highest available version.

To enable automatic chaining, set the EnableAutoChaining property of the Update Controller in your application to true.

Non-Chainable Updates

If you publish an update that would not participate properly within a chain of updates, you can designate that update as non-chainable.  An update that requires the operating system to restart, or that might rely on activity that your application performs as it is restarted are examples of non-chainable updates.  To designate an update as non-chainable, clear the Allow chaining from this update checkbox as your update is created.  This value can be modified after the update is built by managing published updates.

Localized Update Process

The AppLife Update Controller contains built-in forms that allow an implementer to quickly implement a complete update process.  This includes a form to check for updates, a form to download an update, and an error status form.  The Update Interactive method of the Update Controller uses these forms.  You can also use each of the forms individually.

 

The built-in update forms are localized to the following cultures:

English (en-us) – default

•Chinese – Traditional (zh-CHT)

•French (fr)

•German (de)

•Italian (it)

•Japanese (ja)

•Spanish (es)

 

When AppLife Update enabled applications utilize the built-in user interface forms, the forms are localized for clients with these Windows versions.

 

Implementers that do not desire these localizations can remove the culture specific folders containing the localized resources from their application directory.