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

1. Open a .NET Framework SDK Command Prompt, and change to the directory in which you will store your ClickOnce files.

2. Create a subdirectory named bin and place all of your application files here, including executable files, assemblies, resources, and data files

3. 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.

4. Move the \bin directory into the directory you created step 2.

5. 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
   

6. Sign the application manifest with your digital certificate:

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

7. 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
   

8. Sign the deployment manifest with your certificate:

   mage -Sign WindowsFormsApp1.application -CertFile mycert.pfx
   

9. 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.

10. 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

1. Open a .NET Framework SDK Command Prompt, and navigate to the directory in which you will store your ClickOnce files.

2. Create a subdirectory named bin and place all of your application files here, including executable files, assemblies, resources, and data files.

3. 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.

4. Move the \bin directory into the directory you created in step 2, and then start the graphical tool:

   MageUI.exe
   

5. Create a new application manifest by selecting File, New, Application Manifest from the menu.

6. On the default Name tab, enter the name and version number of this deployment.

7. Select the Files tab and click the Browse... button next to the Application Directory text box.

8. Select the directory containing your application files that you created in step 2, and click OK on the folder selection dialog box.

9. 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.)

10. 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.

11. Select File, Save from the menu, and save the application manifest. You will be prompted to sign the application manifest when you save it.

12. 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.

13. 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).

14. 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.)

15. 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.

16. 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.

17. Choose Save and save the deployment manifest to disk. You will be prompted to sign the application manifest when you save it.

18. 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.

19. 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.

20. 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.

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.

See Also

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