+
Download
+ the .NET Application Updater Component
+
+
.NET Client
+ Applications: .NET
+ Application Updater Component
+
+
I
+ recently received a mail from the
+ Microsoft IT team notifying me that they had detected several
+ applications on my desktop computer that did not have the latest
+ patches installed and instructed me to install the latest
+ updates. Ill be the first to
+ admit that I dont update the applications I run as much as I should;
+ either on my home machine or on my work machines. It usually takes a problem like a
+ broken feature in an application or an email (or sometimes several)
+ from the IT department, to get me to install updates. Unfortunately Im more of the rule
+ than the exception when it comes to users updating their
+ applications.
+
+
+
This requirement of
+ needing a user or admin to manually install an update is why rolling
+ out client updates has traditionally been such a huge problem and
+ expense. One solution is to
+ move the responsibility of updating the application from the user to
+ the application itself.
+ Instead of the user obtaining and installing a software
+ update, the client application itself is responsible for downloading
+ and installing updates from a well known server. The only user interaction
+ necessary is whether or not they want to install the new updates now
+ or later. You can see this
+ type of approach to updating applications in action today with
+ products like Windows XP and Microsoft Money.
+
+
In this article we will
+ talk about an approach to building .NET client applications that are
+ able to automatically update themselves.
+
+
+
The .NET Application
+ Updater Component
+
Included with this
+ whitepaper is a component for enabling .NET client applications to
+ automatically update themselves.
+ The component was written using the .NET Framework and
+ enables you to make your application auto-updatable simply by
+ dropping the component into your existing .NET applications and
+ setting a few properties (ex. where to get updates from). Download
+ the .NET Application Updater Component.
+
+
This component is not a
+ Microsoft product. It is
+ intended as a sample to get you started and as such the source is
+ also included with this whitepaper.
+ However, it is worth mentioning that this component has
+ gotten a fair amount of real world use already. It has been used internally in
+ Microsoft to enable auto-updatability in the .NET Terrarium game (http://www.gotdotnet.com/terrarium/). Terrarium has been installed and
+ used by over 10,000 individuals since it was first unveiled as a
+ beta product in October, 2001.
+
+
This component will be
+ the basis for the discussion of what it takes to make an application
+ auto-updatable. This paper
+ will focus on how the .NET Application Updater component works and
+ how you can use it in your own application.
+
+
+
Checking for
+ Updates
+
The first thing an
+ application needs to be able to do in order to update itself is
+ figure out when a new update is available. In order to do this an application
+ needs to know three things 1) where to check for updates, 2) when to
+ check for updates and 3) how to check for updates. The application update component
+ uses HTTP for all network communication. This allows it to update
+ applications over the intranet or extranet. Thus the where to check for
+ updates is simply a URL to a well known Web server.
+
+
To address the when to
+ check for updates, the .NET Application Updater component creates a
+ thread on component creation which is responsible for checking for
+ updates. This thread will
+ sleep for most of the time, but will wake up at the configured
+ interval to perform an update check.
+ How often the application checks for new updates is dependent
+ on the individual application, but common values range from one hour
+ to one day between update checks.
+ This polling based approach is not appropriate for all
+ applications, for example Microsoft Money only checks for updates
+ when the user tells them to.
+ In this case, the update poller thread can be disabled and
+ update checks performed on-demand by calling the CheckForUpdate()
+ method on the updater component.
+
+
+
There are several ways
+ to go about the how to check for updates:
+
+
Method #1: Direct File Check The simplest way to
+ check for updates is to use HTTP to compare the last modified
+ date/time stamp of the application files on the server with that on
+ the client. If the server has
+ newer files, the client knows its time to update itself. This is the same way a Web browser
+ knows if it needs to re-download an html page or image or whether it
+ can just re-use the one previously downloaded. This is certainly the simplest to
+ administrate. When a new
+ version of the app is available, the administrator simply copies the
+ newer version over the older version on the Web server. The problem with this is that the
+ update is not atomic and thus there are potential windows of
+ failure. For example, if an
+ administrator updates the version of the app on the Web server while
+ a client was in the middle of downloading the previous update, that
+ client may be left with some files from the previous update and some
+ files from new update. For
+ this reason, using a direct file check is not recommended for any
+ non-trivial applications.
+
+
+
Method #2: Manifest Check To solve the atomicity
+ problem with direct file checks a level of indirection is
+ needed. To create a level of
+ indirection a manifest file on the server is used. A valid server manifest file for
+ use with the .NET Application Updater component looks like
+ this:
+
+
<VersionConfig>
+
<AvailableVersion>1.0.0.0</AvailableVersion>
+
<ApplicationUrl>http://localhost/demos/selfupdate/V1/</ApplicationUrl>
+
</VersionConfig>
+
+
AvailableVersion
+ specifies the assembly version number of the latest available
+ version. The ApplicationURL
+ property specifies the URL where that version of the application
+ resides. When the
+ administrator wants to update the client applications, they would
+ copy the new version of the app up to the Web server and modify the
+ server manifest file appropriately.
+ The client itself will then detect that the server manifest
+ file has changed and download the manifest file. The client then compares the
+ assembly version number specified in the manifest with the assembly
+ version number of the applications .exe file. If the server manifest file
+ AvailableVersion is newer, the application knows its time to perform
+ an update. This approach has
+ none of the atomicity problems of the previous approach and is the
+ recommended way to check for updates for most applications.
+
+
Method #3: XML Web Service
+ Check
+ XML Web services provide a way to perform more advanced update
+ checks. For example, suppose
+ you wanted to roll out an update to a set of early adopters before
+ you rolled it out to the rest of your users. If the client application calls an
+ XML Web service to check if an update is available, that XML Web
+ service could then look up that user in a database and determine if
+ the user is an early adopter or not.
+ If they are, the XML Web service could return a value
+ indicating that an update is available. If not, the Web service could
+ return a value indicating that a new update is not available. Because the Web service used to
+ check for updates could take many forms depending on what custom
+ functionality is desired, the .NET Application Updater component
+ does not provide direct XML Web service support. To use an XML Web service to check
+ for updates, first build the XML Web service and then hook the
+ OnCheckForUpdate event. This
+ allows the poller threads update check to be replaced with your own
+ custom check. The
+ OnCheckForUpdate event has a return value to indicate whether an
+ update was detected or not.
+
+
+
Downloading
+ Updates
+
Once the application
+ determines a new update is available, the update needs to be
+ downloaded. By default, when
+ the .NET Application Updater component detects that a new update is
+ available it will automatically kick off another thread and start an
+ asynchronous background download of the update. The download is done using
+ HTTP-DAV. DAV is an extension
+ to HTTP that provides functionality such as directory and file
+ enumeration. A complete and
+ deep download is done starting with the specified URL. The URL used to download depends
+ on the type of update check being done. For example, if a server manifest
+ is used, the URL to download the update from is specified by the
+ ApplicationURL property in the server
+manifest.
+
+
The download of the
+ update obviously needs to be robust.
+ Leaving the client application in any kind of bad state after
+ the download and update is unacceptable. Any number of problems could occur
+ during the download: The Web
+ server where the update resides could go down, the client machine
+ could crash, or for that matter the user could simply shut down the
+ application itself. Since the
+ application is what is doing the download, if its shut down, the
+ download will stop. An
+ alternative design would have been to use a separate system service
+ to do the download and update of the application. With a system service, the
+ download of the update could continue even when the application
+ itself is not running. In
+ fact, Windows XP has a built-in download service called BITS for
+ just this purpose. BITS is
+ what Windows XP uses to download updates to Windows itself. For more information on BITS, see
+ http://msdn.microsoft.com/library/en-us/dnwxp/html/WinXP_BITS.asp. A service was not used in the .NET
+ Application Updater component so that it would work on the Windows
+ 9x operating systems which do not support system services.
+
+
+
The .NET Application
+ Updater component achieves robustness by breaking the download and
+ update process into separate stages.
+ As each stage is complete, it is recorded in an updater
+ manifest file which resides in the application directory on the
+ client. If the download or
+ update process is interrupted at any stage, it will simply resume
+ from the point of the last completed phase the next time the app is
+ started. Each stage is re-run
+ able so that if a failure occurs in the middle of a stage,
+ re-running the stage from start will succeed. If an error occurs, such as the
+ loss of connectivity with the Web server during a download, the .NET
+ Application Updater component will simply try again later. If enough failures are reported
+ (ex. The Web server never came back online), the download and update
+ will be aborted and an error reported.
+
+
+
Performing
+ updates
+
Once the new update has
+ been downloaded, the last step is to apply the update. This last step is by far the most
+ challenging. The fundamental
+ problem is that the application is trying to update its own files
+ while running. Thus the files
+ are locked. The only way to
+ unlock the files is to stop the application, but if you stop the
+ application, how can it update its files? Its a catch 22. We went through several designs
+ before we came up with our final approach. Before I describe the final
+ design, lets look at our first approach and describe its
+ shortcomings.
+
+
+
Our first approach was
+ to simply kick off a separate process to perform the update. This separate process would first
+ shut down the application process, perform the update (since the
+ files were now unlocked), restart the application process and then
+ shut itself down when complete.
+ However, there were three fundamental problems with this
+ design:
+
+ - It simply did not work
+ in some scenarios. For
+ example, Windows runs screen savers in what is called a Job
+ object. The defining
+ characteristic of a Job is that when the root process of a Job is
+ shut down, all processes it created are also shut down. This makes sense when you think
+ about it. When a screen
+ saver goes away, you want to make sure it all goes away. However, in the application
+ update case, when the updater process shut down the original
+ application process, the updater process itself would also be shut
+ down and thus no update performed.
+
- We wanted to be able
+ to automatically update all of the code that performed the
+ update. In the course of
+ use, we would find bugs in the .NET Application Updater component,
+ (ex. A timing window that would effect 1% of clients), and we
+ wanted the ability to automatically roll out fixes of not just the
+ application, but the .NET Application Updater component as
+ well. With this model, we
+ could not update the process that performed the
+ update.
+
- Forcing the user to
+ shut down the application and wait in the middle of use was
+ undesirable.
+
+
+
The final approach used
+ to perform the application update was inspired by the side-by-side
+ assembly model of the .NET Framework. Instead of trying to update the
+ application itself, create a new upto-date version of the
+ application next to the existing version. The new version can be created by
+ merging the existing application directory with the downloaded
+ update. When the new version
+ is complete, the user will automatically use that version the next
+ time they launch the application.
+ The original copy of the application can then be removed.
+ This tricky part is figuring out which version to launch at any
+ given time. To do that, a
+ program named Appstart is introduced. Appstart is the entry point into
+ your application. With this
+ model, your application directory will look something like
+ this:
+
+
Program Files
+
+
MyApp
+
+
Appstart.exe
+
Appstart.config
+
V1
+ Folder
+
MyApp.exe
+
V1.1
+ Folder
+
MyApp.exe
+
+
To run your application,
+ you always run Appstart.exe.
+ If you want a shortcut on the desktop, the shortcut should
+ point at Appstart, not at the application directly (Note that you
+ can rename AppStart.exe to be whatever you want, ex.
+ YourApp.exe). Appstart.exe is
+ a very simple program that reads the Appstart.config file and
+ launches the specified application.
+ A valid Appstart.config file looks like the following:
+
+
<Config>
+
<AppFolderName>V1
+ Folder</AppFolderName>
+
<AppExeName>MyApp.exe</AppExeName>
+
<AppLaunchMode>appdomain</AppLaunchMode>
+
</Config>
+
+
The AppFolderName
+ specifies the subfolder that contains the current version of the app
+ to run. The AppExeName
+ contains the name of the exe within that folder to launch. When an application update is
+ complete, the final step is to change the AppFolderName value to
+ point at the new version of the application. Thus the next time the user runs
+ the application, they will run the new updated version of the
+ application. The
+ AppLaunchMode specifies how to launch the application. There are two ways to launch the
+ application. This first
+ approach is with AppDomains.
+ AppDomains are a feature of the .NET Framework common
+ language runtime and the logical unit of isolation and
+ administration of objects.
+ The common language runtime allows multiple application
+ domains per process. Thus
+ Appstart.exe can launch your application in a separate AppDomain but
+ within the same AppStart.exe process. Thus, despite the fact that two
+ different exes are running (in this case Appstart.exe and
+ MyApp.exe), only one process is used. For most applications AppDomains
+ will work well, however there are a few minor differences with
+ running in a separate AppDomain vs. a separate process. For that case, the AppLaunchMode
+ can be set to process which will cause the application to launch in
+ a separate process.
+
+
Once Appstart has
+ started the application, it will go to sleep and wait for the
+ application to terminate.
+ Once the application terminates, Appstart will also shut
+ down. However, if the
+ application shuts down with a well known return code, the Appstart
+ process will re-read the Appstart.config file and re-launch the
+ application. This is useful
+ if the user wants to begin using the new version of the application
+ immediately after it is available.
+
+
+
Using the .NET
+ Application Updater Component
+
Now that weve discussed
+ how the .NET Application Updater works, lets put it in action. First we will build a very simple
+ Windows Forms application.
+ Then we will enable it to auto-update itself using the .NET
+ Application Updater component.
+ Finally well deploy the application and see the auto-update
+ feature in action.
+
+
Included with this paper
+ is a zip file named DotNetUpdater.zip that contains the .NET
+ Application Updater component.
+ The zip file also contains a Sample directory which contains
+ a number of files and folders we will be using in this walkthrough.
+
+
+
Step 1: Build the application to
+ update
+
In this step we will
+ build the application to auto-update. If you want, you can substitute in
+ your own application here.
+ You can also use the pre-built sample application included in
+ the Samples\SampleApp\SampleApp directory of the zip file. However for the purpose of proving
+ that there isnt anything special about SampleApp, well walk through
+ its creation.
+
+
1.
+ Use Visual Studio .NET
+ to create a new Windows Application project, name it SampleApp.
+
2.
+ Give the form an
+ interesting background color of your choice. We will be using background color
+ to differentiate between versions later.
+
3.
+ Now lets add a tiny bit
+ of functionality to this application in the form of a button that
+ opens a form residing in a separate assembly. First add a button to your
+ form. The zip file contains
+ an assembly with a simple Windows Form in it. Add a reference to the
+ Samples\SampleApp\SimpleForm assembly in the zip. Then add two lines of code to your
+ button event handler:
+
+
SimpleForm.Form1 F = new
+ SimpleForm.Form1();
+
F.Show();
+
+
4.
+ Switch your build flag
+ to build RELEASE instead of debug.
+ This will allow us to avoid pdb file locking problems later
+ when we build a new version of the application while the original
+ copy is still running.
+
+
5.
+ Build and test your
+ application. It should look
+ similar to the Samples\SampleApp\SampleApp in the zip
+ file.
+
+
Step 2: Add the .NET Application Updater
+ Component
+
In this step we will add
+ the .NET Application Updater component to
+ SampleApp.
+
+
1.
+ In the components tab of
+ the Visual Studio .NET toolbox, right click and select Customize
+ Toolbox. Select the .NET Framework Components tab. Browse and select the
+ AppUpdater.dll in the AppUpdater project included in the zip. Click OK.
+
2.
+ An AppUpdater icon
+ should now show up at the bottom of the list of components in the
+ toolbox. Drag and drop the
+ AppUpdater component onto the SampleApp Form. An appUpdater1 instance of the
+ .NET Application Updater component should be instantiated and appear
+ below the form.
+
+
Step 3: Configure the .NET Application
+ Updater Component
+
In this step we will
+ configure the .NET Application Updater component. To do this, select the appUpdater1
+ component and open its properties.
+ The following section contains a description of each property
+ and what value to set it to.
+ Note that you only need to change the first four properties
+ for this example, for the rest, the defaults are
+ adequate.
+
+
AppUpdater
+ Properties These are the core
+ properties of the .NET Application Updater and will need to be set
+ for this application as follows:
+
+
+
+
+ |
+ Property
+ Name |
+
+ Description |
+
+ |
+ AutoFileLoad
+
|
+
+ This controls the
+ on-demand download feature described later, for now set this
+ to true. |
+
+ |
+ ChangeDetectionMode
+
|
+
+ This enum
+ determines how to check for updates. In this example, we will use
+ a server manifest check, so set this value to
+ ServerManifestCheck. |
+
+ |
+ ShowDefaultUI
+
|
+
+ The .NET
+ Application Updater component has a set of simple UI for
+ notifying the user of events such as a new update becoming
+ available or errors during updates. This UI can be replaced with
+ custom application specific UI by disabling the default UI,
+ hooking the appropriate events (ex. OnUpdateComplete) and
+ popping up the custom UI.
+ For this example we will use the default UI, so set
+ this value to true. |
+
+ |
+ UpdateUrl
+
|
+
+ The UpdateUrl is
+ what determines where the updater looks for updates. In this case we are using a
+ server manifest to check for updates, so this property should
+ be set to the URL of the server manifest. For this example, set it to
+ http://yourWebserver/SampleApp_ServerSetup/UpdateVersion.xml. Replace yourWebserver with
+ the name of your Web server.
+ |
+
Downloader
+ Properties The AppUpdater component has two
+ sub-components. The first is
+ called the Downloader and controls the download and installation of
+ the component. Below is a
+ description of the properties, but all defaults will work fine for
+ our SampleApp.
+
+
+
+
+ |
+ Property
+ Name |
+
+ Description |
+
+ |
+ DownloadRetryAttempts
+
|
+
+ If a failure
+ occurs during download (ex the Web server goes down) the
+ downloader will try again a little later. This property controls the
+ number of times the downloader will retry the network request
+ before treating it as a complete application update failure.
+ |
+
+ |
+ SecondsBeteweenDownloadRety
+
|
+
+ The number of
+ seconds before retrying the network
+ request. |
+
+ |
+ UpdateRetryAttempts
+
|
+
+ If a serious error
+ occurs during the update process, (ex. The downloader has
+ exceeded the DownloadRetryAttempts), an application update
+ error is generated. By
+ default, the update attempt will stop, but will attempt to
+ resume the next time the application is started (ex maybe the
+ update Web server was just down for day). This property controls how
+ many times an update will be attempted. If this value is exceeded,
+ the updater aborts the update, resets its state and goes back
+ to checking for updates.
+ |
+
+ |
+ ValidateAssemblies
+
|
+
+ This controls the
+ level of validation done on downloaded assemblies. See the security section of
+ this paper for more
+ info. |
+
+
Poller
+ Properties The second
+ sub-component of the AppUpdater is the Poller. The Poller controls the update
+ checks. Below is a
+ description of the properties, but all defaults will work fine for
+ our SampleApp.
+
+
+
+
+ |
+ Property
+ Name |
+
+ Description |
+
+ |
+ AutoStart
+
|
+
+ A Boolean that
+ controls whether or not the Poller should begin polling for
+ updates on application startup or whether it should wait until
+ it is explicitly started
+ programmatically. |
+
+ |
+ DownloadOnDetection |
+
+ A Boolean that
+ controls whether or not the Poller starts a download of an update
+ immediately after a new update is found, or whether the
+ download must be started explicitly by a call to the
+ DownloadUdpate() method. |
+
+ |
+ InitialPollInterval
+
|
+
+ The number of
+ seconds after application startup before the first update
+ check is performed. |
+
+ |
+ PollInterval
+
|
+
+ After the first
+ update check, the PollInterval controls the number of seconds
+ between each subsequent update check. Note: By default this checks every
+ 30 seconds; clearly you will want to reduce the frequency for
+ your application. |
+
+
When all is said and
+ done, your property grid should look the
+ following:
+
+
+
+
+
The
+ Samples\SampleApp\SampleApp_Complete directory contains a version of
+ the application correctly setup.
+
+
Step 4: Build & Deploy V1 of the
+ application to the client
+
In this step we will
+ build the V1 version of the application and deploy it to the
+ client. The deployment is
+ essentially simulating what the install program for your application
+ will do.
+
+
+
1.
+ In the SampleApp
+ project, open the AssemblyInfo.cs file. Change the AssemblyVersion value
+ from "1.0.*" to 1.0.0.0. This
+ will cause the built assembly to get marked with a value of 1.0.0.0
+ instead of the ever increasing value Visual Studio normally
+ assigns.
+
2.
+ Build the
+ application.
+
3.
+ Copy the
+ Samples\SampleApp\SampleApp_ClientSetup directory from the zip onto
+ your local machine. It doesnt
+ matter where you copy it, however the program files directory is the
+ most realistic place to put it since that is where most applications
+ get installed. Youll notice
+ that SampleApp_ClientSetup directory already has AppStart.exe
+ included. AppStart.config is
+ already set to point into the 1.0.0.0 directory and run
+ SampleApp.exe.
+
4.
+ Copy the complete
+ SampleApp (Appupdater.dll, SimpleForm.dll & SampleApp.exe) from
+ the release build directory of SampleApp to the
+ SampleApp_ClientSetup\1.0.0.0 directory on your client.
+
+
At this point a fully
+ functional version of the application should be installed on the
+ client and executable by running AppStart.exe
+
+
Step 5: Setup the Web
+ server
+
In this step we will
+ setup the Web server for use in rolling out application
+ updates. The .NET Application
+ Updater component uses HTTP-DAV to download the application update
+ and thus requires a Web server that supports HTTP-DAV. IIS 5.0 that comes with Windows
+ 2000 and newer operating systems support
+ HTTP-DAV.
+
+
1.
+ Copy the
+ Samples/SampleApp_ServerSetup directory from the zip into the
+ wwwroot directory of your Web server. Note: Any location on your Web server
+ can be used, but be sure to update the UpdateUrl property
+ accordingly. Notice that
+ UpdateVersion.xml is already setup for use as the server manifest
+ file.
+
2.
+ For completeness, copy
+ the V1 version of SampleApp into the 1.0.0.0 folder of the Web
+ server.
+
3.
+ Enable IIS Directory
+ Browsing for the SampleApp_ServerSetup directory on your Web
+ server. Since the .NET
+ Application Updater component enumerates the contents of directories
+ during download, Directory Browsing must be enabled. To do this, open the Internet
+ Information Services manager in the control panel. Select the SampleApp_ServerSetup
+ folder and open its properties.
+ Select the Directory Tab.
+ Check Directory Browsing, and click OK.
+
+
Step 6: Automatically update the
+ application
+
OK, now its time to see
+ the results of all this hard work by automatically rolling out a new
+ version.
+
+
+
1.
+ If the SampleApp version
+ you deployed to the client isnt running, launch it and leave it
+ running. Remember to use
+ AppStart.exe.
+
+
2.
+ Go back to Visual Studio
+ and change something noticeable on the SampleApp form (ex change the
+ background color).
+
3.
+ Change the VersionInfo
+ in AssemblyInfo.cs to be 2.0.0.0.
+
4.
+ Rebuild.
+
5.
+ Go to the Web server and
+ create a 2.0.0.0 directory as a peer to the 1.0.0.0 directory. Copy the new version of the
+ application from the release build directory into the new 2.0.0.0
+ directory on the Web server.
+
6.
+ Open UpdateVersion.xml
+ and change AvailableVersion to be 2.0.0.0. Change the ApplicationURL to point
+ at the new 2.0.0.0 directory.
+
7.
+ Save the changes to
+ UpdateVersion.xml.
+
+
+
As soon as you save the
+ new UpdateVersion.xml, within 30 seconds the running copy of
+ SampleApp should detect the newly available version. SampleApp will then download the
+ new version, apply the update, and pop up the default UI asking the
+ user if they want to restart and start using the new version
+ immediately. Click Yes in
+ response to this dialog.
+ SampleApp should restart and be running the new version.
+ If you look at the client
+ deployment of SampleApp you will notice there is now a 2.0.0.0
+ directory next to the original 1.0.0.0 directory. The 1.0.0.0 directory will be
+ cleaned up the next time an update occurs.
+
+
+
On-Demand
+ Install
+
By exploiting the
+ extensible nature of the .NET Framework, the .NET Application
+ Updater component is able to enable another feature, On-Demand
+ installation. By enabling
+ On-Demand installation, only the main exe needs to be explicitly
+ installed on the client. The
+ remainder of the application can be automatically downloaded and
+ installed on an as needed basis.
+
+
You can see this feature
+ in action with the SampleApp you just finished building and
+ deploying. In SampleApp we
+ enabled the On-Demand install feature by setting the AutoFileLoad
+ property to true. First close
+ SampleApp if it is still running.
+ Next, in the 2.0.0.0 folder of the SampleApp client
+ deployment, delete SimpleForm.dll.
+ Youll recall that SimpleForm.dll is the assembly that
+ contains the form that is displayed when the button on SampleApp is
+ clicked. With SimpleForm.dll
+ deleted, you would expect the application to throw an exception when
+ the button is clicked. Go
+ ahead and try it by running SampleApp (remember to use AppStart.exe)
+ and click the button in SampleApp.
+
+
+
What happened? It worked. In fact if you look in the 2.0.0.0
+ folder youll see that SimpleForm.dll has reappeared. So how did this happen? The CLR is fundamentally
+ programmable and extensible.
+ When the CLR could not find the SimpleForm.dll assembly,
+ instead of simply failing, it raised the AppDomain.AssemblyResolve
+ event. The .NET Application
+ Updater component hooks that event.
+ The .NET Application Updater component knows where a valid
+ copy of SimpleForm.dll resides; on the deployment Web server. It then downloads the assembly to
+ the local application directory and tells the CLR to try to load the
+ assembly again. The second
+ load attempt then succeeds.
+
+
+
On-Demand installation
+ is enabled and disabled via the AutoFileLoad property on the .NET
+ Application Updater component.
+ It is a powerful feature that can make the initial download
+ and install of your application tiny, but can be difficult to use
+ correctly. You must think
+ hard about where the assembly boundaries reside in your application
+ and what actions will cause an assembly to be downloaded. Because the assembly download
+ involves network I/O, it will take variable lengths of time to
+ download. During the assembly
+ download, the application is frozen waiting for the assembly
+ download to complete.
+
+
+
Deployment
+ Security
+
While the ability to
+ roll out application updates automatically has great benefits, it
+ also comes with an inherent danger.
+ When you make it easier to roll out updates, if not careful,
+ you could also make it easier to roll out malicious code. There are two dangers. The first danger is that someone
+ will spoof the Web server used to deploy updates with their own Web
+ server. They could then use
+ that Web server to roll out a virus in place of your
+ application. The easiest way
+ to prevent spoofing or any other tampering over the wire is to use
+ HTTPS. To use HTTPS with the
+ .NET Application Updater component, simply use HTTPS URLs in place
+ of HTTP URLs.
+
+
+
However, HTTPS is not a
+ silver bullet. There are two
+ problems with HTTPS. The first is scalability. Using HTTPS requires the server to
+ encrypt all of the files that are downloaded from the Web
+ server. If an application
+ update is large, the cost of encrypting the update can overburden
+ the server. The other issue
+ with HTTPS is that it does nothing to address the second security
+ danger. The second danger has
+ to do with your Web server being compromised, either from an insider
+ or from an outsider hacking your server. If your Web server is compromised,
+ its bad enough, but if it also means that a thousand clients are
+ also compromised via automatic updates, it could be disastrous.
+
+
+
To solve this problem,
+ the .NET Application Updater component uses the ability to strong
+ name a .NET assembly to verify the authenticity of the assembly upon
+ download. If the .NET
+ Application Updater detects that an assembly is not signed with your
+ applications key during download, the update is aborted. This means that only someone that
+ has the private key of your application can build updates that can
+ be automatically deployed.
+ .NET security is based on keeping your private key
+ secret. Even inside your own
+ organization, only the few select people should have access to your
+ private key.
+
+
To validate assemblies,
+ the .NET Application Updater component verifies that the public key
+ on the exe of your current installed application matches the public
+ key on downloaded updates.
+ The embedded public key can only be the same if the two
+ assemblies were signed with the same secret private key. Because the assembly is loaded by
+ the CLR in order to verify its public key, the CLR does its normal
+ hash value check to ensure the assembly is in fact a real assembly
+ and has not been tampered with.
+ If a verification check fails, it is treated just like any
+ other update failure. To
+ enable verification on download, simply strong name all of your
+ application assemblies and set the ValidateAssemblies property on
+ the .NET Application Updater component to True.
+
+
Assembly validation on
+ download works great, but in practice, applications will often have
+ components signed with different private keys. For example, your application may
+ have two files: The exe
+ assembly signed with your private key and a dll assembly that
+ contains a 3rd party charting control you purchased to
+ use in your application. This
+ 3rd party assembly may be signed with the 3rd
+ partys private key and not yours.
+ What makes it even more complicated is that the set of valid
+ private keys that can be used to sign assemblies in your application
+ could change from version to version. How do you auto-update these types
+ of applications? To solve
+ this problem, you create an assembly that contains a list of valid
+ public keys for your application.
+ Sign this assembly with the applications main private key
+ (the key that the exe of the application is signed with) and place
+ this assembly in the directory with the application update on the
+ Web server. Before the update
+ download process begins, the .NET Application Updater will check for
+ a well known assembly AppUpdaterKeys.dll in the application update
+ directory on the server. If
+ present, the assembly will be downloaded. The assembly will be verified
+ against the main application public key. If the signature is valid, the
+ list of keys will be extracted.
+ From that point on, any of the keys in that list will be
+ treated as valid signatures for the files in the update. The zip file that comes with this
+ paper contains an AppUpdaterKeys project that can be used to build
+ your own AppUpdaterKeys assembly.
+ The AppUpdaterKeys.dll also allows you to specify a set of
+ file exceptions. Files
+ specified as exceptions can be downloaded and updated without
+ passing the validation check.
+ This can be useful when your application contains
+ non-assembly files, such as pdb files for
+ debugging.
+
+
The recommended approach
+ to security is to use HTTPS URLs to perform update checks. This provides a first level of
+ spoofing protection. For
+ update download, its best not to use HTTPS URLs to avoid the
+ overhead on your Web server.
+ Instead, strong name your application assemblies and enable
+ the Validate Assemblies feature.
+
+
+
Extensibility and
+ Terrarium
+
In the sample we walked
+ through earlier in this paper we enabled auto-deployment in an
+ application simply by dropping a component into an application and
+ setting some properties.
+ While this works well for many applications, some
+ applications require a higher degree of control that can only be
+ achieved by writing code. The
+ .NET Application Updater component has an API that can be used to
+ customize and replace application update behavior. The .NET Terrarium game (http://www.gotdotnet.com/terrarium/)
+ I mentioned earlier is a heavy user of these extensibility
+ hooks. Lets take a look at
+ how Terrarium uses the .NET Application Updater components
+ extensibility mechanisms.
+
+
+
Terrarium uses a custom
+ XML Web service to check for updates. Terrarium hooks the
+ OnCheckForUpdate event of the .NET Application Updater component and
+ calls the XML Web service within this event handler. OnCheckForUpdate fires on the
+ poller thread. Thus the XML
+ Web service request is performed on a separate thread from the UI
+ thread and does not lock the UI.
+ The call to the XML Web service passes the assembly version
+ of the clients current Terrarium install. The XML Web service then decides
+ whether or not a newer update is available for that client. Two values are returned. The first indicates whether or not
+ an update is available. The
+ second is the URL where the update resides. For scalability reasons, in
+ practice, one server is used to check for updates and a separate
+ server is used to download updates.
+ On the return from the XML Web service call, if a new update
+ is available, Terrarium sets the UpdateUrl property of the .NET
+ Application Updater component to the URL returned from the Web
+ service. This instructs the
+ .NET Application Updater to use that URL for the next update
+ download. Finally, Terrarium
+ returns true in the OnCheckForUpdate event handler if an update is
+ available.
+
+
Terrarium also uses the
+ custom XML Web service to increase scalability. Updates to Terrarium exceed 10 MB
+ in size. Terrarium also
+ checks for updates very frequently.
+ Thus, in the beginning, when a new update was rolled out, it
+ wasnt uncommon to have hundreds of clients asking for updates at
+ once. This resulted in
+ Gigabytes worth of download requests and the server couldnt handle
+ the load. Moving away from
+ using HTTPS and decreasing the frequency of update checks helped the
+ situation, but the ultimate solution was to build some intelligence
+ into the XML Web service.
+ When the server is under load, the XML Web service only tells
+ the first X number of clients that an update is available. All of the rest are told that no
+ new update is available. The
+ next time the clients check for updates, the next X set of clients
+ are told an update is available.
+ In this way, the update is rolled out in waves and the server
+ is not overloaded.
+
+
+
Terrarium puts up its
+ own custom UI that integrates better with the overall
+ application. Thus Terrarium
+ disables the default .NET Application Updater UI. Terrarium hooks the
+ OnUpdateComplete event. The
+ OnUpdateComplete event includes a set of information, such as
+ whether or not the update was successful, what, if anything, caused
+ failure, and an English string with an explanation of the problem
+ that can be presented to the user.
+ The OnUpdateComplete event fires on the main UI thread of the
+ application. Thus Terrarium
+ raises UI to the user, informing them of update success or failure,
+ directly in the OnUpdateComplete event handler.
+
+
The .NET Application
+ Updater component also includes additional APIs that allow explicit
+ control over when actions like update checks and updates are
+ performed. These actions are
+ controllable via the CheckForUpdate () and ApplyUpdate() methods
+ respectively.
+
+
+
+
Debugging
+
The source code for the
+ .NET Application Updater component is provided so that you can debug
+ problems and add functionality as needed. However, before you dive too far
+ into the source code, this section will spell out some first level
+ debugging options, as well as describe the most frequently
+ encountered problems by consumers of this component.
+
+
The .NET Application
+ Updater creates a hidden log file named AppUpdate.log that resides
+ in the same directory as AppStart.exe. All successful and failed updates
+ are recorded in this log. The
+ log file is especially useful when there is a particular client
+ machine that wont update successfully. You can use the log to determine
+ when and how the update failed.
+ In addition, the .NET Application Updater component uses the
+ Debug class of the .NET Framework to write out a lot of useful
+ information. If you run your
+ application in the debugger, you will see this information in the
+ output window. You can
+ essentially watch the .NET Application Updater go through its update
+ steps and see where the problem is occurring.
+
+
If for whatever reason,
+ you just cant get the .NET Application Updater to work, make sure of
+ the following before you debug too far, more than likely one of
+ these is the problem you are encountering:
+
+
+ - Do you have IIS
+ Directory Browsing turned on?
+ If not, the downloader will see an empty directory on the
+ Web server where the update resides. The updater will then download
+ and install an update of zero files, leaving you with the original
+ unchanged application. See the Setting up the Web server section
+ earlier in this paper for instructions on how to enable Directory
+ Browsing.
+
- Do you have everything
+ deployed correctly and the correct URLs set? Its easy to make a mistake
+ here. Look at the URLs
+ being output by the .NET Application Updater when running in the
+ debugger. Navigate to these
+ URLs in the browser and make sure they are
+ valid.
+
- If your app is
+ installed in the program files directory, are you an admin or
+ power user on the box? If
+ not, you wont have the write access necessary to update the
+ application.
+
- Did you create the
+ AppUpdater object on the main UI thread of the application? If not, the updater will not be
+ able to present UI and will fail when firing events back to the UI
+ thread.
+
- Is the update
+ succeeding, but the app failing to automatically restart to pick
+ up new updates? The .NET
+ Application Updater component attempts to restart the application
+ by calling the Application.Exit method. However, that method is not
+ guaranteed to shut down an application. If you spawn & leave
+ separate threads running, it will not close the process. The solution is to ensure that
+ all threads are terminated via the Application.OnExit event, or
+ hook the .NET Application Updaters OnUpdateComplete event and
+ handle the shutdown yourself.
+
+
+
Summary
+
Ease of deployment for
+ client applications was a major goal for the first version of the
+ .NET Framework. There is no
+ other technology for building client applications that addresses the
+ deployment problems as well as the .NET Framework. Ease of deployment will continue
+ to be a major goal for future versions of the .NET Framework. The .NET Application Updater
+ component described here represents some of our thinking in terms of
+ scenarios we would like to enable directly in future versions of the
+ .NET Framework. However,
+ until that time the .NET Application Updater component is a great
+ way to get started building auto-updating applications.
+
+
+
+