Manifest Generation and Editing Tool (Mage.exe) 

The Manifest Generation and Editing Tool (Mage.exe) is a command-line tool that supports the creation and editing of application and deployment manifests. As a command-line tool, Mage.exe can be run from both batch scripts and other Windows-based applications, including ASP.NET applications.

You can also use MageUI.exe, a graphical client, instead of Mage.exe. For more information, see Manifest Generation and Editing Tool, Graphical Client (MageUI.exe).

Mage [commands] [commandOptions]

Parameters

Command Description

-cc, ClearApplicationCache

Clears the downloaded application cache of all online-only applications.

-n, -New fileType [newOptions]

Creates a new file of the given type. Valid types are:

  • Deployment: Creates a new deployment manifest.

  • Application: Creates a new application manifest.

If you do not specify any additional parameters with this command, it will create a file of the appropriate type, with appropriate default tags and attribute values.

Use the –FromDirectory option (see in the following table) to create an application manifest with all of the assemblies for an application added to the <dependency> section of the manifest.

-u, -Update [filePath] [updateOptions]

Makes one or more changes to a manifest file. You do not need to specify the type of file you are editing; Mage.exe will examine the file using a set of heuristics and determine if it is a deployment manifest or an application manifest.

If you have already signed a file with a certificate, -Update will remove the key signature block. This is because the key signature contains a hash of the file, and modifying the file renders the hash invalid.

-s, -Sign [signOptions]

Uses a certificate to sign a file. Signatures are inserted as XML elements inside of the files.

-h, -Help

Describes all of the available commands and their options.

-v, -Verbose

Provides more detail about an operation during execution.

The following table shows the options supported by the –New and –Update commands.

Options Description

-appc, -AppCodeBase manifestReference

(Deployment manifests only) Inserts a URL or file path reference to the application manifest file. This file must be the full path to the application manifest.

-appm, -AppManifest manifestPath

(Deployment manifests only) Inserts a reference to a deployment's application manifest into its deployment manifest.

The file indicated by manifestPath must exist, or Mage.exe will issue an error. If the file referenced by manifestPath is not an application manifest, Mage.exe will issue an error.

-cf, -CertFile filePath

(All file types) Specifies the location of a digital certificate for signing a manifest. This option can be used in conjunction with the –Password option, if the certificate requires a password.

-ch, -CertHash hashSignature

(All file types) The hash of a digital certificate stored in the personal certificate store of the client computer. This corresponds to the Thumbprint string of a digital certificate viewed in the Windows Certificates Console.

hashSignature can be either uppercase or lowercase, and can be supplied either as a single string, or with each octet of the Thumbprint separated by spaces and the entire Thumbprint enclosed in quotes.

-fd, -FromDirectory directoryPath

(Application manifests only) Populates the application manifest with descriptions of all assemblies and files found in directoryPath, where directoryPath is the directory containing the application you want to deploy. For each file in the directory, Mage.exe decides whether the file is an assembly or a static file. If it is an assembly, it adds a <dependency> tag and installFrom attribute to the application with the assembly's name, code base, and version. If it is a static file, it adds a <file> tag. Mage.exe will also use a simple set of heuristics to detect the main executable for the application, and will mark it as the ClickOnce application's entry point in the manifest.

Mage.exe will never automatically mark a file as a "data" file; this must be done manually. For more information, see How to: Include a Data File in a ClickOnce Application.

Mage.exe also generates a hash for each file based on its size. ClickOnce uses these hashes to ensure that no one has tampered with the deployment's files since the manifest was created. If any of the files in your deployment change, you can run Mage.exe with the –Update command and the –FromDirectory option, and it will update the hashes and assembly versions of all referenced files.

-FromDirectory will include all files in all subdirectories found within directoryPath.

If you use –FromDirectory with the –Update command, Mage.exe will remove any files in the application manifest that no longer exist in the directory.

-I, -Install willInstall

(Deployment manifests only) Indicates whether or not the ClickOnce application should install onto the local machine, or whether it should run from the Web. Installing an application gives that application a presence in the Windows Start menu. Valid values are "true" or "t", and "false" or "f". If unspecified, the default value is “true”.

If you specify the –MinVersion option, and a user has a version less than -MinVersion installed, it will force the application to install, regardless of the value you pass to -Install.

-mv, -MinVersion [version]

(Deployment manifests only) The minimum version of this application a user can run. This flag makes the named version of your application a required update; if you release a version of your product with an update to a breaking change or a critical security flaw, you can use this flag to specify that this update must be installed, and that the user cannot continue to run previous versions.

If no version is specified, Mage.exe will use the version listed in the ClickOnce deployment manifest as specified by the -Version flag.

version has the same semantics as the argument to the -Version flag.

-n, -Name nameString

(All file types) The name used to identify the application. ClickOnce will use this name to identify the application in the Start menu (if the application is configured to install itself) and in Permission Elevation dialog boxes. If no name is supplied, the default is "deploy".

-pwd, -Password passwd

(All file types) The password used for signing a manifest with a digital certificate. Must be used in conjunction with the –CertFile option.

-p, Processor processorValue

(Deployment and application manifests only) The microprocessor architecture on which this distribution will run. This value is required if you are preparing one or more installations whose assemblies have been precompiled for a specific microprocessor. Valid values include msil, x86, ia64, and amd64. Default is msil, or Microsoft Intermediate Language, which means all of your assemblies are platform-independent, and the common language runtime (CLR) will just-in-time compile them when your application is first run.

-pu, -ProviderUrl url

(Deployment manifests only) Specifies the URL which ClickOnce will examine for application updates.

-tr, -TrustLevel level

(Application manifests only) The level of trust to grant the application on client computers. Values include "Internet", "Intranet", and "FullTrust". When creating a new application manifest, the default is "Intranet".

-tf, -ToFile filePath

(All file types) Specifies the output path of the file that has been created or modified.

If –ToFile is not supplied when using –New, the output is written to the current working directory with a default file name, whose exact name depends upon the type of file you create:

  • Deployment: deploy.application

  • Application: application.exe.manifest

If –ToFile is not supplied when using –Update, Mage.exe will write the file back to the input file.

-v, -Version versionNumber

(Deployment and application manifests only) The version of the deployment. The argument must be a valid version string of the format "N.N.N.N", where "N" is an unsigned 32-bit integer. The default value is "1.0.0.0".

The following table shows the options supported by the –Sign command, which apply to all types of files.

Options Description

-cf, -CertFile filePath

Specifies The location of a digital certificate for signing a manifest. This option can be used in conjunction with the –Password option.

-ch, -CertHash hashSignature

The hash of a digital certificate stored in the personal certificate store of the client computer. This corresponds to the Thumbprint property of a digital certificate viewed in the Windows Certificates Console.

hashSignature can be either uppercase or lowercase, and can be supplied either as a single string or with each octet of the Thumbprint separated by spaces and the entire Thumbprint enclosed in quotes.

-p, -Password passwd

The password used for signing a manifest with a digital certificate. Must be used in conjunction with the –CertFile option.

-t, -ToFile filePath

Specifies the output path of the file that has been created or modified.

Remarks

All arguments to Mage.exe are case-insensitive. Commands and options can be prefixed with a dash (-) or a forward slash (/).

All of the arguments used with the –Sign command can be used at any time with the –New or –Update commands as well. The following commands are equivalent.

mage –Sign c:\HelloWorldDeployment\HelloWorld.deploy –CertFile cert.pfx
mage –Update c:\HelloWorldDeployment\HelloWorld.deploy –CertFile cert.pfx

Signing is the last task you should perform, because a signed document uses a hash of the file to verify that the signature is valid for the document. If you make any alteration to a signed file, you must sign it again. If you sign a document that was previously signed, Mage.exe will replace the old signature with the new.

When you use the –AppManifest option to populate a deployment manifest, Mage.exe will assume that your application manifest will reside in the same directory as the deployment manifest within a subdirectory named after the current deployment version, and will configure your deployment manifest appropriately. If your application manifest will reside elsewhere, use the –AppCodeBase option to set the alternate location.

Your deployment and application manifest must be signed before you deploy your application. For guidance about signing manifests, see Trusted Application Deployment Overview.

The –TrustLevel option for application manifests describes the permission set an application requires to run on the client computer. By default, applications are assigned a trust level based on the zone in which their URL resides. Applications deployed over a corporate network are generally placed in the Intranet zone, while those deployed over the Internet are placed in the Internet zone. Both security zones place restrictions on the application's access to local resources, with the Intranet zone slightly more permissive than the Internet zone. The FullTrust zone gives applications complete access to a computer's local resources. If you use the –TrustLevel option to place an application in this zone, the Trust Manager component of the CLR will prompt the user to decide whether he or she wants to grant this higher level of trust. If you are deploying your application over a corporate network, you can use Trusted Application Deployment to raise the trust level of the application without prompting the user.

Application manifests also support custom trust sections. This helps your application obey the security principle of requesting least permission, as you can configure the manifest to demand only those specific permissions that the application requires in order to execute. Mage.exe does not directly support adding a custom trust section; you can add one using a text editor, an XML parser, or the graphical tool MageGUI.exe. For more information about using MageGUI.exe to add custom trust sections, see Manifest Generation and Editing Tool, Graphical Client (MageUI.exe).

Examples

The following example opens the user interface for Mage (MageUI.Exe).

mage

The following example calls create a default deployment manifest and application manifest. These files are all created in the current working directory and are called deploy.application and application.exe.manifest, respectively.

mage –New Deployment
mage –New Application
mage –New TrustLicense

The following example creates an application manifest populated with all of the assemblies and resource files from theHelloWorldapplication directory.

mage –New Application –FromDirectory \bin -Version 1.0.0.0

The following example also specifies the deployment name and target microprocessor, and also specifies a URL against which ClickOnce should check for updates.

mage –New Application –FromDirectory \bin -Name "Hello, World! Application" –Version 1.0.0.0 –Processor "x86" –ProviderUrl http://internalserver/HelloWorld/

The following example updates a deployment manifest with information from an application manifest, and sets the code base for the location of the application manifest.

mage –Update HelloWorld.deploy –AppManifest 1.0.0.0\application.manifest –AppCodeBase http://internalserver/HelloWorld.deployment

The following example edits the deployment manifest to force an update of the user's installed version.

mage –Update c:\HelloWorldDeployment\HelloWorld.deploy –MinVersion 1.1.0.0

The following example tells the deployment manifest to retrieve the application manifest from another directory.

mage –Update HelloWorld.deploy –AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/

The following example signs an existing deployment manifest using a digital certificate in the current working directory.

mage –Sign deploy.application –CertFile cert.pfx –Password passwd

See Also

Tasks

Walkthrough: Deploying a ClickOnce Application Manually

Reference

Manifest Generation and Editing Tool, Graphical Client (MageUI.exe)
SDK Command Prompt

Concepts

Trusted Application Deployment Overview