C# City

In a previous post, we discussed the basics of Microsoft’s Updater block from their Enterprise Library: that clients connect to a server, pull XML files describing updates (files to update and an execution script/task to execute), grab those updates passively via BITS, and then download and execute updates.

As promised, this post will describe how to include multiple updates in a single manifest file.

The key here is really to understand that manifest files and refer to other manifest files. This means we have a master/index manifest file, which links all the update manifests.

Conceptually, you can have recursive manifests, nested manifests, or a tree/graph of manifests (with an unlimited amount of nesting, as far as I can tell). And in terms of performance, only new manifests are downloaded, so you don’t need to worry about a performance hit.

Our previous manifest looked like this:

<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" manifestId="{9DBCD243-0479-4dd2-883B-8DA46FC3FCA9}" mandatory="False" xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
  <description>New software update</description>
  <application applicationId="{225E1AD7-8ABA-432f-A942-24BACA556850}">
  <!-- Path relative to <location /> of the app to launch for this update -->
    <entryPoint file="SimpleApplication\1.0.0.0\SimpleApplication.exe" parameters="" />
  <!-- Local path to store the downloadad file. Creates if necessary. -->
    <location>C:\Temp\Updater\</location>
  </application>
  <files base="http://localhost/MyAwesomeUpdateServer" hashComparison="No">
  <!-- Place on the remote server where we store the file -->
    <file source="SimpleApplication\1.0.0.0\SimpleApplication.exe" transient="No" />
  </files>
  <activation>
    <tasks>
      <task type="Microsoft.ApplicationBlocks.Updater.ActivationProcessors.ApplicationDeployProcessor, Microsoft.ApplicationBlocks.Updater.ActivationProcessors" name="ApplicationDeployProcessor" />
    </tasks>
  </activation>
</manifest>

Let’s rip out and stub out tasks and files, and instead, put them into a child manifest called update1.xml. This file will look like:

<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" manifestId="{9DBCD243-0479-4dd2-883B-8DA46FC3FCA9}" mandatory="False" xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
  <description>New software update</description>
  <application applicationId="{225E1AD7-8ABA-432f-A942-24BACA556850}">
  <!-- Path relative to <location /> of the app to launch for this update -->
    <entryPoint file="SimpleApplication\1.0.0.0\SimpleApplication.exe" parameters="" />
  <!-- Local path to store the downloadad file. Creates if necessary. -->
    <location>C:\Temp\Updater\</location>
  </application>
  <files base="http://localhost/MyAwesomeUpdateServer" hashComparison="No">
  <!-- Place on the remote server where we store the file -->
    <file source="SimpleApplication\1.0.0.0\SimpleApplication.exe" transient="No" />
  </files>
  <activation>
    <tasks>
      <task type="Microsoft.ApplicationBlocks.Updater.ActivationProcessors.ApplicationDeployProcessor, Microsoft.ApplicationBlocks.Updater.ActivationProcessors" name="ApplicationDeployProcessor" />
    </tasks>
  </activation>
</manifest>

Now that we have encapsulated our update into its own manifest, let’s update the original manifest to reference this one:

<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" manifestId="{11BCD243-0379-4cd2-883A-8D946FC3FBA1}" mandatory="False" xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
  <description>New software update</description>
  <application applicationId="{215E1AD7-9ABA-432f-A952-24BABA556850}">  
    <entryPoint file="" parameters="" />
    <location>C:\Temp\Updater\</location>
  </application>
  <files base="http://localhost/MyAwesomeUpdateServer" hashComparison="No" />
  <includedManifests>
    <manifest location="update1.xml" manifestId="{11BCD243-0379-4cd2-883A-8D946FC3FBA1}" />
  </includedManifests>
</manifest>

You’ll notice the <includedManifests> section, which references our update1.xml manifest. Great!

That’s it! If you wanted to add another update, simply create an update2.xml (or whatever you want to call it), and add another <manifest ... /> to your master/index manifest file to reference it.

One caveat: The Updater block uses manifest IDs to tell if a manifest has changed. The updater is smart enough to know if the original file has additional referenced files, even if the ID hasn’t changed. So you just need to add the new manifest, and you’re golden.

Simple as that!

Part of Microsoft’s Enterprise Library is an Updater block. It’s not really clear from the MSDN introduction page what this is and how it works.

Essentially, it’s code that works like Windows Update. How does it work? At a high level:

1. Your computer (client) connects to the Windows Update machine with the updates (server)
2. The client asks: What new updates are there for me?
3. The server sends: Here’s a list of updates.
4. The client downloads each update (when bandwidth is available)
5. The client activates each update

As you can see, it’s a server-client architecture. One of the immediate benefits is that it uses pull, not push — meaning if your client is behind corporate firewalls, you can still deliver updates. But like all pull technology, you can’t guarantee when (or even if) updates will happen.

Let’s drill into some details.

Under the Hood: How Updates Work

How exactly do we encapsulate this notion of an update? What exactly is an update?

In the Updater block, an update is essentially a file you want to deliver to the client, with a possible execution action.

• A file can be any file — a ZIP file, an EXE file, a batch file, text file, doc file, or anything else.
• An execution action is any action you can run. For example, you can invoke Internet Explorer, or 7-Zip; you can run your downloaded EXE or batch file; or open your downloaded text file in Notepad.

All of this information is collected into a “manifest” XML file on the server. Here’s a sample of an update that downloads SimpleApplication.exe into C:\Temp\Updater and then executes it:

<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" manifestId="{9DBCD243-0479-4dd2-883B-8DA46FC3FCA9}" mandatory="False" xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
  <description>New software update</description>
  <application applicationId="{225E1AD7-8ABA-432f-A942-24BACA556850}">
  <!-- Path relative to <location /> of the app to launch for this update -->
    <entryPoint file="SimpleApplication\1.0.0.0\SimpleApplication.exe" parameters="" />
  <!-- Local path to store the downloadad file. Creates if necessary. -->
    <location>C:\Temp\Updater\</location>
  </application>
  <files base="http://localhost/MyAwesomeUpdateServer" hashComparison="No">
  <!-- Place on the remote server where we store the file -->
    <file source="SimpleApplication\1.0.0.0\SimpleApplication.exe" transient="No" />
  </files>
  <activation>
    <tasks>
      <task type="Microsoft.ApplicationBlocks.Updater.ActivationProcessors.ApplicationDeployProcessor, Microsoft.ApplicationBlocks.Updater.ActivationProcessors" name="ApplicationDeployProcessor" />
    </tasks>
  </activation>
</manifest>

You can see a couple of things from this file:

• A description of what this update contains
• An application that we’re providing as an update (SimpleApplication.exe)
• The script to execute when the update completes (<entryPoint ... />)
• The location to download the update to (C:\Temp\Updater)
• The location on the server where we can grab the file from (http://localhost/MyAwesomeUpdateServer)
• The exact path of the remote file to download (files base plus file source)

That’s really (surprisingly) all there is to it. When you run the updater, it will download this file; if it hasn’t run this update before (successfully), it will download and execute http://localhost/MyAwesomeUpdateServer/SimpleApplication/1.0.0.0/SimpleApplication.exe into E:\temp\Updater\SimpleApplication\1.0.0.0.

That’s really it. The update is queued and executed later. The next time you run the updater, it’ll check again for any new files in the manifest, and download any new updates.

Server-Side Stuff: IIS

On the server side, you need to actually host the manifest file somewhere where clients can access it. If you’re doing everything locally (and even if you’re not), the easiest way to do this is add a virtual directory to IIS to host the manifest file and the update files.

In our example, we’ll have the virtual directory MyAwesomeUpdateServer somewhere; it will have inside a manifest.xml file, along with the SimpleApplication.exe file under MyAwesomeUpdateServer\SimpleApplication\1.0.0.0.

I’m sure this can work with Apache or any other web-server, but I leave that as an exercise to you.

How Transferring Works: BITS

BITS, which evolved out of Windows Updater, is a smart downloader. If your maximum download speed is 100kb/s, and you’re currently downloading at 90kb/s, it will utilize only the remaining 10kb/s to download the updates. BITS also handles resuming downloads (even across client reboots), and some other stuff; you can read more about it here, at MSDN.

How do you add updates for multiple applications, and multiple updates per application? That’s beyond the scope of this article, so until next time! (Actually, that’s beyond the scope of my knowledge at this time, so when I figure it out, I’ll post another post about it.)