Recently, I have helped one of our clients with ClickOnce deployment. Part of the system that our client sells consists of application servers that have a .Net web service, and a smart client application. We helped our client improve the architecture of the web service and the Smart Client application to support extensibility for customizations specific to their customers. These customizations are out of the scope of this post, but during this re-architecture, the technology base was upgraded from VS 2003 & .Net 1.1 to VS 2005 and .Net 2.0.
The extensibility, plug-in and pipelining portions of the project went over very well. We did however face an unforeseen complexity: ClickOnce Deployment. We had done our fair share of reading on the benefits of ClickOnce and had read some of the deeper technical articles, that all focused on ClickOnce deployment from the web server to the client. The benefits seemed great on paper, even though there are issues with Xbrowser support that quickly rear their head. Also, there seems to be a lack of documentation around actually getting the server portion of ClickOnce installed, and that is what this post focuses on.
ClickOnce deployment has two very important files: the application manifest that defines what files make up the application and the deployment manifest that has the deployment version information and the path (the ProviderURL) for the ClickOnce application to look for updates from. These manifests are signed and this leads to a very tough issue to get around: how can you have a setup package that contains a deployment URL that you do not know ahead of time?
Our client sells their web applications to many customers. These servers are all imaged with Windows Server 2003 and the .NET framework 2.0. Then a deployment team installs the web service and ClickOnce application on the server via an MSI setup package. In the field, servers are always added to server farms to increase capacity. The need for quick setup of machines via a setup package is required.
The nature of the client application that we built, includes dynamically loaded assemblies in order to support customizations of the core application. This scenario is not covered by the “right click -> deploy” ClickOnce deployment method in Visual Studio or MSBuild. When using MSBuild /deploy, the ClickOnce setup package only consists of statically linked assemblies.
What we did was prepare a nAnt script for the build team to use, which creates the proper setup program, including dynamically linked files and additional files needed for server setup. The setup program itself is created via a Web Setup project in Visual Studio.
The nAnt script that we created performed the following steps:
- Get files from source safe and label
- Update all assembly info files with version information (remember that the assembly version is not what is used by ClickOnce to determine if there is a new version to download, the deployment manifest is used for that purpose)
- Build all of the assemblies that are statically and dynamically linked.
- Create the application manifest using Mage.exe, linking all of the statically and dynamically linked assemblies
- Create the deployment manifest and version it with Mage.exe – ensure that the deployment provider URL points to an invalid host name
- Sign the Deployment and Application manifests with a certificate that is not issued by a certificate authority
- Copy all of the files that are needed into a temporary build area with the Web Setup Project
- Update the default web page with version information
- Include a vbscript that is invoked during the install that will update the manifests (more on this later)
- Invoke the Web Setup package via devenv (you need Visual Studio 2005 installed on the build machine)
After the NAnt script is run, there will be a setup.exe and MSI install package for your ClickOnce server deployment. In this package a dummy certificate is included and a vbscript for updating the deployment and application manifests.
In the Web Setup project we configured the vbscript to run during the server install. The vbscript prompts the user to input the URL that will be used for ClickOnce client updates. This URL is then used to update the deployment manifest with the new deployment URL. The prompt also tells the installer that they should point to the load balanced hostname or as opposed to the specific server IP or hostname. The vbscript invokes mage.exe to perform this step. Mage.exe is part of the .Net Framework 2.0 SDK and must also be deployed with the setup project.
mage.exe -Update myclickonceapp.application -ProviderUrl http://myserverhostname/myclickonceapp
The installer then prompts for a path to the certificate to sign with. Customers can use their own certificate to sign the application manifests with, or they can use the unsecured dummy certificate that is included in the setup package.
mage.exe -Sign myclickonceapp.application -CertFile somecertificate.pfx -Password somepassword
Next the installer vbscript must update the bootstrapper that is used to install the prerequisites. This step is needed because the bootstrapper itself will invoke the ClickOnce application after it installs the prerequisites. Note, that there are even issues around this if the client browser is not IE. There are some very good work arounds for ClickOnce Firefox issues discussed over on the Microsoft Channel 9 forums.
setup.exe /url= http://myserverhostname/
After this is complete, the vbscript is left on the server in case if the user wants to update the deployment URL after setup.
This build and installation has worked very well for us, but you do need to at least provide instructions on the setup web page for Firefox users on how to properly install the application, or follow some of the work arounds detailed on the Microsoft Channel 9 Forums.
I hope this helps
-Jon
