.NET Framework Developer's Guide
Walkthrough: Manually Deploying a ClickOnce Application

Updated: August 2009

If you cannot use Visual Studio to deploy your ClickOnce application, or you 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. This walkthrough describes how to create a ClickOnce deployment by using either the command-line version (Mage.exe) or the graphical version (MageUI.exe) of the Manifest Generation and Editing Tool.

Prerequisites

This walkthrough has some prerequisites and options that you need to choose before building a deployment.

  • Install Mage.exe and MageUI.exe.

    Mage.exe and MageUI.exe are part of the Windows Software Development Kit (SDK). You must either have the Windows SDK installed or the version of the Windows SDK included with Visual Studio. For more information, see Windows SDK on MSDN.

  • Provide an application to deploy.

    This walkthrough assumes that you have a Windows application that you are ready to deploy. This application will be referred to as AppToDeploy.

  • Determine how the deployment will be distributed.

    The distribution options include: Web, file share, or CD. For more information, see ClickOnce Deployment.

  • Determine whether the application requires an elevated level of trust.

    If your application requires Full Trust—for example, full access to the user's system—you can use the -TrustLevel option of Mage.exe to set this. 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. For more information, see Trusted Application Deployment Overview.

  • Obtain an Authenticode certificate.

    You should sign your deployment with an Authenticode certificate. You can generate a test certificate by using Visual Studio, MageUI.exe, or MakeCert.exe and Pvk2Pfx.exe tools, or you can obtain a certificate 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.

  • Make sure that the application does not have a manifest with UAC information.

    You need to determine whether your application contains a manifest with User Account Control (UAC) information, such as an <dependentAssembly> element. To examine an application manifest, you can use the Windows Sysinternals Sigcheck utility.

    If your application contains a manifest with UAC details, you must re-build it without the UAC information. For a C# project in Visual Studio, open the project properties and select the Application tab. In the Manifest drop-down list, select Create application without a manifest. For a Visual Basic project in Visual Studio, open the project properties, select the Application tab, and click View UAC Settings. In the opened manifest file, remove all elements within the single <asmv1:assembly> element.

  • Determine whether the application requires prerequisites on the client computer.

    ClickOnce applications deployed from Visual Studio can include a prerequisite installation bootstrapper (setup.exe) with your deployment. This walkthrough creates the two manifests required for a ClickOnce deployment. You can create a prerequisite bootstrapper by using the GenerateBootstrapper Task.

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

  1. Create a directory where you will store your ClickOnce deployment files.

  2. In the deployment directory you just created, create a version subdirectory. If this is the first time that you are deploying the application, name the version subdirectory 1.0.0.0.

    NoteNote:

    The version of your deployment can be distinct from the version of your application.

  3. Copy all of your application files to the version subdirectory, including executable files, assemblies, resources, and data files. If necessary, you can create additional subdirectories that contain additional files.

  4. Open the Windows SDK or Visual Studio command prompt and change to the version subdirectory.

  5. Create the application manifest with a call to Mage.exe. The following statement creates an application manifest for code compiled to run on the Intel x86 processor.

    mage -New Application -Processor x86 -ToFile AppToDeploy.exe.manifest -name "My App" -Version 1.0.0.0 -FromDirectory . 
    
    NoteNote:

    Be sure to include the dot (.) after the -FromDirectory option, which indicates the current directory. If you do not include the dot, you must specify the path to your application files.

  6. Sign the application manifest with your Authenticode certificate. Replace mycert.pfx with the path to your certificate file. Replace passwd with the password for your certificate file.

    mage -Sign AppToDeploy.exe.manifest -CertFile mycert.pfx -Password passwd
    
  7. Change to the root of the deployment directory.

  8. Generate the deployment manifest with a call to Mage.exe. By default, Mage.exe will 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 -Install option with a value of false. If you use the default, and users will install your application from a Web site or file share, make sure that the value of the -ProviderUrl option points to the location of the application manifest on the Web server or share.

    mage -New Deployment -Processor x86 -Install true -Publisher "My Co." -ProviderUrl "\\myServer\myShare\AppToDeploy.application" -AppManifest 1.0.0.0\AppToDeploy.exe.manifest -ToFile AppToDeploy.application
    
  9. Sign the deployment manifest with your Authenticode certificate.

    mage -Sign AppToDeploy.application -CertFile mycert.pfx -Password passwd
    
  10. Copy all of the files in the deployment directory to the deployment destination or media. This may be either a folder on a Web site or FTP site, a file share, or a CD-ROM.

  11. Provide your users with the URL, UNC, or physical media required to install your application. If you provide a URL or a UNC, you must give your users the full path to the deployment manifest. For example, if AppToDeploy is deployed to http://webserver01/ in the AppToDeploy directory, the full URL path would be http://webserver01/AppToDeploy/AppToDeploy.application.

To deploy an application with the MageUI.exe graphical tool

  1. Create a directory where you will store your ClickOnce deployment files.

  2. In the deployment directory you just created, create a version subdirectory. If this is the first time that you are deploying the application, name the version subdirectory 1.0.0.0.

    NoteNote:

    The version of your deployment is probably distinct from the version of your application.

  3. Copy all of your application files to the version subdirectory, including executable files, assemblies, resources, and data files. If necessary, you can create additional subdirectories that contain additional files.

  4. Start the MageUI.exe 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, type the name and version number of this deployment. Also specify the Processor that your application is built for, such as x86.

  7. Select the Files tab and click the ellipsis (...) button next to the Application directory text box. A Browse For Folder dialog box appears.

  8. Select the version subdirectory containing your application files, and then click OK.

  9. If you will deploy from Internet Information Services (IIS), select the When populating add the .deploy extension to any file that does not have it check box.

  10. 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 contains only one executable file, MageUI.exe will mark it for you.)

  11. Select the Permissions Required tab and select the level of trust that you need your application to assert. The default is FullTrust, which will be suitable for most applications.

  12. Select File, Save As from the menu. A Signing Options dialog box appears prompting you to sign the application manifest.

  13. If you have a certificate stored as a file on your file system, use the Sign with certificate file option, and select the certificate from the file system by using the ellipsis (...) button. Then type your certificate password.

    -or-

    If your certificate is kept in a certificate store accessible from your computer, select the Sign with stored certificate option, and select the certificate from the provided list.

  14. Click OK to sign your application manifest. The Save As dialog box appears.

  15. In the Save As dialog box, specify the version directory, and then click Save.

  16. Select File, New, Deployment Manifest from the menu to create your deployment manifest.

  17. On the Name tab, specify a name and version number for this deployment (1.0.0.0 in this example). Also specify the Processor that your application is built for, such as x86.

  18. Select the Description tab, and specify values for Publisher and Product. (Product is the name given to your application on the Windows Start menu when your application installs on a client computer for offline use.)

  19. Select the Deployment Options tab, and in the Start Location text box, specify the location of the application manifest on the Web server or share. For example, \\myServer\myShare\AppToDeploy.application.

  20. If you added the .deploy extension in a previous step, also select Use .deploy file name extension here.

  21. Select the Update Options tab, and specify how often you would like this application to update. If your application uses UpdateCheckInfo to check for updates itself, clear the This application should check for updates check box.

  22. Select the Application Reference tab and then click the Select Manifest button. An open dialog box appears.

  23. Select the application manifest that you created earlier and then click Open.

  24. Select File, Save As from the menu. A Signing Options dialog box appears prompting you to sign the deployment manifest.

  25. If you have a certificate stored as a file on your file system, use the Sign with certificate file option, and select the certificate from the file system by using the ellipsis (...) button. Then type your certificate password.

    -or-

    If your certificate is kept in a certificate store accessible from your computer, select the Sign with stored certificate option, and select the certificate from the provided list.

  26. Click OK to sign your deployment manifest. The Save As dialog box appears.

  27. In the Save As dialog box, move up one directory to the root of your deployment and then click Save.

  28. Copy all of the files in the deployment directory to the deployment destination or media. This may be either a folder on a Web site or FTP site, a file share, or a CD-ROM.

  29. Provide your users with the URL, UNC, or physical media required to install your application. If you provide a URL or a UNC, you must give your users the full path the deployment manifest. For example, if AppToDeploy is deployed to http://webserver01/ in the AppToDeploy directory, the full URL path would be http://webserver01/AppToDeploy/AppToDeploy.application.

Next Steps

When you need to deploy a new version of the application, create a new directory named after the new version—for example, 1.0.0.1—and copy the new application files into the new directory. Next, you need to follow the previous steps to create and sign a new application manifest, and update and sign the deployment manifest. Be careful to specify the same higher version in both the Mage.exe -New and –Update calls, as ClickOnce only updates higher versions, with the left-most integer most significant. If you used MageUI.exe, you can update the deployment manifest by opening it, selecting the Application Reference tab, clicking the Select Manifest button, and then selecting the updated application manifest.

See Also

Reference

Other Resources

Change History

Date

History

Reason

August 2009

Updated topic.

Customer feedback.

Tags : clickonce


Community Content

Neeme
mage steps corrected
This text is partially misleading, partially insufficient, partially just wrong. You very likely fail miserably if you try to "walk through" your task with it.
1. Do not put files into bin directory or smth. - mage example provided on top of that leads just to wrong setup, where files are not found when deployed.
2. Step 5 and step 7 - there is no link nor guidance how to create pfx file. Good example is at http://blogs.msdn.com/maximelamure/archive/2007/01/24/create-your-own-pfx-file-for-clickonce.aspx
3. Step 5 and step 7 then need additional arguments to feed with keyfile passwords "-pwd <yourpassword>" (you want your TFS build, right, why else to use commandline?)
4. Mage does not have option to provide deployment manifest with publisher information, but installation fails then with "Deployment manifest requires that you specify a publisher and a product". Link, how to tweak it is http://www.ureader.com/msg/1436844.aspx. Another option woult be of course to manually modify deployment manifest. But leaving it without publisher results definitely with a crash.
5. No word about the fact that publishing files without special .deploy extension results with webserver configuration headaches, with IIS it may be complete showstopper. Unfortunately mage does not have functionality to support .deploy-renaming. Workaround is to:
a) generate application manifest
b) sign application manifest
b) add .deploy extension to all files except .manifest file
c) create application manifest, modify deployment tag, add parameter mapFileExtensions="true"
d) sign application manifest
Tags : contentbug

yoshiw
useless article
as some people already pointed out, this walkthrough is incomplete, contains errors, and just does not help. I wasted good one hour on this.
Tags : contentbug

Thomas Lee
using Visual Studio to deploy a ClickOnce application

You can use Visual Studio to deploy your ClickOnce application. this way, the application and deployment manifests are generated for you, and all the assemblies are placed into version-specific folders automatically. for more information, see How to: Publish a ClickOnce Application at http://msdn.microsoft.com/en-us/library/31kztyey.aspx


Exorsus
Why do we need this chapter in documentation when it is not working???

Good day,

i must say this article is completely useless and i am not mentioning its misleading. I've tried to dotfuscate my C# project and then deploy it with ClickOnce. I presume ClickOnce "technology" is a simple compile-copy-rename-sign and make mess with two manifests technology and even not working properly when used outside of Visual Studio. So, question is, what for the god sake is so complicated to create comprehensive tutorial on this topic? I've spent 8 hours of browsing internet searching for solution and trying to make this work but without luck. I think anyone can write better installer within 2 man days.

I apologize myself if i was crude but keep it simple and working!

Tags : contentbug

Jason Nadrowski From Blue Clarity
Using ClickOnce to generate an Obfuscated Package

I feel envious of the person that said they only lost an hour on this. I lost two days!!!

I was interested in Mage.exe as a method to clickonce an OBFUSCATED package. I think that probably applies to a lot of people interested in Mage. With that said, I am sure there are some people that want a mechanism to have a customer "tweak" and then "re-sign" the package. The bottom line is that mage is supposed to get you started and then you are left to manually tweak the file(s)...and THEN you sign them. I found the need for manual tweaking intolerable.

MY SHORT TERM SOLUTION
I used mage in the short term. It was painful because it required a fair amount of manual intervention--which made it a non-automated solution. I used the process written about by the user above--correcting for their typos--to generate the package.
a) generate APPLICATION manifest
b) sign APPLICATION manifest
b) add .deploy extension to all files except .manifest file (I simply did a rename on the existing files)
c) create DEPLOYMENT manifest, modify deployment tag, add parameter mapFileExtensions="true"
d) sign DEPLOYMENT manifest


MY LONG TERM SOLUTION
Of course, I could have completely automated my "short-term" solution by writting some command line programs that made the tweaks to the files for me. However, this would have been an inefficient use of my time. Instead, I am NOW publishing my obfuscated packages through VS 2008.

My DEBUG build, builds the UNobfuscated package. My RELEASE build, builds the Ofuscated package. The key was to modify the .csproj file (cannot do it through VS GUI) to do things depending on the type of build. First off, I needed to specify the references (obfuscated or UNobfuscated assemblies) based on wether I was in debug or release. See http://realfiction.net/?q=node/164 for information on understanding the condition attribute. The next was to integrate the obfusation process into the build. I am using Smart Assembly and the way they recomend doing it is described here: http://www.smartassembly.com/download/HowToUseClickOnce.pdf. Even if you are NOT using Smart Assembly, their method is generic and can be applied to your obfuscation generator.


OTHER COMMENTS
I have no earthly idea why this article is currently averaging 4 out of 5 stars? Maybe they are rating the user comments which are really the only redeeming aspect of this article.

NOTE TO Microsoft: It would be nice to have a little indicator at the top of the article that there are user comments. I have been assuming the article is correct and don't bother looking below it. After my experience with this, I will now.


Mary R Lee - MSFT
Updated article

This article has been updated in August 2009 to address all customer comments.

Tags : contenbug

Mary R Lee - MSFT
Updated article in August 2009
this article was updated in August 2009 to address all customer comments. all steps have been tested to ensure technical accuracy.
Tags :

Page view tracker