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. 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.