Manually Putting a ClickOnce Application into Production

A common question with respect to ClickOnce is how to take an application that you have published and tested on your local machine or a local development server and move that application into production. The steps involved are not particularly complex, but do involve using some other tools to get it done and are not easy to figure out on your own unless you have a solid understanding of ClickOnce manifests, signing, and how they relate to the launch mechanisms of ClickOnce.

A key pre-requisite for doing this is that the administrator who will be placing the application on the target machine will need to have the publisher certificate that will be used to sign the production application available. Usually in large organizations the developers will not have access to the company’s real certificate to do their development anyway, it will be up to the IT Administrator to get that certificate and do the final signing of the applications anyway.

*Step 1: Move your application files to the target machine.
Assuming you have published your application with Visual Studio to your local machine or another test server in your development environment, the application files are contained in the virtual directory or folder that you specified as the Publish Location within Visual Studio. The deployment manifest, Bootstrapper setup.exe, publish.htm deployment page, and version specific deployment manifests are located in the root folder. For each version you published to that location, there is a subfolder that contains the application manifest and application files for that version. You might do this by zipping up the appropriate files and folders and just giving the zip file to the administrator who will put it into production.

To move the current version into production, you will need to copy the deployment manifest, setup.exe, version-specific manifest and sub-folder for the version you want to publish to the target machine deployment folder. You only need to include the publish.htm file if you intend to use that test page directly to expose the application to end users. But if you are going to put a link to the deployment manifest in some other page or send a link via email, you don’t need to include the publish.htm page.

*Step 2 (Optional): Make needed changes to application files
If you need to change something in the application files, such as changing a setting in the application configuration file or updating some graphics files, you will need to update the application manifest after modifying the application files themselves. So make the modifications needed in your application files.

*Step 3: (Only needed if you did step 2): Update the application manifest file list
If you made any changes to any application files, you will need to refresh the list of files contained in the application manifest. This is because the manifest contains the hash for each file that provides a unique representation of the contents of the file. If you changed the application file, the hash for that file that is in the application manifest is no longer valid and needs to be updated.

– Open the application manifest (.manifest file in the application files folder for the version you are publishing) with mageui.exe.
– Select the Files category in the list on the left side of the window.
– Enter the path to the application files folder for the deployment on the right side.
– You can press the ellipses (…) button to browse to the folder.

Mage Files Pane

This step does not have to be done on the target machine because only relative paths are stored in the manifest from the location of the manifest, but the manifest and the application files need to be located with the same relative folder path as they will be on the target machine (usually the same directory).
– After you have entered the path to the folder, press the Populate button.
-You will be prompted with a warning dialog about the fact that the files will be renamed with a .deploy extension.
– Click Yes in this dialog.

Renaming Files Warning

*Step 4: Sign the application manifest
If you make any changes to the application files and update the application manifest as described in step 3, or if you just need to re-sign the application manifest with a production certificate that is different than the one that was used in development, then you will need to sign the manifest with Mage. To do so:
– Open the .manifest file with mageui.exe if not already open from step 3.
– Press the Save button in the toolbar, and you will be presented with the signing dialog shown below.

Signing Dialog

– Provide the path to the certificate file and the certificate password at the top of the dialog, or select the certificate from your personal certificate store at the bottom of the dialog.
– Click OK to sign the manifest with the selected certificate.

*Step 5: Update the application manifest reference in the deployment manifest
If you performed step 4 and signed with a different certificate than the one used to
originally generate the deployment manifest, you now need to update the application reference in the deployment manifest. The application reference is a strong reference to the application manifest from the deployment manifest, including path information as well as the public key token from the digital signature in the application manifest. That signature is generated using the publisher certificate, so if you change the certificate, you have to update the application reference.

To update the application reference, do the following:
– Open the deployment manifest (.application file) in mageui.exe
– Select Application Reference from the list of categories on the left of the window
– Press the Select Manifest… button and navigate to the application manifest (.manifest file) for the version that you are deploying.

Application Reference UI

*Step 6: Update the Deployment Provider
If you are moving the application to a different server than the one where you first published the application from Visual Studio, you will need to update the deployment provider URL that is embedded in the deployment manifest. To do so, perform the following steps:
– Open the deployment manifest in mageui.exe if it is not already opened from step 5.
– Select Deployment Options from the list of categories on the left side of the window.
– Change the URL labeled Start Location to reflect the URL users will use to launch the application from the client machine. This setting is saved as the deployment provider in the deployment manifest.

Deployment Provider

*Step 7: Sign the deployment manifest
– Click the Save button in the toolbar.
– Enter the path and password for the publisher certificate file at the top of the signing dialog, or select the certificate from the list of certificates at the bottom. This should be the same certificate used to sign the application manifest.
– Click OK to re-sign the manifest.

At this point, your application should be ready to go from the client.