It was around end off November 2014 when I decided to pick up my old code base from the Silverlight version of the game and see if I could make a universal app out of it. I had tried a few other test apps but I felt that the touch capabilities of windows 8.1 were perfect for a game like Hexpand.

It was also an opportunity to review the game mechanics and make a game with less micromanagement and more emphasis on the strategy. This would require a better AI which could handle Soldier movement for the player and that was in itself an interesting challenge. I could finally use my Uni studies on path-finding algorithms!

By the end of Jan 2015 I had a prototype with one hard-coded level and a simplistic AI that could move the soldiers and was only able to create one flag every turn. It wasn’t much of a game but all of a sudden Hexpand was actually semi enjoyable. At that moment it became clear to me that it just needed the rest of the components in place in order to reach it’s full potential.

So I pushed forward. I had to create a few different maps and teach the AI how to build towers and spawn soldiers. Those were the minimum requirements in order to have a functional game worth publishing.

The progress was slow. It is hard to work on a project like this while having a full time job. Mental fatigue eventually will catch up on you and it is difficult to maintain the level of motivation you need to get stuff done.

Sometimes we need to trick our minds in order to keep things going and luckily Windows Apps London gave me the perfect excuse. They organised a one day Submit-It hackathon. Everyone participating had to complete an app that they were working on and submit it on the day.

Off course one day is not enough to finish anything of this scale unless you are almost there already. But that gave me a hard deadline. The game had to be ready for the first release by the day of the hackathon. I even took a week off from work just before that Saturday but on 18th of April 2015 Hexpand was finally on the store!

The easiest way to provide basic auto updates, without having to alter the code of your application is probably ClickOnce

You still have to double-click.

The way it works is simple. All you have to do is to copy the files that your project needs to run (executable, dlls, configs etc) to a folder accessible from your end users along with 2 files, an application manifest and a deployment manifest. You can use a shared folder if your deployment is within a corporate environment or a web server for a broader audience.

All your users need in order to install your software is a link to the deployment manifest file, with the extension .application, and to have .Net already installed on their machines. After that first installation ClickOnce will check the deployment location and if there is a new version it will interact with the user in order to install it.

Of course you don’t want to do all these steps manually every time you make an update to your code. That’s what we have a build server for, right?

How to create the manifests

The easiest way I found to automatically generate the manifests was with the use of Mage.exe, a command line tool provided by Microsoft specifically for that purpose.

The first thing you need to do is to create a new build configuration for the deployment of your project. Add the necessary build steps to build a release version of your application and to run all the unit and integration tests. Then add two more steps: one to create the application manifest and one to create the deployment. Both steps need to execute mage.exe with the appropriate command line arguments for each manifest file.

An example for the application manifest on TeamCity would look like this:

The ProviderUrl can be a shared folder instead of a URL like the one above as long as your users have access to it. Installation of an application is supported over file://, http:// and https:// protocols.

Note that we use TeamCity’s variable %build.number% as the product’s version. By formating the build version of this build configuration to something like:

Build number format: 1.0.0.{0}

We can ensure that the version is auto incremented every time we run this build.

How to copy the files to the deployment location

This is the easy part. All we need to do at this stage is to add a last step that will copy those files to the appropriate location accessible by the ProviderUrl mentioned above. If that is a shared folder all we need is to use the copy command passing the from and to directories. Make sure you copy everything from the Release folder that was included in the application manifest.

Here is an example of that last step where we have to copy our files to a remote linux server using PuTTY secure copy:

And that’s it! You now have implemented auto-updates for your application!

Complicating things

So far we have seen how easy it is to setup auto-updates with ClickOnce. Once you start using it though you will soon find out that there are a few complications down the line that may or may not affect you depending on the auto-update requirements of your application. In any case it is better to consider a few things in advance.

Decide the right update-strategy

ClickOnce will check for updates of your application in predefined instances like before the application starts, after it starts and in specified intervals. If a new version is found it will ask the user whether it should install the new version or not.

This approach is sufficient when your updates are optional. However it becomes trickier to enforce important updates, like security fixes, breaking changes to remote APIs etc. The only way you can achieve that is to require ClickOnce to check for updates before the application starts and mark each update as necessary by specifying a minimum required version in the deployment manifest. Here is an example of a build-step in TeamCity that adds that requirement to the manifest which was created in a previous step:

Make sure all prerequisites are installed

ClickOnce is part of .NET, therefore if .NET is not already on your user’s machine, your user can not install your application either. Remember that the MyProject.application file is just an xml manifest. Without ClickOnce your user’s machine can not make any sense of it. But even if there is a version of .Net already installed you need to make sure that it is one your application is compatible with.

To address this issue you can provide an additional setup.exe file which will install all the prerequisites of your application, like .NET for example, and then use the manifest to install the application itself. This file is called a “bootstrapper” and you can automate the creation of it using MSBuild tasks. You can find more information in how to generate a bootstrapper task and how to create bootstrapper packages.

Server and Client issues

As we mentioned already, ClickOnce applications can be distributed over http by providing a web page with a link to the deployment manifest file, the one with the descriptive extension “application”. The end users just need to click (once) on the link and .NET runtime will get them through the installation process.

However that behaviour is available only if the link is accessed using Firefox with a special Microsoft add-on installed or IExplorer. In any other case the end user just gets a prompt to download the file instead at best or a new web page with the xml content of the file at worst. To avoid the later you need to make sure you have setup the server correctly to include the relevant mime types for .application and .manifest extensions.

You also might want to consider checking the available .NET version on your user machine and provide a link to either the .application file or the setup.exe that we mentioned earlier. This is not as trivial as it might seem though (see a discussion on StackOverflow).

Sign your deployments and more

Every time a user is trying to install your ClickOnce application will get a warning that your application is not signed (therefore not safe in the eyes of your users). This can be ignored when the deployment is within the same organization but is a serious concern when the application is distributed over the Internet for example.

To avoid that you will have to purchase a certificate and add yet another step to sign each deployment manifest. Here are the sign command options for the Mage.exe tool.

Conclusion

ClickOnce is an easy way to introduce auto-updates to your application but has some limitations. If your requirements allow you to operate within those limitations then you need to look no further. Otherwise you might need to consider an alternative approach that we will discuss at the next part

Once you have specified the auto-update requirements for your application you need to decide what will be the architecture of the auto-update solution. This post offers an overview of the most common options you might want to consider.

We assume in this series of articles that updating your application involves replacing part of the executable code among other things. The reason why you can’t do that directly from within your application’s process is that since Windows XP the OS doesn’t allow an executable file to be deleted (or replaced) while it is running. There are some techniques to bypass that limitation and you can still rename the locked file and come up with some clever way to restart the application from a different executable, but we are not going to talk about those here. Our focus is on methods that you can use to provide auto-update functionality without having to implement everything from scratch.

There are generally 3 common approaches to update your executable files based on which process initiates an update of your application:

1. Using an installer

In this approach your application initiates an external process to do the update and then terminates allowing that process to replace all the necessary files. The external process could be a custom executable which is part of the installation or more likely the Windows Installer itself.

Most applications that require a full installation would use this approach. It is probably the most flexible way to distribute an application and allows you to have finer control of when to check for an update and how to install it. Of course the extra flexibility comes at the cost of having to implement part of the update process inside the application itself, like checking for new versions and notifying the users. Luckily there are a few open source frameworks that handle some of that complexity for you. We will talk more about these in Part 4.

2. Using a bootstrapper*

A “bootstrapper” is a process that will always run before your application and will do all that is necessary to keep it updated, like check for latest versions and run a new installation. Once it has finished it’s tasks, it then executes the actual application.

There are 2 variations of the bootstrapper approach. One that you provide your custom bootstrapper with your installation and one that you use a system-wide bootstrapper service like ClickOnce.

The first, where you provide a custom bootstrapper, is similar to the custom installer that we mentioned above. You need to implement all the logic for updating the application and come up with a mechanism to update the bootstrapper itself. Again you have the full control of the whole update process, however this is beyond the scope of these articles.

In the next post we will go through the second variation and in particular the use of ClickOnce which is probably the easiest way for C# developers to implement auto-updates as it provides a complete solution “out of the box”. ClickOnce will always run before your application and take care of it’s auto-update requirements as they are specified in the deployment manifest without having to add a single line of code to the executable. Of course there are some limitations but for most cases, especially for enterprise software and applications that are going to be distributed only within the same organisation, ClickOnce is the logical first choice.

3. Using a service

In certain scenarios you might want to consider using a service that will monitor the current installation and check for updates periodically or when triggered by specified events. The benefit of the service is that it can keep your application updated even if it has not been used by the user for a while. It is also useful in cases where you don’t want to invoke a check for updates when the application is executed for performance or other reasons and you need the update process to be completely decoupled.

Again, this method requires a complete custom solution and we are not going to discuss about it in any further detail here.

Which approach is better?

There is no right answer to this question, it depends on the requirements of your specific application. In most common scenarios however it is likely that you will have to chose between 1 and 2, an installer or a bootstrapper. If you can narrow down your options between Windows Installer and ClickOnce then it is worth going through this article provided by Microsoft first, before you make your decision.

In the following posts we will go through those two solutions, starting with the simpler one which is ClickOnce.

* (Note: We use the term bootstrapper liberally to describe the whole process that precedes the execution of our application in order to check for updates and thus prepare the application to run. Not to be confused with the Bootstrapper Packages that are used by ClickOnce to describe the prerequisites of an application before installation, or setup.exe which is used as the bootstrapper of a ClickOnce installation, by installing those prerequisites.)