Configuring a ClickOnce Deployment

Configuring a ClickOnce Deployment

If you wish to follow along with the demonstration below, you will need to make sure you have Visual Studio 2008 with SP1 installed. First, open VS 2008 SP1 and create a new Windows Forms project. Right click on the project file in Solution Explorer, choose Properties, and navigate to the Publish tab. Now, let's look at the different option menus and configurations ClickOnce offers. Click the "Options…" button on the Publish tab. The Publish Options dialog contains four sections (Description, Deployment, Manifests, File Associations), each described below.

Publish Options: Description

Click here for larger image

The following table illustrates where each property is used:

Click here for larger image

Publish Language was excluded from this list as it has to do with multi-lingual/multi-cultural applications. It controls the language setting in the application's deployment manifest. For example, the following entry is from a manifest with German set as the Publish Language. Note this does not override the cultural settings of your application. It also does not necessarily control the language in which the installation dialogs will be presented; this is determined by the OS settings and the language packs for .NET that are installed on the user's machine. Setting the Publish Language will ensure that the localized files in your application that pertain the language you selected will be included by default in the list of application files to be deployed.

<asmv1:assemblyIdentity version="1.0.0.3" name="ClickOnce Demo.exe" 
publicKeyToken="056bfb40ce3cb353" language="de" 
processorArchitecture="msil" type="win32" />

Publish Options: Deployment

Click here for larger image

The five options under the Deployment section are:

1. Automatically generate deployment web page after every publish: This option is useful when debugging your ClickOnce deployment. Choosing it will instruct VS to create a default web page from which you can launch the ClickOnce installer each time you publish your application.
2. Open deployment web page after publish: This option will instruct VS to launch the web page it creates (if you have checked the first option) each time you publish your application.
3. Use .deploy file extension: VS will append a ".deploy" file extension on your assemblies, both .exe and .dll. Unless you are deploying in a controlled environment where you know security policies and firewalls won't interfere with downloading .exe and .dll files it is better to leave this option checked. This will allow the web server administrators to continue blocking .exe and .dll mime types and still let ClickOnce installation succeed.
   • NOTE: When using the ".deploy" extension and web site installations be sure to add the extension to the mime types list in IIS so that the files don't get blocked on transfer. If you start getting File Not Found errors during deployment, this is one of the first places to look (right after you check to make sure the files are indeed there, of course).

   Here are the files generated with the ".deploy" extension option:

   
   
   Click here for larger image

   
   Listing 1.4 Generated files with the "Use .deploy file extension option

   Here are the files generated without the ".deploy" extension option:

   
   
   Click here for larger image

   
   Listing 1.5 Generated files without the "Use .deploy file extension option

4. For CD installations automatically start Step when CD is inserted: This option is fairly straight forward; think "Autorun" for ClickOnce. This is a user convenience option to use if you will be deploying via CD.
5. Verify files uploaded to a web server: This option is important when deploying a published package out to a server for production. This will not do much for you when running or testing locally, but it is important when a network connection, security, and permissions come into play in a production environment.

Publish Options: Manifests

Click here for larger image

1. Block application from being activated via a URL: This option controls whether or not the application can be launched from a URL call. If this box is checked, the application will be required to launch from the Start menu. Additionally, disabling this option allows the application to start automatically after installation.
2. Allow URL parameters to be passed to application: This option enables the application to accept URL parameters. The parameters are then stored in the ActivationUri object to be retrieved in the application code.
3. User application manifest for trust information: This option controls if the deployment uses the default Microsoft certificate information or your own certificate. If you are looking to control the publisher and product name via certificate on the security/trust dialog (before installation), use this option and sign with your own or your company's certificate. Custom certificates can aid in hiding the security/trust dialog when you have full control over the machines on which the application will be installed (e.g. a network environment).
4. Exclude deployment provider URL: This option is new to VS 2008 SP1. This setting can be used if the update location is indeterminate at the time of initial release, in which case the application will check for updates from wherever it was initially installed.
5. Create desktop shortcut: This option is also new to VS 2008 SP1. It controls whether or not the deployment creates an icon shortcut on the desktop. This is an exciting new feature for ClickOnce; prior to SP1, it was not possible to create desktop shortcuts unless you had control over the machines via SMS or some other method.

Take some caution when configuring these settings as some will not play nicely together or even make sense in certain scenarios. For example, options 1 and 2 shouldn't be enabled at the same time; doing so will result in an error during deployment as shown below.

ERROR SUMMARY
Below is a summary of the errors, details of these 
errors are listed later in the log.
* Activation of
http://gobi/ClickOnceDeployment/ClickOnce%20Demo.application
resulted in exception. Following failure messages were
detected:
+ Exception reading manifest from
http://gobi/ClickOnceDeployment/ClickOnce%20Demo
.application: the manifest may not be valid or the file
could not be opened.
+ Deployment manifest is not semantically valid.
+ trustUrlParameters and disallowUrlActivation cannot both
be true at the same time.

Publish Options: File Associations

Click here for larger image

Note that all four fields are required and if not populated will be flagged with a red exclamation point. They are as follows:

1. Extension: It is important to include the "." and for the extension to be unique. If the extension is found not be unique upon installing, the association will not succeed.
2. Description: This will display as the hover-over text in Windows.
3. ProgID: This is a name used to identify the file type.
4. Icon: You can browse to select an .ico file to use for the files' icon in the file system.

Conclusion

About the Authors

Rachel Baker is a senior developer with Crowe Horwath LLP in the Oak Brook, Illinois, office. She can be reached at 630.990.4434 or rachel .baker@crowehorwath.com.