Configuring a ClickOnce DeploymentYou can perform many of the common activities needed to properly install your Windows desktop application to users’ machines via the built-in configuration menus in Visual Studio 2008. These menus expose properties that allow you to add description information, configure deployment and manifest-related settings, and control file associations. We will discuss all of these options. We will be using Visual Studio 2008 with SP1, which introduce a few important features, including the ability to create desktop shortcuts and file associations.
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: DescriptionIn the Deployment section, you’ll find the following dialog that allows you to enter general information about the application. This information is used during deployment, updates and uninstalls.
Listing 1.1 The Description screen of the Publish dialog
The following table illustrates where each property is used:
Listing 1.2 A table describing where the Description properties are used
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=”188.8.131.52″ name=”ClickOnce Demo.exe”
processorArchitecture=”msil” type=”win32″ />
Publish Options: DeploymentIn the Deployment section, you’ll find settings useful during debugging and for specifying options related to deploying to a web server and installing on a CD.
Listing 1.3 The Deployment screen of the Publish dialog
The five options under the Deployment section are:
- 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.
- 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.
- 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:
Listing 1.4 Generated files with the “Use .deploy file extension option
Here are the files generated without the “.deploy” extension option:
Listing 1.5 Generated files without the “Use .deploy file extension option
- 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.
- 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: ManifestsUnder the Manifest section, you’ll find the dialog below with five check box options used to configure the manifest files used during the deployment of the application.
Listing 1.6 The Manifests screen of the Publish dialog
- 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.
- 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.
- 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).
- 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.
- 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.
Below is a summary of the errors, details of these
errors are listed later in the log.
* Activation of
resulted in exception. Following failure messages were
+ Exception reading manifest from
.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 AssociationsIn the File Associations section, you’ll be able to configure and associate file extensions for your application that are then configured on the user’s PC during deployment. This is a new feature in VS 2008 SP1 / .NET 3.5 SP1 that opens up traditional file save and open functionality that has been previously missing from ClickOnce deployed applications.
Listing 1.7 The File Associations screen of the Publish dialog
Note that all four fields are required and if not populated will be flagged with a red exclamation point. They are as follows:
- 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.
- Description: This will display as the hover-over text in Windows.
- ProgID: This is a name used to identify the file type.
- Icon: You can browse to select an .ico file to use for the files’ icon in the file system.
ConclusionWe have discussed all of the ClickOnce deployment options available on the Publish tab’s Options dialog. With exposed configuration for many of the most common features required when installing a desktop application, now you can configure your ClickOnce application to perform exactly as you like. VS 2008 SP1 offers some additional features for improved deployment options.
About the AuthorsMatt Goebel is a manager with Crowe Horwath LLP in the Indianapolis, Indiana, office. He can be reached at 317.208.2555 or matt [email protected].
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 [email protected].