Design of the Updater Application Block

Updater Application Block - Version 2.0

Microsoft Corporation

March 2005

Summary: The Updater Application Block is designed to provide a simple out-of–the-box experience at the same time it is also designed to be extensible, so you can customize to perform a complex set of tasks after the download process is complete.

The Updater Application Block is designed to provide a simple solution to the problem of keeping smart client applications up to date in enterprise environments. You can use it out-of–the-box to perform the downloading and activation of updates for your applications. However, it is also designed to be extensible, so you can customize the default application block to perform exactly the functionality that your application requires, whether that is using a different type of download technology or performing a complex set of tasks after the download process is complete.

The application block consists of four subsystems, each designed to fulfill a specific role in the application update process. These subsystems are a logical, not physical, separation and they include the following:

• Update management subsystem. The update management subsystem includes the ApplicationUpdaterManager, RegistryManager, and UpdaterTask classes. ApplicationUpdaterManager is a facade into the Updater Application Block. This is a singleton and is responsible for interacting with the ManifestManager to determine whether any updates are available, with the DownloadManager to download the updates, and with the ActivationManager to activate the updates. It also provides methods to the client application to start the download and activation processes and events to track the update progress.
• Manifest management subsystem. The manifest is configuration information for the update that is to be applied to the client application. It is stored on the server; the information describes the updates that are available and the configuration of those updates. It also defines the activation processors that should be executed after the files are transferred. Manifest classes access this information and make it available to the other classes in the application block.
• Downloader subsystem. This subsystem is responsible for connecting to the server and downloading the updates to the client computer.
• Activation subsystem. This subsystem is responsible for performing any activation processing, for example, copying the downloaded files to a specified location, deleting temporary files and folders, or registering assemblies in the global assembly cache.

Figure 2.1 shows the high level design of the Updater Application Block.

Figure 2.1. High level design of the Updater Application Block

The simplest case of using the Updater Application Block consists of the following steps:

1. The client application requests the ApplicationUpdaterManager to check if any updates are available.
2. The client application requests the ApplicationUpdaterManager to use the ManifestManager to retrieve the XML manifest for this application from a server location specified in the client configuration.
3. If updates are available, the client application requests the ApplicationUpdaterManager to call the DownloadManager, which uses the BITSDownloader to transfer the files listed in the manifest from server to client.
4. After all the relevant files are downloaded, the client application requests the ApplicationUpdaterManager to call the ActivationManager which executes the ActivationProcessors specified in the manifest.

Common Usage Scenarios

There are three common usage scenarios for the Updater Application Block:

• Self updating applications. In this scenario, the client application uses the Updater Application Block to check for updates while it is running. The process may be initiated by a user request or at pre-configured intervals. Updates are downloaded while the client application is running and then activated when the application exits. This is known as an in-process update.
• Stub applications. In this scenario, the user starts a bootstrap application that checks for updates. If any are present, it downloads and activates them before starting the client application.
• Windows services. In this scenario, a Windows service is used to check for updates for multiple client applications. If any are present, it downloads and activates the updates for each application.

For more information about implementing each of these scenarios, see Choose the Application Scenario.

Within each of these scenarios, you can make further decisions about how to implement your self-updating application. These include the following:

• Synchronous or asynchronous downloading of updates. The IDownloader interface defines methods for both synchronous and asynchronous downloads of updates. The ApplicationUpdaterManager provides two methods that your client application can call to initiate either a synchronous or asynchronous download.
• Mandatory or optional updates. The manifest contains a mandatory attribute that you can use to specify whether an update should be mandatory. You can use this attribute to determine whether the user should be given the option to not install the update.
• Pre-launch or post-launch application updates. The stub application can be configured to run the update process either before or after the client applications runs.

This section describes the subsystems and tools included in the Updater Application Block:

Update Management Subsystem

Manifest Management Subsystem

Downloader Subsystem

Activation Subsystem

Configuration Design

Utility Design

Manifest Schema Design

PostApplicationExitActivationProcess Design

Update Management Subsystem

The update management subsystem contains three core classes that are central to the functionality of the application block:

ApplicationUpdaterManager Class

UpdaterTask Class

RegistryManager Class

ApplicationUpdaterManager Class

The ApplicationUpdaterManager class is a facade into the application block and it controls the actions of the application block. This class can be instantiated using the static GetUpdater factory method provided in the class.

The ApplicationUpdaterManager class is responsible for interacting with the ManifestManager class to determine whether any updates are available. It contains methods that use the DownloadManager and ActivationManager classes to start the download and the activation processes, and it exposes update progress events that an application can subscribe to. These events enable an application to track the progress of downloads. Events are also exposed for tracking the different task states during the update process (DownloadStarted, DownloadCompleted, ActiviationInitializing, or ActivationCompleted) for the application to alert the user, restart itself, or both.

The class contains the CheckForPendingUpdates method that uses the RegistryManager to check for pending updates from a previous update process. This method raises the OnPendingUpdatesDetected event, which the client application can handle to resume or cancel the updates. You can call the CheckForPendingUpdates method directly from the client application; however the method is also called from the CheckForUpdates method. This means that whenever the client application checks for new updates, it is notified of any pending updates and has the opportunity to resume the pending update or to cancel it. If the pending task is resumed and fails again, it remains in the task registry and the manifest is not committed. The task will be retried during each update until the client application calls the CancelPendingUpdate method. If the client application does not call the ResumePendingUpdate method from the OnPendingUpdatesDetected event, the pending task is canceled to enable a new task to be started.

The ApplicationUpdaterManager supports both synchronous and asynchronous operations, enabling applications to download updates in the foreground or background. This means that users do not need to be interrupted while downloads occur. The manifest download and activation processes are synchronous-only operations.

UpdaterTask Class

The UpdaterTask class is responsible for storing the state of an update. Instances of this class are serialized and deserialized to and from an application registry that stores the state of application updates. The application block uses this registry to persist the update task information across restarts. The UpdaterTask class contains members that store the following:

• The manifest being downloaded
• A unique identifier for identifying the task
• The base location of the download
• The state of the update
• A state bag to store information between activation processors

This class implements ISerializable so that the RegistryManager can serialize the task into its own storage. This is necessary so that any pending tasks will be resumed when the application block starts.

RegistryManager Class

The registry classes are responsible for managing a registry of updates that are currently executing. This registry is designed to ensure that multiple updates are not concurrently initiated for the same application and to store information to survive interruptions to the update process.

The RegistryManager class manages the registry of tasks. It is implemented as a singleton object to ensure that only one instance per application is active at any one time. It maintains a registry containing the UpdaterTaskID and UpdaterTask of each task that is currently in progress. This information is used by the ApplicationUpdaterManager to ensure that only one instance of each task is started. Each UpdaterTask is persisted as a separate binary file.

When a task is started, the ApplicationUpdaterManager saves the UpdaterTask in the registry and then whenever a state change occurs, the UpdaterTask is updated. When the activation process completes successfully, the task is deleted from the registry. If the activation process is unsuccessful, the UpdaterTask is persisted so that the client application can resume the pending task next time the update process is initiated.

Manifest Management Subsystem

The manifest is provided on the server and it contains information for the update that is to be applied to the client computer. The client configuration file contains the location of the manifest; however, a client application can pass the location information directly to an overloaded method in the ApplicationUpdaterManager. The manifest classes use this location information to obtain the contents of the XML. The manifest contains information that describes the updates that are available, the files to be downloaded, the path where the files are located on the server, and the downloader to use. It also defines the activation processors that should be executed after the files are transferred.

A manifest can contain a list of one or more included manifests. In this situation, the primary manifest identified in the client configuration will list other manifests that should be applied to the client application. If any manifests are found that have not been applied to the client application, they are executed in the usual way. The Updater Application Block does not guarantee what order the manifests are run in. To enforce order or dependencies, the client application must acquire the order or dependency list externally. This can be as simple as maintaining a list of manifests that are returned from the original call to CheckForUpdates. You can use this technique to implement versioning of client applications. However, if the manifest is very complex; you should consider using Windows Installer files for updates.

The manifest management subsystem contains a number of classes that are used to interact with the manifest, including the following:

ManifestManager Class

Manifest Class

ApplicationManifest Class

FileManifest Class

FilesCollection Class

ManifestManager Class

The ManifestManager class is an internal class that is responsible for obtaining the download manifests from the Uniform Resource Identifier (URI) specified in the application configuration file or passed to the class programmatically from the client application. Its implementation using a URI is compliant with the ClickOnce design in Visual Studio 2005. When using the default configuration, the URI is expected to point to an XML file; however, if you require dynamic generation of the XML, the URI can point to a Web service or ASPX file.

The ManifestManager downloads, deserializes, and validates the XML contained in the manifest and creates an instance of the Manifest class for each manifest. This Manifest class is simply a data class representing the XML that is returned to the ApplicationUpdaterManager.

During the download and serialization process, the XML is validated against the schema defined in the manifest schema and the application element is checked to ensure that this manifest relates to the client application using it.

Manifest Class

The Manifest class is a data class representation of the contents of the manifest. It contains members that store the contents of attributes and elements in the manifest XML. It also implements ISerializable so that it can be deserialized at the client.

The Manifest class contains an Apply property that the client application can use to define whether an individual manifest should be applied during the application update process.

There is one instance of the Manifest class for each updater task defined by a single manifest. This class contains all the information about the task and an UpdaterTask instance is created in the task registry for the task. The UpdaterTask instance is then used as an information source during the download and activation processes.

You can implement partial updates by including a hash value for each download file listed in the manifest. The ManifestManager is responsible for comparing any hash value in the manifest to the hash value of the corresponding file on the client to determine whether a particular file needs to be downloaded. Alternatively, partial updates can be accomplished using Windows Installer packages. For more information about partial updates, see Performing Partial Updates.

ApplicationManifest Class

The ApplicationManifest class is a data class representation of the contents of the application element in the manifest XML. It contains members that store the contents of the attributes and elements in the application element.

FileManifest Class

The FileManifest class is a data class representation of the contents of the file element in the manifest XML. It contains members that store the contents of the attributes of the file elements. One instance of the FileManifest is created for each file element in a manifest.

FilesCollection Class

The FilesCollection class is a collection of FileManifest objects that are referenced in the manifest XML. It extends the System.Object.CollectionBase class and contains members that provide collection manipulation functionality.

Downloader Subsystem

The downloader subsystem contains classes that are responsible for the downloading of updated files from the server to the client computer. These classes include the following:

DownloadManager Class

DownloadProviderData Class

DownloadProviderDataCollection Class

IDownloader Interface

IDownloader Implementations

DownloadManager Class

The DownloadManager is an internal class that is responsible for instantiating the appropriate IDownloader implementation as specified in the manifest file. If a downloader is not identified, the default BITSDownloader is used.

Because the download may be a lengthy process, the DownloadManager contains synchronous and asynchronous versions of the methods to initiate a download; these are called from methods in the ApplicationUpdaterManager class. By default, BITS supports only asynchronous downloads; however, the BITSDownloader class provides methods for both synchronous and asynchronous downloads. The DownloadManager class also contains a method for canceling a download. The DownloadManager class also defines a set of events that the ApplicationUpdaterManager propagates to the client application so it can track the progress of the download process.

DownloadProviderData Class

The DownloadProviderData class stores the information contained in an individual downloader element of the Updaterconfiguration.config file. The application block uses this to return the configuration settings for the downloader being used, such as user credentials required by the downloader.

DownloadProviderDataCollection Class

The DownloadProviderDataCollection class stores a collection of DownloadProviderData classes. It provides the collection capabilities for the application block to iterate through the collection of available downloaders.

IDownloader Interface

The IDownloader interface defines the members that all Downloader implementations must support. It defines methods for both synchronous and asynchronous downloads. It also defines the progress events exposed by the download implementation class.

IDownloader Implementations

The Updater Application Block ships with a default downloader that uses the Windows Background Intelligent Transfer Service (BITS). In addition to this, you can develop your own custom implementations of the IDownloader interface to access updates from alternative locations such as a UNC path or Web service. For more information about developing custom downloaders, see Adding a Downloader Provider.

The choice of downloader for a client application is configurable at run time by changing the contents of the manifest and application configuration information. This means you can easily update an application to use a new downloader without having to recompile the application itself.

Certain downloaders may need client-side information to function; for example, the BITS downloader requires user credentials for authentication. To support this client-side configuration, the Updater Application Block uses the Enterprise Library Configuration Application Block. This application block stores run-time configuration information in a configuration file named Updaterconfiguration.config; this file is referenced from the client application's App.config file. At design time, you can use the Enterprise Library Configuration Console to manage the downloader configuration.

BITSDownloader

The BITSDownloader is the default implementation of the IDownloader interface and is used if no other downloader is specified in the manifest information. It uses the Windows Background Intelligent Transfer Service (BITS) to download files from the server.

BITS is the default transfer technology because it provides the following features:

• It performs asynchronous job execution to maximize performance of the updates.
• It supports HTTP and HTTPS connections.
• It resumes automatic file transfers after network or computer failure.
• It performs transfers using idle network bandwidth to avoid interference with other applications needs.

This design choice has two major tradeoffs:

• The BITSDownloader will function only on versions of Windows that currently support BITS. These include Windows 2000, Windows XP, and Windows Server 2003.
• By default, BITS uses the identity of the currently logged-on user that initiated the transfer. If the user logs off, the transfer is suspended until the user logs on again. When using the Updater Application Block, you can specify the user credentials to use in the application configuration. If you do not specify a user, the user identity used is that of the controller application. In the case of the application block being used from a Windows service with the default user identity, you must ensure that the user profile associated with the Windows account assigned to the service is loaded. (This is default behavior when the Local System account is used.)

The BITSDownloader includes a number of classes to perform its tasks:

BITSDownloader Class

BITSDownloaderProviderData Class

BITSDownloadErrorException Class

BITSInterop Class

Note   You can use BITS to transfer static content, such as executables and text files, without any special configuration. However, to transfer dynamic content such as ASP pages or CGI scripts, you must ensure that the files being copied support the Content-Range and Content-Length headers. For more information, see "Background Intelligent Transfer Service" in the Platform SDK documentation on MSDN.

BITSDownloader Class

The BITSDownloader class uses the wrapper methods in the BITSInterop class to consume the BITS API to transfer files from a server to a client computer.

It also contains callback functions that receive notifications when a job is complete, has been modified, or has errors. These are eventually exposed as events to the client application.

BITSDownloaderProviderData Class

The BITSDownloaderProviderData class is an internal class that supports the BITSDownloader class. It inherits from the DownloadProviderData class. It stores the client configuration information from the client configuration file for use by the BITSDownloader class. It contains members to store the following fields:

• User name. This field stores the user's user name.
• Password. This field stores the user's password.
• Authentication mechanism. This field stores the type of authentication mechanism to use, which can be basic, digest, NTLM, negotiate, or passport.
• Target server type. This field stores whether the credentials are used for server or proxy authentication requests.

BITSDownloadErrorException Class

The BITSDownloadErrorException class supports the BITSDownloader class. If a native BITS error occurs during the download, this class wraps the error as a .NET exception and returns it to the BITSDownloader class.

BITSInterop Class

The BITSInterop class defines the COM interop wrapper that the BITSDownloader uses to access the BITS API.

Activation Subsystem

The activation subsystem contains classes that are responsible for performing activation processing. For example, in addition to downloading new files, you may need to execute a downloaded .msi file or create new entries in the registry. By default, update files are downloaded to a temporary folder on the client computer. If you do not execute any activation processors, the files are then deleted at the end of the process.

The Updater Application Block, version 2.0, supports using multiple activation processors per update. The application block ships with a set of commonly required processors, and you can write your own custom processors by implementing the IActivationProcessor interface.

The application block contains a number of classes that are used to support the activation processing, including the following:

ActivationManager Class

ActivationProcessorProviderData Class

ActivationProcessorProviderDataCollection Class

IActivationProcessor Interface

IActivationProcessor Implementations

Activation Extensibility Model

The Updater Application Block uses an extensible model for the processor design. The ActivationManager is used to obtain a list of processors that must be run, but each processor is responsible for the actual execution of its own task. The IActivationProcessor interface must be implemented for a processor to enable activation processing to occur. You can include the functionality you require for your specific activation scenario in your implementation of this interface.

This model enables the following:

• Activation processing composition and reusability
• Extensions to the activation processing model

These abilities result in an environment that supports a wide range, from very simple to extremely complex, of activation processing tasks to be implemented in your solutions. The QuickStarts included in the Updater Application Block include examples of the following out-of-the-box activation processors:

• WaitForApplicationExitProcessor
• ApplicationDeployProcessor
• MSIProcessor

ActivationManager Class

The ActivationManager class is responsible for checking the manifest information to determine whether any post-download processing is required and which activation processors to use. If no processors are listed in the manifest, no processing occurs. If processors are listed, the ActivationManager class uses the three-phase execution model to run the activations:

• Phase 1–Initialization. Each activation processor is initialized and is queried as to whether any prerequisites for its execution are met.
• Phase 2–Execution. If every activation processor is able to execute, they run in the order specified in the manifest.
• Phase 3–Error handling. If any activation processor throws an exception, each processor that has been executed is given the opportunity to perform any corrective actions before the activation process is aborted and the ApplicationUpdaterManager notified.

The ActivationManager class also defines a set of events that the ApplicationUpdaterManager propagates to the client application so it can track the progress of the activation process.

A new instance of each processor will be created for every activation task. No instance reuse is guaranteed.

ActivationProcessorProviderData Class

The ActivationProcessorProviderData class stores information obtained from the activation element in the manifest XML. This includes the name and type of the processor to execute and processor specific information that is used during the activation process.

ActivationProcessorProviderDataCollection Class

The ActivationProcessorProviderDataCollection class stores a collection of ActivationProcessorProviderData classes. It provides the collection capabilities for the application block to iterate through the collection.

IActivationProcessor Interface

The IActivationProcessor interface defines the members that all processor classes must implement. These include an Init method to initialize the processor, a PrepareExecute method to ensure that the processor can potentially run and prepare for the execution, an Execute method to run the process, and an OnError method to perform corrective processing if an error occurs in a later activation.

The application block contains a suite of implementations of this interface, and you can also write your own custom processors to undertake tasks specific to your application.

IActivationProcessor Implementations

The application block contains the following implementations of the IActivationProcessor interface:

ApplicationDeployProcessor

FileCopyProcessor

FileDeleteProcessor

FolderCopyProcessor

FolderDeleteProcessor

MSIProcessor

WaitForApplicationExitProcessor

GACUtilProcessor

InstallUtilProcessor

UncompressProcessor

ValidateHashProcessor

Each implementation provides functionality to execute a typical post-download task. For example, the MSIProcessor executes an .msi file that has been downloaded.

ApplicationDeployProcessor

The ApplicationDeployProcessor implementation of the IActivationProcessor interface copies non-transient files specified in the manifest to the application location specified in the manifest. This class contains the following members:

• The Init method of this class stores the current task, which is passed to the method, in a class variable.
• The Execute method copies the downloaded files to the application location specified in the task manifest.
• The OnError method removes any files that have been copied to the destination folder.

FileCopyProcessor

The FileCopyProcessor implementation of the IActivationProcessor interface copies downloaded files to a location configured in the manifest for that file or to the application location specified in the manifest. This class contains the following members:

• The Init method of this class extracts the current task, source location, destination location, and overwrite option from the arguments passed to it and stores the information in class variables.
• The PrepareExecution method generates a fully qualified file name for the source file and verifies that the file exists.
• The Execute method ensures the destination folder exists and then copies each required file to the target folder.
• The OnError method removes any files that have been copied to the destination folder.

FileDeleteProcessor

The FileDeleteProcessor implementation of the IActivationProcessor interface deletes the specified file from a location configured in the manifest for that file or from the application location specified in the manifest. This class contains the following members:

• The Init method of this class extracts the file name to be deleted from the ActivationProcessorProviderData, which is passed to it and stores the information in a class variable.
• The Execute method extracts the folder and file name from the specified file received by the Init method and deletes the file.

FolderCopyProcessor

The FolderCopyProcessor implementation of the IActivationProcessor interface copies the contents of a specified source folder to a location configured in the manifest for that folder or to the application location specified in the manifest. This class contains the following members:

• The Init method of this class extracts the current task, source location, destination location, and overwrite option from the arguments passed to it and stores the information in class variables.
• The Execute method uses the CopyDirectory method from the internal FileUtility class to recursively copy the contents of the source folder to the destination.

FolderDeleteProcessor

The FolderDeleteProcessor implementation of the IActivationProcessor interface deletes the specified folder from a location configured in the manifest for that folder or from the application location specified in the manifest. A switch is used to specify whether this should perform a recursive delete or delete only an empty folder. This class contains the following members:

• The Init method of this class extracts the path and recursive attributes from the ActivationProcessorProviderData, which is passed to the method and stores the information in class variables. The default setting for recursive is true; this results in the contents of the folder being deleted. If this setting is false, only an empty folder can be deleted.
• The Execute method uses the Delete method from the System.IO.Directory namespace to delete the folder and optionally its contents.

MSIProcessor

The MSIProcessor implementation of the IActivationProcessor runs Windows Installer packages on the client computer. This class contains the following members:

• The Init method of this class prepares the properties of the installer using the information from the ActivationProcessorProviderData, which is passed to the method and stores the information in class variables.
• The Execute method determines whether this should be an install, patch, or remove process from the installer properties and executes the installer using the configuration extracted in the Init method.

Note   By default, when executing the MSI, the MSIProcessor does not query the user for information such as where the application is to be installed, which users can run the application, and agreement to the license. To modify this behavior, you can add the uiLevel element to the activation processor configuration in the manifest. For more information about the valid values for this element, see Installer.UILevel on the MSDN Web site.

WaitForApplicationExitProcessor

The WaitForApplicationExitProcessor implementation of the IActivationProcessor resolves the issue of application files being locked when an update is executed. The WaitForApplicationExitProcessor batches the activation process until the application is closed and then it resumes the activation process. This class contains the following members:

• The Init method of this class extracts the process name attribute from the ActivationProcessorProviderData, which is passed to the method and stores the information in a class variable.
• The PrepareExecute method of this class determines whether the application is currently executing. If it is not, the method returns. If the application is executing, it calls the PostApplicationExitActivationProcessor.exe tool, passing the process ID of the executing application and raises the ActivationPausedException. The tool waits for the application to exit before completing the copy process.
• The Execute method does not need any implementation code in this processor because the processor is only intended to branch to a different task to wait for the application exit.

GACUtilProcessor

The GACUtilProcessor implementation of the IActivationProcessor interface uses the .NET Framework Global Assembly Cache tool, Gacutil.exe, to install downloaded assemblies into the global assembly cache. This class contains the following members:

• The Init method of this class extracts the assembly name, file name, and options from the ActivationProcessorProviderData, which is passed to the method and stores the information in class variables.
• The PrepareExecution method retrieves the full path to Gacutil.exe from the registry and verifies that the file exists.
• The Execute method calls Gacutil.exe, passing the assembly information retrieved by the Init method.

InstallUtilProcessor

The InstallUtilProcessor implementation of the IActivationProcessor interface uses the .NET Framework Installer tool, Installutil.exe, to install or uninstall downloaded resources by executing the installer components in a downloaded assembly. This class contains the following members:

• The Init method of this class extracts the action to be performed, install, or uninstall, from the ActivationProcessorProviderData, which is passed to the method. It also constructs the parameter string to be passed to Installutil.exe using information from the ActivationProcessorProviderData.
• The PrepareExecution method retrieves the full path to Installutil.exe from the registry and verifies that the file exists.
• The Execute method calls Installutil.exe passing the string constructed in the Init method.

UncompressProcessor

The UncompressProcessor implementation of the IActivationProcessor interface uses the Windows Expand.exe tool to expand .cab files. This class contains the following members:

• The Init method of this class extracts the source and destination folder information from the ActivationProcessorProviderData, which is passed to the method and stores the information in class variables.
• The PrepareExecution method generates the full path to Expand.exe, using the System.Environment class to determine the system folder where it should be located. It then verifies that the file exists.
• The Execute method calls Expand.exe, passing the source and destination information retrieved by the Init method.

ValidateHashProcessor

The ValidateHashProcessor implementation of the IActivationProcessor interface compares the hash value of a downloaded file with the hash defined for that file in the manifest to ensure that the correct files have been downloaded. This class contains the following members:

• The Init method of this class extracts the source file name from the ActivationProcessorProviderData, which is passed to the method and stores the information in a class variable.
• The Execute method retrieves the hash value of the original download files from the manifest. It then compares the hash of the downloaded file with the hash retrieved from the manifest and throws an exception if they do not match.

Configuration Design

The configuration for the Updater Application Block is stored in an XML file in the client application. The application block contains a set of classes that are responsible for storing the information from that file in an object-oriented format, including the following:

Updaterconfiguration.config File

ApplicationUpdaterSettings Class

Updaterconfiguration.config File

The client application stores the application configuration information that the Updater Application Block requires in the Updaterconfiguration.config file, which is referenced from the App.config file. The application block uses the Enterprise Library Configuration Application Block to retrieve this information and store it in classes that the Updater Application Block uses to access the settings.

The information is all stored within the applicationUpdater element located in the Updaterconfiguration.config file. Table 1 describes the structure of this element.

Table 1: Structure of applicationUpdater element

The following code shows an example of a valid application configuration file.

<?xml version="1.0" encoding="utf-8"?>
<UpdaterConfiguration>
  <xmlSerializerSection type="Microsoft.ApplicationBlocks.Updater.Configuration.ApplicationUpdaterSettings, Microsoft.ApplicationBlocks.Updater">
    <applicationUpdater xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" applicationId="{215e1ad7-9aba-432f-a952-24baba556850}" basePath="C:\Program Files\SimpleDesign" manifestUri="http://localhost/simpledesign/server/manifest.xml" xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2" >
      <manifestManager username="" password="" authenticationMethod=""/>
      <downloaders>
        <downloader xsi:type="BitsDownloaderProviderData" name="BITSDownloader">
         <userName></userName>
         <password></password>
         <authenticationScheme>BG_AUTH_SCHEME_NTLM</authenticationScheme>
         <targetServerType>BG_AUTH_TARGET_SERVER</targetServerType>
        </downloader>
      </downloaders>
    </applicationUpdater>
  </xmlSerializerSection>
</UpdaterConfiguration>
  

Various classes are included in the application block to store the information contained in this configuration file in an object-oriented format for use during the update process.

ApplicationUpdaterSettings Class

The ApplicationUpdaterSettings class stores the top-level information obtained from the Updaterconfiguration.config file. It contains a class variable for each of the attributes of the applicationUpdater element.

Figure 2.2 shows that the class stores information from each of the elements in the configuration file for the application block to use. For example, the ManifestUri property stores the URI of the manifest index from the manifestUri element.

Figure 2.2. Updaterconfiguration.config and the ApplicationUpdaterSettings class

Utility Design

The utility classes offer utility functions to the other classes in the application block:

DownloaderFactory Class

FileUtility Class

Logger Class

ProcessorFactory Class

SchemaValidator Class

DownloaderFactory Class

The DownloaderFactory class provides functionality to create an instance of a specified downloader using information from the application configuration.

FileUtility Class

The FileUtility class provides a series of file and folder manipulation functions used in the application block, including the following:

• IsUNCPath
• AppendSlashURLorUNC
• AppendTerminalBackSlash
• AppendTerminalForwardSlash
• CreateTemporaryFolder
• CopyDirectory
• MoveFile

These functions are used to manipulate the files and folders used during the download and activation processes.

Logger Class

The Logger class provides the logging functionality for warnings and exceptions raised within the application block. It is a singleton wrapper around the Enterprise Library Instrumentation EventLogger class.

ProcessorFactory Class

The ProcessorFactory class provides functionality to create an instance of a specified activation processor.

SchemaValidator Class

The SchemaValidator class contains members that validate XML documents against the schemas that define their required structure. The ManifestManager class uses these functions to verify that the manifest files are valid.

Manifest Schema Design

The Manifest schema defines the required structure of the manifest files. It defines the required and optional elements and attributes within the file. It uses both simple types (for example, string and Boolean) and complex types (for example, task). Table 1 describes the elements and attributes in the Manifest schema.

Table 1: Elements and attributes in the Manifest schema

The following code shows an example of a valid manifest file.

<manifest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" manifestId="{311085F7-9320-4318-9A67-9BE32F04E933}" mandatory="False"
  xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
  <description>ClientApp manifest</description>
  <application applicationId="{215E1AD7-9ABA-432f-A952-24BABA556850}">
    <entryPoint file="MyApp.exe" parameters="" />
    <location>..\..\New\</location>
  </application>
  <files base="http://localhost/MyApp" hashComparison="No">
    <file source="Name.txt" />
  </files>
  <downloader name="BITSDownloader"/>
  <activation>
    <tasks>
      <task name="ApplicationDeployProcessor" type="Microsoft.ApplicationBlocks.Updater.ActivationProcessors.ApplicationDeployProcessor, Microsoft.ApplicationBlocks.Updater.ActivationProcessors"/>
    </tasks>
  </activation>
</manifest>
  

PostApplicationExitActivationProcess Design

In some scenarios, files will be in use when the updated versions are downloaded. The PostApplicationExitActivationProcess assembly contains an application that the WaitForApplicationExitProcessor uses to complete updates after the client application has exited.

To complete the update process, the file locks must be released by exiting the application and the old versions replaced. This assembly waits for the client application to exit, and then it resumes the pending update tasks stored in the task registry.

Start | Previous | Next