Mage.exe（清单生成和编辑工具）

• .NET Framework 3.5
• .NET Framework 2.0

清单生成和编辑工具 (Mage.exe) 是一种命令行工具，可以支持创建和编辑应用程序和部署清单。 作为一种命令行工具，Mage.exe 可以从批脚本和其他基于 Windows 的应用程序（包括 ASP.NET 应用程序）运行。

也可以使用一种图形应用程序 MageUI.exe 来代替 Mage.exe。 有关更多信息，请参见 MageUI.exe（图形化客户端中的清单生成和编辑工具）。

• Mage.exe 和 MageUI.exe 的两个版本作为组件包含在 Visual Studio 2010 安装程序中。 若要查看版本信息，请运行 MageUI.exe，选择“帮助”并选择“关于”。 本文档描述 Mage.exe 和 MageUI.exe 的 4.0.x.x 版本。

Mage [commands] [commandOptions]

下表显示了 Mage.exe 所支持的命令。 有关这些命令所支持的选项的更多信息，请参见新建和更新命令选项以及签名命令选项。

命令

说明

-cc, ClearApplicationCache

清除所有仅联机应用程序的已下载应用程序缓存。

-n, -New文件类型 [新建选项]

指定给定类型的新文件。 有效类型是：

• Deployment：创建新的部署清单。

• Application：创建新的应用程序清单。

如果不使用此命令指定任何其他参数，该命令将会使用默认的标记和特性值创建相应类型的文件。

使用 -ToFile 选项（如下表所示）指定新文件的文件名和路径。

使用 -FromDirectory 选项（如下表所示），可以创建一个应用程序清单，应用程序的所有程序集都添加到该清单的 节。

-u, -Update[文件路径] [更新选项]

对清单文件进行一项或多项更改。 不需要指定正在编辑的文件的类型。 Mage.exe 将使用一组试探法检查该文件，并确定该文件是部署清单还是应用程序清单。

如果已经使用证书对某个文件进行签名，-Update 将会移除密钥签名块。 这是因为，该密钥签名包含该文件的哈希，修改该文件会呈现无效的哈希。

使用 -ToFile 选项（如下表所示）指定新文件名和路径，而不是覆盖现有文件。

-s, -Sign[signOptions]

使用密钥对或 X509 证书对文件签名。 签名作为 XML 元素插入文件内。

在签署指定 -TimestampUri 值的清单时，必须连接到 Internet。

-h, -?, -Help[verbose]

描述所有的可用命令及其选项。 指定 verbose 以获得详细的帮助。

新建和更新命令选项

下表显示了 -New 和 -Update 命令支持的选项。

选项

默认值

适用于

说明

-appc, -AppCodeBasemanifestReference

部署清单。

插入应用程序清单文件的 URL 或文件路径引用。 此值必须是应用程序清单的完整路径。

-appm, -AppManifestmanifestPath

部署清单。

将对部署的应用程序清单的引用插入其部署清单中。

manifestPath 指示的文件必须存在，否则，Mage.exe 将会发出一个错误。 如果 manifestPath 引用的文件不是应用程序清单，Mage.exe 将会发出一个错误。

-cf, -CertFilefilePath

所有文件类型。

指定用于对清单进行签名的 X509 数字证书的位置。 如果该证书需要密码，此选项可以与 -Password 选项结合使用。

-ch, -CertHashhashSignature

所有文件类型。

存储在客户端计算机个人证书存储区中的数字证书的哈希。 此哈希对应于在 Windows 证书控制台中查看的数字证书的 Thumbprint 字符串。

hashSignature 可以大写或小写，可以作为单个字符串提供，或者与 Thumbprint 的每个八进制数一起提供。与每个八进制数一起提供时，要用空格分隔，且整个 Thumbprint 用引号引起来。

-fd, -FromDirectorydirectoryPath

应用程序清单。

使用 directoryPath（包括所有子目录）中的所有程序集和文件的说明填充应用程序清单，其中 directoryPath 是包含要部署的应用程序的目录。 对于该目录中的每个文件，Mage.exe 确定该文件是程序集还是静态文件。 如果该文件是程序集，它将会使用程序集的名称、代码库和版本将 标记和 installFrom 特性添加到应用程序中。 如果该文件是静态文件，它将会添加 标记。 另外，Mage.exe 将通过一组简单的试探法检测该应用程序的主要可执行文件，并在清单中将其标记为 ClickOnce 应用程序的入口点。

Mage.exe 永远不会将某个文件自动标记为“数据”文件； 此项操作必须手动完成。 有关更多信息，请参见 如何：将数据文件包括到 ClickOnce 应用程序中。

Mage.exe 还可以根据每个文件的大小为其生成哈希。 ClickOnce 使用这些哈希确保自创建清单以来无人篡改部署文件。 如果部署中的任何文件发生更改，可以使用 -Update 命令和 -FromDirectory 选项运行 Mage.exe，Mage.exe 将更新所有引用文件的哈希和程序集版本。

-FromDirectory 将包括 directoryPath 内所有子目录中的全部文件。

如果将 -FromDirectory 与 -Update 命令结合使用，Mage.exe 会从应用程序清单中移除该目录中不再存在的所有文件。

-if, -IconFile filePath

应用程序清单。

指定 .ICO 图标文件的完整路径。 此图标在开始菜单及其添加或删除程序项中，显示在应用程序名称旁边。 如果未提供图标，则使用默认图标。

-ip, -IncludeProviderURL url

true

部署清单。

指示部署清单是否包含由 -ProviderURL 设置的更新位置值。

-i, -InstallwillInstall

true

部署清单。

指示该 ClickOnce 应用程序是否应该安装到本地计算机上，或者该应用程序是否应通过 Web 运行。 安装某个应用程序后，该应用程序将会显示在 Windows“开始”菜单中。 有效值为“true”或“t”和“false”或“f”。

如果指定 -MinVersion 选项，并且用户安装的版本低于 -MinVersion，则无论向 -Install 传递何值，该选项都会强制安装该应用程序。

此选项不能与 -BrowserHosted 选项一起使用。 尝试为同一清单同时指定这两个选项将会导致错误。

-mv, -MinVersion [version]

由 -Version 标志指定的在 ClickOnce 部署清单中列出的版本。

部署清单。

用户可以运行的此应用程序的最低版本。 此标志使得应用程序的命名版本成为必需的更新。 如果发布的产品版本存在对重大更改或严重的安全漏洞的更新，可以使用此标志指定必须安装此更新且用户不能继续运行早期版本。

version 与 -Version 标志的参数的语义相同。

-n, -NamenameString

部署

所有文件类型。

用于标识应用程序的名称。 ClickOnce 将使用此名称标识“开始”菜单（如果该应用程序配置为自行安装）和“权限提升”对话框中的应用程序。

-pwd, -Passwordpasswd

所有文件类型。

使用数字证书对清单进行签名时所用的密码。 必须与 -CertFile 选项结合使用。

-p, ProcessorprocessorValue

Msil

应用程序清单。

部署清单。

可用于运行此分发的微处理器体系结构。 如果准备的是已经针对特定微处理器预编译程序集的一项或多项安装，则需要此值。 有效值包括 msil、x86、ia64 和 amd64。 msil 是 Microsoft 中间语言，这表示所有程序集都与平台无关，并且首次运行应用程序时，公共语言运行时 (CLR) 将会对所有程序集进行即时编译。

-pu,-ProviderURLurl

部署清单。

指定 ClickOnce 要检查是否存在应用程序更新的 URL。

-pub, -PublisherpublisherName

应用程序清单。

部署清单。

将发布者名称添加到部署清单或应用程序清单的描述元素中。 在应用程序清单中使用时，必须还要使用值“true”或“t”来指定 -UseManifestForTrust，否则此参数将引发错误。

-s, -SupportURL url

应用程序清单。

部署清单。

指定在“添加/删除程序”对话框中为 ClickOnce 应用程序显示的链接。

-ti, -TimestampUriuri

应用程序清单。

部署清单。

数字时间戳服务的 URL。 如果数字证书在部署应用程序的下一个版本之前过期，为清单加盖时间戳可以阻止您必须对清单进行重新签名。 有关详细信息，请参阅 Windows root certificate program members（Windows 根证书程序成员）。

-t, -ToFilefilePath

• 新签名：

• 部署：deploy.application

• 应用程序：application.exe.manifest

• 更新：

• 输入文件。

所有文件类型。

指定已经创建或修改的文件的输出路径。

如果使用 -New 时未提供 -ToFile，则输出将写入当前工作目录。 如果使用 -Update 时未提供 -ToFile，Mage.exe 会将该文件写回到输入文件中。

-tr, -TrustLevellevel

Intranet

应用程序清单。

要为客户端计算机上的应用程序授予的信任级别。 值包括“Internet”、“Intranet”和“FullTrust”。

-um, -UseManifestForTrustwillUseForTrust

False

应用程序清单。

指定当应用程序在客户端上运行时，是否将应用程序清单的数字签名用于做出信任决定。 如果指定“true”或“t”，则指示该应用程序清单将用于做出信任决定。 如果指定“false”或“f”，则指示将使用部署清单的签名。

-v, -VersionversionNumber

1.0.0.0

应用程序清单。

部署清单。

部署的版本。 参数必须是格式为“N.N.N.N”的有效版本字符串。其中，“N”是一个无符号的 32 位整数。

-wpf, -WPFBrowserApp isWPFApp

false

应用程序清单。

部署清单。

仅当应用程序是将在 Internet Explorer 内承载的 Windows Presentation Foundation (WPF) 应用程序且不是独立的可执行文件时，才使用此标志。 有效值为“true”或“t”和“false”或“f”。

对于应用程序清单，请在应用程序清单的 entryPoint 元素下插入 hostInBrowser 特性。

对于部署清单，请将 deployment 元素上的 install 特性设置为 false，并使用 .xbap 扩展名保存部署清单。 同时指定此参数与 -Install 参数将产生一个错误，因为浏览器承载的应用程序不可以是已安装的脱机应用程序。

签名命令选项

下表显示了 -Sign 命令支持的选项。该命令适用于所有类型的文件。

选项

说明

-cf, -CertFilefilePath

指定用于对清单进行签名的数字证书的位置。 此选项可以与 -Password 选项结合使用。

-ch, -CertHashhashSignature

存储在客户端计算机个人证书存储区中的数字证书的哈希。 此哈希对应于在 Windows 证书控制台中查看的数字证书的 Thumbprint 属性。

hashSignature 可以大写或小写，可以作为单个字符串提供，或者与 Thumbprint 的每个八进制数一起提供。与每个八进制数一起提供时，要用空格分隔，且整个 Thumbprint 用引号引起来。

-pwd, -Passwordpasswd

使用数字证书对清单进行签名时所用的密码。 必须与 -CertFile 选项结合使用。

-t, -ToFilefilePath

指定已经创建或修改的文件的输出路径。

Mage.exe 的所有参数区分大小写。 命令和选项的前缀可以是短划线 (-) 或反斜杠 (/)。

与 -Sign 命令结合使用的所有参数也可以随时与 -New 或 -Update 命令结合使用。 下列命令是等价项。

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

签名是应该执行的最后一项任务，因为签名的文档使用该文件的哈希验证签名是否对该文档有效。 如果对签名的文件做出任何更改，就必须重新对该文件进行签名。 如果对以前已经签名的文档进行签名，Mage.exe 将会使用新的签名替换原有的签名。

使用 -AppManifest 选项填充某个部署清单时，Mage.exe 会假定应用程序清单与部署清单（部署清单位于用当前部署版本命名的子目录中）位于同一个目录中，并对该部署清单进行相应地配置。 如果应用程序清单驻留在其他位置，请使用 -AppCodeBase 选项设置备用位置。

部署和应用程序清单必须在部署应用程序之前进行签名。 有关清单签名的指导，请参见受信任的应用程序部署概述。

应用程序清单的 -TrustLevel 选项描述了应用程序在客户端计算机上运行时所需的权限集。 默认情况下，根据应用程序的 URL 驻留的“区域”指定应用程序的信任级别。 通过公司网络部署的应用程序一般放置在 Intranet 区域，而那些通过 Internet 部署的应用程序放置在 Internet 区域。 这两个安全区域都可以限制应用程序对本地资源的访问。Intranet 区域比 Internet 区域的权限稍大。 FullTrust 区域授予应用程序对计算机本地资源的完全访问权限。 如果使用 -TrustLevel 选项将某个应用程序放置在此区域中，CLR 的信任关系管理器组件将会提示用户确定是否授予这种更高的信任级别。 如果准备通过公司网络部署应用程序，可以使用“受信任的应用程序部署”提升该应用程序的信任级别，而无需对用户做出提示。

应用程序清单还支持自定义信任部分。 这有助于应用程序遵守请求最低权限的安全原则，这是因为您可以对清单进行配置，使其只需要该应用程序运行所需的那些特定权限。 Mage.exe 不直接支持添加自定义信任部分。 可以使用文本编辑器、XML 分析器或图形工具 MageUI.exe 添加自定义信任部分。 有关如何使用 MageUI.exe 添加自定义信任部分的更多信息，请参见 MageUI.exe（图形化客户端中的清单生成和编辑工具）。

使用第 4 版本 Mage.exe 创建的新清单，包含在 Visual Studio 2010 中，以 .NET Framework 4 Client Profile 为目标。 若要指向早期版本的 .NET Framework，必须使用 Mage.exe 的早期版本。 将程序集添加到现有清单或从现有清单中移除程序集时，或者重新签署现有清单时，Mage.exe 不会将清单更新到目标 .NET Framework 4 Client Profile。 下表显示这些功能和限制。

清单版本

操作

Mage v2.0

Mage v4.0

面向 .NET Framework 2.0 版或 3.x. 版的应用程序的清单

打开

确定

确定

关闭

确定

确定

保存

确定

确定

重新签名

确定

确定

新建

确定

不支持

更新（如下所示）

确定

确定

面向 .NET Framework 第 4 版的应用程序的清单

打开

确定

确定

关闭

确定

确定

保存

确定

确定

重新签名

确定

确定

新建

不支持

确定

更新（如下所示）

不支持

确定

清单版本

更新操作详细信息

Mage v2.0

Mage v4.0

面向 .NET Framework 2.0 版或 3.x. 版的应用程序的清单

修改程序集

确定

确定

添加程序集

确定

确定

删除程序集

确定

确定

面向 .NET Framework 第 4 版的应用程序的清单

修改程序集

不支持

确定

添加程序集

不支持

确定

删除程序集

不支持

确定

Mage.exe 创建以 .NET Framework 4 Client Profile 为目标的新清单。 针对 .NET Framework 4 Client Profile 的 ClickOnce 应用程序可同时在 .NET Framework 4 Client Profile 和 .NET Framework 4 的完整版本上运行。 如果您的应用程序以完整版的 .NET Framework 4 为目标并且不能在 .NET Framework 4 Client Profile 上运行，请通过使用文本编辑器并对清单重新签名来删除客户端 元素。 以下为示例 元素，该元素以 .NET Framework 4 Client Profile 为目标。

下面的示例将打开 Mage (MageUI.exe) 的用户界面。

mage

下面的示例将创建默认的部署清单和应用程序清单。 这两个文件都在当前的工作目录中创建，并且分别命名为 deploy.application 和 application.exe.manifest。

mage -New Deploymentmage -New Application

下面的示例将创建使用 current 目录中的所有程序集和资源文件填充的应用程序清单。

mage -New Application -FromDirectory . -Version 1.0.0.0

下面的示例通过指定部署名称和目标微处理器继续前面的示例。 它还指定了 ClickOnce 检查更新时应该依据的 URL。

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

下面的示例演示如何创建一对清单，用于部署将在 Internet Explorer 中承载的 WPF 应用程序。

mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp truemage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true

下面的示例使用应用程序清单中的信息更新部署清单，并为该应用程序清单的位置设置了代码库。

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

下面的示例对部署清单进行编辑，以便强制更新用户已安装的版本。

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

下面的示例指示部署清单从其他目录检索应用程序清单。

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

下面的示例使用当前工作目录中的数字证书对现有的部署清单进行签名。

mage -Sign deploy.application -CertFile cert.pfx -Password