Click or drag to resize
UpdateController Class
The UpdateController forms the core of the AppLife Update system in the application that will be updated. It enables the application to communicate with an update server and download, validate, and apply updates.
Inheritance Hierarchy

Namespace: Kjs.AppLife.Update.Controller
Assembly: Kjs.AppLife.Update.Controller (in Kjs.AppLife.Update.Controller.dll) Version: 5.1.0.9 (5.1.0.9)
Syntax
public class UpdateController : Component

The UpdateController type exposes the following members.

Constructors
  NameDescription
Public methodUpdateController
Initializes a new instance of the UpdateController class.
Public methodUpdateController(IContainer)
Initializes a new instance of the UpdateController class with the specified container.
Top
Methods
  NameDescription
Public methodApplyUpdate
Applies the downloaded update represented by CurrentUpdate. If the update is applied, the application will shut down. If EnableAutoChaining is , applies all chained updates in sequence.
Public methodApplyUpdate(ApplyUpdateOptions)
Applies the downloaded update represented by CurrentUpdate. If the update is applied, the application will shut down. If EnableAutoChaining is , applies all chained updates in sequence.
Public methodApplyUpdate(ApplyUpdateOptions, IDictionary)
Applies the downloaded update represented by CurrentUpdate. If the update is applied, the application will shut down. If EnableAutoChaining is , applies all chained updates in sequence.
Public methodCancelAsync
Public methodCheckForUpdate
Searches for an available update. If an update is found, its information can be retrieved from CurrentUpdate.
Public methodCheckForUpdateAsync
Searches for an available update. If an update is found, its information can be retrieved from CurrentUpdate. This method does not block the calling thread.
Public methodCreateObjRef
Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
(Inherited from MarshalByRefObject.)
Public methodDispose
Releases all resources used by the Component.
(Inherited from Component.)
Protected methodDispose(Boolean)
Clean up any resources being used.
(Overrides ComponentDispose(Boolean).)
Public methodDownloadUpdate
Downloads the update represented by CurrentUpdate, or, if EnableAutoChaining is , every update in the update chain.
Public methodDownloadUpdateAsync
Downloads the update represented by CurrentUpdate, or, if EnableAutoChaining is , every update in the update chain. This method does not block the calling thread.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodFinalize
Releases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection.
(Inherited from Component.)
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetLifetimeService
Retrieves the current lifetime service object that controls the lifetime policy for this instance.
(Inherited from MarshalByRefObject.)
Protected methodGetService
Returns an object that represents a service provided by the Component or by its Container.
(Inherited from Component.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodGetUpdateChain
Gets an array of UpdateInformation corresponding to all updates in the current chain.
Public methodStatic memberGetUpdateHistory
Gets a collection of LoggedUpdate objects representing past updates applied for the specified application ID. The information is retrieved by reading update log files.
Public methodInitializeLifetimeService
Obtains a lifetime service object to control the lifetime policy for this instance.
(Inherited from MarshalByRefObject.)
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Protected methodMemberwiseClone(Boolean)
Creates a shallow copy of the current MarshalByRefObject object.
(Inherited from MarshalByRefObject.)
Protected methodOnCheckForUpdateCompleted
Raises the CheckForUpdateCompleted event.
Protected methodOnDownloadUpdateCompleted
Raises the DownloadUpdateCompleted event.
Protected methodOnDownloadUpdateProgressChanged
Raises the DownloadUpdateProgressChanged event.
Protected methodOnShutdownRequested
Raises the ShutdownRequested event.
Protected methodOnUpdateDialogShowing
Raises the UpdateDialogShowing event.
Protected methodOnUpdateFound
Raises the UpdateFound event.
Protected methodOnUpdateStarting
Raises the UpdateStarting event.
Public methodOverrideAssemblyLocation
Specifies a different assembly location for this application in order to allow the controller to apply updates on behalf of another application.
Public methodOverrideHostProcessInfo Obsolete.
Overrides the host process information to allow the controller to apply updates on behalf of another application
Public methodReadLastUpdateInformation
Gets information about the last update applied for this application ID.
Public methodSaveUpdatesToLocal
Saves the current update and any chainable updates that have been downloaded to a local folder.
Public methodShowCheckForUpdateDialog
Searches for an available update while showing a modal dialog to the user.
Public methodShowCheckForUpdateDialog(IWin32Window)
Searches for an available update while showing a modal dialog to the user in front of the specified object.
Public methodShowCheckForUpdateDialog(ErrorDisplayLevel)
Searches for an available update while showing a modal dialog to the user that can show the specified amount of error information.
Public methodShowCheckForUpdateDialog(IWin32Window, ErrorDisplayLevel)
Searches for an available update while showing a modal dialog to the user that can show the specified amount of error information in front of the specified object.
Public methodShowDownloadUpdateDialog
Downloads the update represented by CurrentUpdate while showing a modal dialog to the user.
Public methodShowDownloadUpdateDialog(IWin32Window)
Downloads the update represented by CurrentUpdate while showing a modal dialog to the user in front of the specified object.
Public methodShowDownloadUpdateDialog(ErrorDisplayLevel)
Downloads the update represented by CurrentUpdate while showing a modal dialog to the user that can show the specified amount of error information.
Public methodShowDownloadUpdateDialog(IWin32Window, ErrorDisplayLevel)
Downloads the update represented by CurrentUpdate while showing a modal dialog to the user that can show the specified amount of error information in front of the specified object.
Public methodToString
Returns a String containing the name of the Component, if any. This method should not be overridden.
(Inherited from Component.)
Public methodUpdateInteractive
Uses built-in dialogs to walk the user through an entire update process.
Public methodUpdateInteractive(IWin32Window)
Uses built-in dialogs to walk the user through an entire update process. The dialogs will be shown in front of the specified object.
Public methodUpdateInteractive(ApplyUpdateOptions)
Uses built-in dialogs to walk the user through an entire update process. The dialogs will be shown in front of the specified object.
Public methodUpdateInteractive(ErrorDisplayLevel)
Uses built-in dialogs to walk the user through an entire update process, showing the specified amount of information about any error that occurs.
Public methodUpdateInteractive(IWin32Window, ErrorDisplayLevel)
Uses built-in dialogs to walk the user through an entire update process, showing the specified amount of information about any error that occurs. The dialogs will be shown in front of the specified object.
Public methodUpdateInteractive(IWin32Window, ErrorDisplayLevel, ApplyUpdateOptions)
Uses built-in dialogs to walk the user through an entire update process, showing the specified amount of information about any error that occurs. The dialogs will be shown in front of the specified object.
Public methodUpdateInteractive(IWin32Window, ErrorDisplayLevel, ApplyUpdateOptions, IDictionary)
Uses built-in dialogs to walk the user through an entire update process, showing the specified amount of information about any error that occurs. The dialogs will be shown in front of the specified object.
Public methodValidateUpdate
Validates the downloaded update represented by CurrentUpdate, or, if EnableAutoChaining is , every update in the update chain.
Top
Properties
  NameDescription
Public propertyAddCredentialsToAutoDetectProxy
Gets or sets a value that specifies whether the controller will add default network credentials to the application's default web proxy.
Public propertyAllowElevatedPrivileges Obsolete.
Gets or sets a value that specifies whether to allow updates to be applied using a Windows service with administrative privileges. The service must be installed before it can be used to apply an update.
Public propertyAllUpdates
Gets a collection of UpdateInformation objects that represent all updates found from the last update check, or if no update information is available.
Public propertyApplicationId
Gets or sets a Guid that is used to uniquely identify the application that is being updated.
Public propertyAutoCopyCommandLine
Gets or sets a value that indicates whether the command line arguments passed to the application should be automatically passed to it again when it is restarted after an update.
Public propertyAutoDetectProxy
Gets or sets a value that specifies whether the controller will automatically detect proxy settings.
Public propertyAvailableUpdates
Gets a collection of UpdateInformation objects that can be applied to the current Version or if no update information is available or EnableAutoChaining is .
Public propertyBypassProxyOnLocal
Gets or sets a value that specifies whether to bypass using a proxy server for local addresses.
Protected propertyCanRaiseEvents
Gets a value indicating whether the component can raise an event.
(Inherited from Component.)
Public propertyClientAccessKey
Gets or sets a value that can be used as a secondary client identifier. Client keys can be used in an AppLife Update Server whitelist. Like the ClientID, this value is passed to the server with each request.
Public propertyClientId
A client identifier generated based on a unique hardware signature and install location
Public propertyContainer
Gets the IContainer that contains the Component.
(Inherited from Component.)
Public propertyControlledRolloutEnabled
Gets or sets a value that specifies whether controlled rollouts are enabled for updates received by the controller. When controlled rollouts are enabled, clients are updated over the amount of time specified in the ControlledRolloutHours property.
Public propertyControlledRolloutHours
Gets or sets the period of time over which clients will be updated when controlled rollouts are enabled.
Public propertyCurrentUpdate
Gets or sets information about the currently available update, or if no update information has been retrieved. If setting this value, the UpdateInformation must be in the list of updates retured by AllUpdates and EnableAutoChaining must be .
Public propertyCustomHttpHeaders
Gets a collection of custom headers that will be sent with any HTTP request issued by the controller.
Public propertyCustomHttpHeaderValue Obsolete.
Gets or sets a String value that, when specified, is added to the http request header collection under the name 'AppLifeHttpHeader'. The value can be used within a custom http handler on the server to perform server side processing.
Public propertyCustomIpcData
Gets or sets a string that is sent with all communications between controllers.
Protected propertyDesignMode
Gets a value that indicates whether the Component is currently in design mode.
(Inherited from Component.)
Public propertyDisableControllerIpc
Gets or sets a value that indicates whether the controller will communicate with other controllers that share the same ApplicationId.
Public propertyElevationType
Gets or sets a value that specifies the level of elevation used to apply updates. See UpdateElevationType for more information.
Public propertyEnableAutoChaining
Gets or sets a value that indicates whether the UpdateController will find, download and apply all possible updates in sequence, rather than one update at once.
Public propertyEnableOfflineUpdates
Gets or sets a value indicating whether the UpdateController will check for updates using cached data, allowing previously downloaded updates to be applied without network connectivity.
Public propertyEnableTestUpdates
Gets or sets a value that indicates whether to allow updates that are flagged as "test only" to be applied.
Protected propertyEvents
Gets the list of event handlers that are attached to this Component.
(Inherited from Component.)
Public propertyHostAssemblyLocation
Gets the Entry Assembly location. To override the host assembly information use the OverrideHostProcessInfo method.
Public propertyIsBusy
Gets a value indicating whether an asynchronous operation is currently in progress.
Public propertyIsFirstRun
Gets a value indicating that this is the first time an UpdateController has been set to the current ApplicationId since the last successful update for that ID was applied.
Public propertyNoUpdateDisplayHtml
Gets HTML retrieved from the update server that should be shown when no updates are available, or if no update information has been retrieved.
Public propertyNoUpdateDisplayText
Gets text retrieved from the update server that should be shown when no updates are available, or if no update information has been retrieved.
Public propertyPreferredDownloadPath
Gets or sets the directory where downloaded updates will be saved. If this property is not set, updates will be saved in the current user's temp directory.
Public propertyProxyAddress
Gets or sets the address of the proxy server the UpdateController will use when connecting to the update location.
Public propertyProxyDomain
Gets or sets the domain used for authentication on the proxy server.
Public propertyProxyPassword
Gets or sets the password used for authentication on the proxy server.
Public propertyProxyUseDefaultCredentials
Gets or sets a value that specifies whether the UpdateController will use the credentials of the currently logged on user when accessing the proxy server.
Public propertyProxyUserName
Gets or sets the user name used for authentication on the proxy server.
Public propertyPublicKeyToken
Gets or sets the public key token of the strong name key used to create the updates that will be downloaded and applied by the UpdateController. If an update cannot be validated using this key, it will not be applied.
Public propertySite
Gets or sets the ISite of the Component.
(Inherited from Component.)
Public propertyCode exampleUpdateLocation
Gets or sets the network location of the updates for the application. Any UNC, HTTP, or FTP location can be specified.
Public propertyUpdateLocationDomain
Gets or sets a domain user name to use to log in to access the location specified in UpdateLocation.
Public propertyUpdateLocationPassword
Gets or sets a password to use to log in to access the location specified in UpdateLocation.
Public propertyUpdateLocationUserName
Gets or sets a user name to use to log in to access the location specified in UpdateLocation.
Public propertyUseDefaultCredentialsOverHttp
Gets or sets a value that indicates whether to user the current user's credentials when accessing UpdateLocation, when UpdateLocation is an HTTP URI.
Public propertyUseHostAssemblyVersion
Gets or sets a value that specifies whether the controller will use the hosting assembly's version as the value for Version.
Public propertyVersion
Gets or sets the current version number of the application used for update purposes.
Public propertyWebRequestKeepAlive
Gets or sets a Boolean value that sets the KeepAlive property of a web request for an update. The default value is true, and should only be set to false if updates are hosted on a server that does not support the default keep alive behavior.
Top
Events
  NameDescription
Public eventCheckForUpdateCompleted
Occurs when an asynchronous update check operation completes.
Public eventDisposed
Occurs when the component is disposed by a call to the Dispose method.
(Inherited from Component.)
Public eventDownloadUpdateCompleted
Occurs when an asynchronous update download operation completes.
Public eventDownloadUpdateProgressChanged
Occurs during when an asynchronous update download operation successfully transfers some or all of the data.
Public eventShutdownRequested Obsolete.
Occurs when applying an update requires the application to terminate.
Public eventUpdateDialogShowing
Occurs before the built-in update information dialog displays information about the current update available for download.
Public eventUpdateFound
Occurs when one or more updates have been found.
Public eventUpdateStarting
Occurs when an update is about to be applied.
Top
Remarks

To use an UpdateController, you must first initialize it with information about the update server and the application being updated. The UpdateLocation and ApplicationId properties link the controller to an update server, and the PublicKeyToken property allows it to validate updates. These three properties must be set before the controller can be used to download and apply updates.

In order to determine what updates are available, the controller needs to know the application's version. This information is stored in the Version property. If the UseHostAssemblyVersion property is , Version will automatically be set to the version of the current application.

If the controller may be working through a proxy to download updates, you can use the AutoDetectProxy, ProxyAddress, ProxyDomain, ProxyUseDefaultCredentials, ProxyUserName, ProxyPassword, and BypassProxyOnLocal properties to configure proxy settings.

Once the controller is configured, the easiest way to update your application is to use one of the UpdateInteractive methods. These methods use the controller's built-in dialogs to guide the user through the entire update process. Note that since the user might choose to update the application from these methods, the application might shut down before they return. Handle the UpdateStarting event to perform work needed before the application shuts down.

using System;
using System.Windows.Forms;
using Kjs.AppLife.Update.Controller;
class UpdatableForm : Form {
[STAThread]
static void Main() {
Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.Run(new UpdatableForm());
}
private UpdateController mController;
public UpdatableForm() {
Button updateButton = new Button();
updateButton.Text = "Update!";
updateButton.Click += new EventHandler(updateButton_Click);
this.Controls.Add(updateButton);
this.mController = new UpdateController();
//These settings do not represent a real update server.
this.mController.UpdateLocation = "my-update-server/updates";
this.mController.ApplicationId = new Guid("01234567-89AB-CDEF-0123-456789ABCDEF");
this.mController.PublicKeyToken = "<RSAKeyValue><Modulus>25yO48pjp1EWrE/kCAfjtXpX" +
"1q/s1iS0stCFqPSJ0IkftbieP80gBitULM2cdR6kMEde/bZ/zwESOCqo2us6aLnKHam5B3o3g94jYf" +
"jYWC4KE/fm7qDZx0MkVhmwSfqCZXQdouOmfQVe7Uf48Qg/R3x45alcdDHUAYoNVK8Hn88=</Modulu" +
"s><Exponent>AQAB</Exponent></RSAKeyValue>";
}
void updateButton_Click(object sender, EventArgs e) {
this.mController.UpdateInteractive(this);
}
}

The controller can also be used to perform each step of the update process separately. To only contact the update server and find what update (if any) is available, use the ShowCheckForUpdateDialog, CheckForUpdateAsync, or CheckForUpdate methods. Each of these methods fills in the CurrentUpdate and NoUpdateDisplayText properties with information from the update server. To download the update represented by CurrentUpdate, use the ShowDownloadUpdateDialog, DownloadUpdateAsync, or DownloadUpdate methods. Once an update has been successfully downloaded, the IsDownloaded property of CurrentUpdate will be set to . To validate a downloaded update, use the ValidateUpdate method. To apply a downloaded update, use the ApplyUpdate method. Like UpdateInteractive, ApplyUpdate can shut down the application.

When checking for an update, the UpdateController will analyze the updates it finds on the update server and choose the highest update that can be applied to Version. You can handle the UpdateFound event to further filter updates based on custom criteria.

See Also