Your first ClickOnce app

So if you haven’t had time to try out ClickOnce yet, now is the time! Here is a quick example of how simple it is and how it works.

First, the client machine will have to have the Whidbey bits installed. There is bootstrap capability where you can deploy the framework and pre-requisites first before deploying the app, but I’ll cover that in more detail at some point in the future.

Step 1: Build a Windows Form app in VS.NET Whidbey. Doesn’t have to be a work of art, just drag a couple controls on a form so you can convince yourself that when it runs, it is your app.

Step 2: Go to the project menu and select Publish Project. This brings up the Publish wizard. This helps you set a few values that will let VS.NET generate the application and deployment manifest files for you and puts them out on your web server along with the app files so that you can test them out. The first is the URL on your web server at which you want to publish the application files. The second is whether you want the app to be available offline or not.

If a virtual directory does not exist at the location you specify, one will be created by VS.NET. It then pushes all the build outputs for the project to a subfolder in that virtual directory that will contain the name of the app and its version. In this way, multiple versions can be deployed and supported from the same deployment location.

The two key files it creates are the application and deployment manifests. These are both XML files containing the info that the runtime needs to figure out how and what to deploy to the client machine. The application manifest contains info about what constitutes the application. The deployment manifest dictates what gets deployed. I’ll get into details on the contents of these buggers in future posts.

Step 3: Bottom line is that once published, all you need to do is provide a URL to a client that points to the .deploy (deployment manifest) file in the virtual directory you specified, and you are off and running. Really you provide a path – that path can be a URL, file share, or UNC path to where that .deploy file lives.

When the user clicks once on the link or shortcut (thus the name), the runtime on the client machine will download the .deploy file and read its contents to determine where the app manifest is. From that it will figure out what to download. If the deployment info indicates that the app is to be available offline as well as online, a shortcut to the app is placed in the All Programs menu in the Start menu, and the app will download and launch. From that Start menu item you can launch the app whether online or offline in the future. Otherwise, the app will just launch and you will have to use that same shortcut or link and be online to launch the app again in the future.

The app will run in a security sandbox on the user’s machine either way that is determined by the location from which the app was downloaded by default. You can also include information in the application manifest that indicates the required security permissions for the app. In VS.NET you do this by going into the project properties, and look for the new Security section under Configuration Properties. There is also a mechanism with ClickOnce to deploy security policy from a trusted source that I will cover in a future post.

That is all there is to it.

A couple of gotchas to be aware of in the alpha:

– Close the browser window that pops up when you publish after testing and before publishing another version. If you leave it open (even if you refresh) and publish a new version, it will be caching stale deployment info and youwill not get the new version deployed.

– Your machine has to have a valid network connection for the deployment to work. No connection, no deploy, exception, no fun. This is an alphaism. ClickOnce also supports deployment from local media such as disk or CD, so obviously you shouldn’t need a network connection to deploy or test a deployment on the local machine. Hopefully this will be cleaned up by beta 1.

– The security tab in the Project settings only lets you select preconfigured security code groups. There is a big ugly empty listbox below it that in the future will contain individual permissions that you can use to customize exactly what the application requires.

That’s it for now. Expect more fun facts about ClickOnce in the future.