Click Once Deployment Process and Issue Resolution
- by Geordie
Introduction
We are adopting Click Once as a deployment standard for Thick .Net application clients. The latest version of this tool has matured it to a point where it can be used in an enterprise environment. This guide will identify how to use Click Once deployment and promote code trough the dev, test and production environments.
Why Use Click Once over SCCM
If we already use SCCM why add Click Once to the deployment options. The advantages of Click Once are their ability to update the code in a single location and have the update flow automatically down to the user community. There have been challenges in the past with getting configuration updates to download but these can now be achieved. With SCCM you can do the same thing but it then needs to be packages and pushed out to users. Each time a new user is added to an application, time needs to be spent by an administrator, to push out any required application packages. With Click Once the user would go to a web link and the application and pre requisites will automatically get installed.
New Deployment Steps Overview
The deployment in an enterprise environment includes several steps as the solution moves through the development life cycle before being released into production. To make mitigate risk during the release phase, it is important to ensure the solution is not deployed directly into production from the development tools. Although this is the easiest path, it can introduce untested code into production and result in unexpected results.
1. Deploy the client application to a development web server using Visual Studio 2008 Click Once deployment tools. Once potential production versions of the solution are being generated, ensure the production install URL is specified when deploying code from Visual Studio. (For details see ‘Deploying Click Once Code from Visual Studio’)
2. xCopy the code to the test server. Run the MageUI tool to update the URLs, signing and version numbers to match the test server. (For details see ‘Moving Click Once Code to a new Server without using Visual Studio’)
3. xCopy the code to the production server. Run the MageUI tool to update the URLs, signing and version numbers to match the production server. The certificate used to sign the code should be provided by a certificate authority that will be trusted by the client machines. Finally make sure the setup.exe contains the production install URL. If not redeploy the solution from Visual Studio to the dev environment specifying the production install URL. Then xcopy the install.exe file from dev to production. (For details see ‘Moving Click Once Code to a new Server without using Visual Studio’)
Detailed Deployment Steps
Deploying Click Once Code From Visual Studio
Open Visual Studio and create a new WinForms or WPF project.
In the solution explorer right click on the project and select ‘Publish’ in the context menu.
The ‘Publish Wizard’ will start. Enter the development deployment path. This could be a local directory or web site. When first publishing the solution set this to a development web site and Visual basic will create a site with an install.htm page. Click Next. Select weather the application will be available both online and offline. Then click Finish.
Once the initial deployment is completed, republish the solution this time mapping to the directory that holds the code that was just published. This time the Publish Wizard contains and additional option.
The setup.exe file that is created has the install URL hardcoded in it. It is this screen that allows you to specify the URL to use. At some point a setup.exe file must be generated for production. Enter the production URL and deploy the solution to the dev folder. This file can then be saved for latter use in deployment to production. During development this URL should be pointing to development site to avoid accidently installing the production application.
Visual studio will publish the application to the desired location in the process it will create an anonymous ‘pfx’ certificate to sign the deployment configuration files. A production certificate should be acquired in preparation for deployment to production.
Directory structure created by Visual Studio
Application files created by Visual Studio
Development web site (install.htm) created by Visual Studio
Migrating Click Once Code to a new Server without using Visual Studio
To migrate the Click Once application code to a new server, a tool called MageUI is needed to modify the .application and .manifest files. The MageUI tool is usually located – ‘C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin’ folder or can be downloaded from the web.
When deploying to a new environment copy all files in the project folder to the new server. In this case the ‘ClickOnceSample’ folder and contents. The old application versions can be deleted, in this case ‘ClickOnceSample_1_0_0_0’ and ‘ClickOnceSample_1_0_0_1’.
Open IIS Manager and create a virtual directory that points to the project folder. Also make the publish.htm the default web page.
Run the ManeUI tool and then open the .application file in the root project folder (in this case in the ‘ClickOnceSample’ folder).
Click on the Deployment Options in the left hand list and update the URL to the new server URL and save the changes.
When MageUI tries to save the file it will prompt for the file to be signed.
This step cannot be bypassed if you want the Click Once deployment to work from a web site. The easiest solution to this for test is to use the auto generated certificate that Visual Studio created for the project. This certificate can be found with the project source code. To save time go to File>Preferences and configure the ‘Use default signing certificate’ fields.
Future deployments will only require application files to be transferred to the new server. The only difference is then updating the .application file the ‘Version’ must be updated to match the new version and the ‘Application Reference’ has to be update to point to the new .manifest file.
Updating the Configuration File of a Click Once Deployment Package without using Visual Studio
When an update to the configuration file is required, modifying the ClickOnceSample.exe.config.deploy file will not result in current users getting the new configurations. We do not want to go back to Visual Studio and generate a new version as this might introduce unexpected code changes. A new version of the application can be created by copying the folder (in this case ClickOnceSample_1_0_0_2) and pasting it into the application Files directory. Rename the directory ‘ClickOnceSample_1_0_0_3’. In the new folder open the configuration file in notepad and make the configuration changes.
Run MageUI and open the manifest file in the newly copied directory (ClickOnceSample_1_0_0_3).
Edit the manifest version to reflect the newly copied files (in this case 1.0.0.3). Then save the file. Open the .application file in the root folder. Again update the version to 1.0.0.3. Since the file has not changed the Deployment Options/Start Location URL should still be correct. The application Reference needs to be updated to point to the new versions .manifest file. Save the file.
Next time a user runs the application the new version of the configuration file will be down loaded. It is worth noting that there are 2 different types of configuration parameter; application and user. With Click Once deployment the difference is significant. When an application is downloaded the configuration file is also brought down to the client machine. The developer may have written code to update the user parameters in the application. As a result each time a new version of the application is down loaded the user parameters are at risk of being overwritten. With Click Once deployment the system knows if the user parameters are still the default values. If they are they will be overwritten with the new default values in the configuration file. If they have been updated by the user, they will not be overwritten.
Settings configuration view in Visual Studio
Production Deployment
When deploying the code to production it is prudent to disable the development and test deployment sites. This will allow errors such as incorrect URL to be quickly identified in the initial testing after deployment. If the sites are active there is no way to know if the application was downloaded from the production deployment and not redirected to test or dev.
Troubleshooting
Clicking the install button on the install.htm page fails.
Error: URLDownloadToCacheFile failed with HRESULT '-2146697210' Error: An error occurred trying to download <file>
This is due to the setup.exe file pointing to the wrong location.
‘The setup.exe file that is created has the install URL hardcoded in it. It is this screen that allows you to specify the URL to use. At some point a setup.exe file must be generated for production. Enter the production URL and deploy the solution to the dev folder. This file can then be saved for latter use in deployment to production. During development this URL should be pointing to development site to avoid accidently installing the production application.’
