Walkthrough: Deploying a ClickOnce Application Manually

Walkthrough: Deploying a ClickOnce ...

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

Want more? Here are some additional resources on this topic:

Building ClickOnce Applications from the Command Line

.NET Framework Developer's Guide

Walkthrough: Deploying a ClickOnce Application Manually

This walkthrough describes the steps required to create a full ClickOnce deployment using the command-line or graphical version of the Manifest Generation and Editing tool (Mage).

If you do not use Visual Studio regularly, need to automate the deployment process, or need to use advanced deployment features such as Trusted Application Deployment, you should use the Mage.exe command-line tool to create your ClickOnce manifests. The following walkthrough takes you through all of the steps required to generate a full ClickOnce deployment using either the command-line version (Mage.exe) or the Windows Forms version (MageUI.exe) of the Manifest Generation and Editing Tool.

Prerequisites

This walkthrough was written under the assumption that you have a Windows Forms application that you are ready to deploy; this application will be referred to as WindowsFormsApp1. You also must install the .NET Framework SDK.

There are a number of issues you need to decide before building a deployment. First and foremost is how you will distribute the deployment: Over the Web, from a file share, or installed off of a CD. For more information, see ClickOnce Deployment Overview.

Next, you need to determine whether your application will run at an elevated level of trust. As discussed in Trusted Application Deployment Overview, by default ClickOnce applications will run in a partially trusted zone, with their exact permissions determined by whether they are hosted on an intranet or off of the Internet. If an application needs to access data on the client computer, talk to local devices, call Windows API functions, or perform other potentially dangerous operations, it will need to assert a higher level of trust. If your application requires Full Trust—for example, full access to the user's system—you can use Mage.exe to set this easily. If you want to define a custom permission set for your application, you can copy the Internet or intranet permission section from another manifest, modify it to suit your needs, and add it to the application manifest using either a text editor or MageUI.exe.

The two methods for asserting higher trust in a ClickOnce manifest are Permission Elevation and Trusted Application Deployment. In both cases, your deployment must be signed with an Authenticode certificate either generated using the MakeCert.exe tool or obtained from a Certificate Authority (CA). If you choose to use Trusted Application Deployment, you must also perform a one-time installation of the certificate onto all client computers. For more information, see Trusted Application Deployment Overview.

To deploy an application with the Mage.exe command-line tool

Open a .NET Framework SDK Command Prompt, and change to the directory in which you will store your ClickOnce files.
Create a subdirectory named bin and place all of your application files here, including executable files, assemblies, resources, and data files
Create a subdirectory named after the current version of your deployment. If this is the first time you are deploying the application, you will likely choose 1.0.0.0.

Note

The version of your deployment may be distinct from the version of your application files.
Move the \bin directory into the directory you created step 2.

Note
The version of your deployment may be distinct from the version of your application files.

Generate the application manifest with a call to Mage.exe:

mage -New Application -ToFile 1.0.0.0\WindowsFormsApp1.exe.manifest -Name "Windows Forms App 1" -Version 1.0.0.0 -FromDirectory 1.0.0.0\bin

Sign the application manifest with your digital certificate:

mage -Sign WindowsFormsApp1.exe.manifest -CertFile mycert.pfx

Generate the deployment manifest with a call to Mage.exe. Mage.exe will, by default, mark your ClickOnce deployment as an installed application, so that it can be run both online and offline. To make the application available only when the user is online, use the -i flag with a value of f. If you use the default, and users will install your application from a Web site or file share, make sure the value of the -providerUrl flag points to the location of the application manifest on the Web server or share.
```
mage -New Deployment -ToFile WindowsFormsApp1.application -Name "Windows Forms App 1" -Version 1.0.0.0 -AppManifest 1.0.0.0\WindowsFormsApp1.manifest -providerUrl http://www.adatum.com/WindowsFormsApp1/WindowsFormsApp1.application
```

Sign the deployment manifest with your certificate:

mage -Sign WindowsFormsApp1.application -CertFile mycert.pfx

Copy all of the files in the current directory—including the version folder and the \bin folder—to the deployment destination. This may be either a folder on a Web site or FTP site, a file share, or a CD.
Supply your users with the URL, UNC, or physical media required to install your application. If you are supplying a URL or UNC, you must give your users the full path the deployment manifest. For example, if WindowsFormsApp1 is deployed to http://webserver01/ in the WindowsFormsApp1 directory, the full URL path would be http://webserver01/WindowsFormsApp1/WindowsFormsApp1.deploy.

Deploying the application with the MageUI.exe Graphical Tool

Open a .NET Framework SDK Command Prompt, and navigate to the directory in which you will store your ClickOnce files.
Create a subdirectory named bin and place all of your application files here, including executable files, assemblies, resources, and data files.
Create a subdirectory named after the current version of your deployment. If this is the first time you are deploying the application, you will likely choose 1.0.0.0.

Note

The version of your deployment may be distinct from the version of your application files.
Move the \bin directory into the directory you created in step 2, and then start the graphical tool:
```
MageUI.exe
```
Create a new application manifest by selecting File, New, Application Manifest from the menu.
On the default Name tab, enter the name and version number of this deployment.
Select the Files tab and click the Browse... button next to the Application Directory text box.
Select the directory containing your application files that you created in step 2, and click OK on the folder selection dialog box.
Click the Populate button to add all your application files to the file list. If your application contains more than one executable file, mark the main executable file for this deployment as the startup application by selecting Entry Point from the File Type drop-down list. (If your application only contains one executable file, MageUI.exe will mark it for you.)
Select the Permissions Required tab and select the level of trust you need your application to assert. The default is Full Trust, which will be suitable for most applications.
Select File, Save from the menu, and save the application manifest. You will be prompted to sign the application manifest when you save it.
If you have a certificate stored as a file on your file system, use the Sign as certificate file option, and select the certificate from the file system using the ... button.

-or-

If your certificate is kept in a certificate store accessible from your machine, select the Sign with stored certificate option, and select the certificate from the list provided.
Select File, New, Deployment Manifest from the menu to create your deployment manifest, and then on the Name tab, supply a name and version number (1.0.0.0 in this example).
Select the Publisher tab, and supply values for Publisher and Product. (Product is the name given your application on the Windows Start menu when you install your application locally.)
Switch to the Update tab, and specify how often you would like this application to update. If your application uses the ClickOnce Deployment API to check for updates itself, clear the check box labeled This application should check for updates.
Switch to the Application Reference tab. You can pre-populate all of the values on this tab by clicking the Select Manifest button and selecting the application manifest you created in previous steps.
Choose Save and save the deployment manifest to disk. You will be prompted to sign the application manifest when you save it.
If you have a certificate stored as a file on your file system, use the Sign as certificate file option, and select the certificate from the file system using the ... button.

-or-

If your certificate is kept in a certificate store accessible from your machine, select the Sign with stored certificate option, and select the certificate from the list provided.
Copy all of the files in the current directory—including the version folder and the \bin folder—to the deployment destination. This may be either a folder on a Web site or FTP site, a file share, or a CD.
Supply your users with the URL, UNC, or physical media required to install your application. If you are supplying a URL or UNC, you must give your users the full path the deployment manifest. For example, if WindowsFormsApp1 is deployed to http://webserver01/ in the WindowsFormsApp1 directory, the full URL path would be http://webserver01/WindowsFormsApp1/WindowsFormsApp1.deploy.

Note
The version of your deployment may be distinct from the version of your application files.

Next Steps

When you need to deploy a new version of the application, you will need to create a new directory named after the new version—for example, 1.1.0.0—and move the new application files into a \bin folder in that new directory. You should generate a new application manifest and store it in the new directory, and have the publisher sign the new manifest. Once you get the signed manifest back, you can use Mage.exe to update the deployment manifest and point it at the new application manifest:

mage -Update WindowsFormsApp1.application -Version 1.1.0.0 -AppManifest 1.1.0.0\WindowsFormsApp1.exe.manifest

MageUI.exe users can perform the same operation by opening up their deployment manifest, selecting the Application Reference tab, and selecting the Select Manifest button again.

After updating the application manifest reference, you will need to re-sign the deployment manifest, because changing a manifest in any way invalidates its digital signature.

Reference

Manifest Generation and Editing Tool (Mage.exe)
Manifest Generation and Editing Tool, Graphical Client (MageUI.exe)
ClickOnce Deployment Manifest
ClickOnce Application Manifest

Concepts

ClickOnce Deployment Overview

Tags

: Add a tag

Community Content

Add new content

Annotations

ClickOnce Deployment

Rich-C | Edit | Show History

This process will work with IIS 5 but will fail with IIS 6 with the following error.

ERROR SUMMARY
Below is a summary of the errors, details of these errors are listed later in the log.
* Activation of http://www.adatum.com/WindowsFormsApp1/WindowsFormsApp1.application resulted in exception. Following failure messages were detected:
+ Downloading http://www.adatum.com/WindowsFormsApp1/1.0.0.0/WindowsFormsApp1.exe.config did not succeed.
+ The remote server returned an error: (403) Forbidden.

Tags

: Add a tag

Flag as ContentBug

Is it really that much trouble to proofread your articles?

hattar ... Lex Cui | Edit | Show History

The article has been voted a 1 because it's poorly written. In step 4 I'm told to move the /bin directory into the directory created in step 2. Perhaps I should move the directory into itself?

maybe you are right

Tags

: Add a tag

Flag as ContentBug

This article truly provides minimal and inadequate information...

jeffhuckins | Edit | Show History

So, I dump all of my files into this \bin directory - where/how does the target file system get defined (location for each file?)
Is a Windows Installer (.msi) for the application used? If not, what provides that functionality to install files, register components, set target folder access permissions, etc?

Basically, this article seems to imply that you just dump all of the application files into this mixed bin with a signed app and deployment manifest and the mix of files must somehow genesis themselves into an install application.

Tags

: Add a tag

Flag as ContentBug

This article is not that bad

Rhapsody | Edit | Show History

For the people above. To understand this article you must read some other articles about deployment first.

There's no MSI used. ClickOnce will take care of the 'install', register components etc etc...

This article is usefull for me though. I was searching for the exact difference between the deployment- and the application manifest.
Only step 4 is strange.

Tags

: Add a tag

Flag as ContentBug

Information and steps are wrong, cannot follow these steps to success

Bil Simser [MVP] | Edit | Show History

The article is wrong on many steps. In fact, following it to the letter will result in nothing working as there are incorrect instructions. Following and adjusting the locations of files as you go (for example where your .pfx file is when you sign the manifests, which changes between steps) works however you get to the end and the system can't find your files to download. In generally it's just wrong steps and I would challenge anyone to reproduce them as-is. I'm currently writing up a (long) blog entry on this entire process (between Visual Studio, MageUI, mage.exe and MSBuild) which will hopefully clarify all of this.

Tags

: Add a tag

Flag as ContentBug