Click to Rate and Give Feedback
MSDN
MSDN Library
Visual Studio 2008
Visual Studio
 Walkthrough: Manually Deploying a C...

  Switch on low bandwidth view
This page is specific to
Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:
.NET Framework Developer's Guide
Walkthrough: Manually Deploying a ClickOnce Application

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.

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 Windows Software Development Kit (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 Windows SDK Command Prompt, and change to the directory in which you will store your ClickOnce files.

  2. Create a directory 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.

    NoteNote:

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

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

  4. 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
    
  5. Sign the application manifest with your digital certificate:

    mage -Sign WindowsFormsApp1.exe.manifest -CertFile mycert.pfx
    
  6. 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
    
  7. Sign the deployment manifest with your certificate:

    mage -Sign WindowsFormsApp1.application -CertFile mycert.pfx
    
  8. 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.

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

    NoteNote:

    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.

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.

Community Content   What is Community Content?
Add new content RSS  Annotations
mage steps corrected      Neeme   |   Edit   |   Show History
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
useless article      yoshiw   |   Edit   |   Show History
as some people already pointed out, this walkthrough is incomplete, contains errors, and just does not help. I wasted good one hour on this.
using Visual Studio to deploy a ClickOnce application      Mary Lee - MSFT ... Thomas Lee   |   Edit   |   Show History

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

Why do we need this chapter in documentation when it is not working???      Exorsus   |   Edit   |   Show History

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!

Using ClickOnce to generate an Obfuscated Package      Jason Nadrowski From Blue Clarity   |   Edit   |   Show History

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.

Usless article      Anslum ... Thomas Lee   |   Edit   |   Show History

This article is not fully completed and missed couple of steps...I can't even rate this article.

Flag as ContentBug
Processing
© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker