Mage.exe (средство создания и редактирования манифеста)

Средство создания и редактирования манифеста (Mage.exe) — это средство командной строки, поддерживающее создание и редактирование манифестов приложений и развертываний. В качестве средства командной строки программа Mage.exe может быть выполняться как в пакетных скриптах, так и в других Windows-приложениях, включая приложения ASP.NET.

Вместо Mage.exe также можно использовать MageUI.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. Дополнительные сведения о параметрах, поддерживаемых этими командами, см. в разделах Параметры команд New и Update и Параметры команды Sign.

Параметры команд New и Update

В следующей таблице приведены параметры, поддерживаемые командами -New и -Update.

Параметры	Значение по умолчанию	Применение	Описание
-appc, -AppCodeBase manifestReference		Манифесты развертывания.	Вставляет в файл манифеста приложения ссылку на URL-адрес или путь к файлу. Это значение должен быть равно полному пути к манифесту приложения.
-appm, -AppManifest manifestPath		Манифесты развертывания.	Вставляет ссылку на манифест приложения в соответствующий манифест развертывания. Файл, задаваемый параметром manifestPath, должен существовать, или программа Mage.exe выдаст ошибку. Если файл, определяемый параметром manifestPath, не является манифестом приложения, программа Mage.exe выдаст ошибку.
-cf, -CertFile filePath		Все типы файлов.	Задает местонахождение цифрового сертификата X509 для подписания манифеста. Этот параметр может использоваться в сочетании с параметром -Password, если для сертификата требуется пароль.
-ch, -CertHash hashSignature		Все типы файлов.	Хэш-значение цифрового сертификата, хранящегося в хранилище персональных сертификатов клиентского компьютера. Оно соответствует строке отпечатка цифрового сертификата, отображаемого в консоли сертификатов Windows. Параметр hashSignature может быть задан или в верхнем, или в нижнем регистре, и может предоставляться либо как целая строка, либо в виде всех октетов отпечатка, разделенных пробелами, и всего отпечатка, заключенного в кавычки.
-fd, -FromDirectory directoryPath		Манифесты приложений.	Заполняет манифест приложения описаниями всех сборок и файлов, найденных в каталоге directoryPath и всех его дочерних каталогах, где directoryPath — это каталог, содержащий приложение, которое нужно развернуть. Для каждого файла в этом каталоге программа Mage.exe определяет, является ли этот файл сборкой или статическим файлом. Если он является сборкой, программа добавляет тег <dependency> и атрибут installFrom в приложение, указав имя, базу кода и версию сборки. Если это статический файл, добавляется тег <file>. Программа Mage.exe также будет использовать простой набор эвристик, чтобы определить главный исполнимый файл приложения, и пометит его в манифесте как точку входа приложения ClickOnce. Программа Mage.exe никогда не помечает файл как файл "данных". Это необходимо сделать вручную. Дополнительные сведения см. в разделе Практическое руководство. Включение файла данных в приложение ClickOnce. Программа Mage.exe также создает хэш-значение для каждого файла, используя его размер. Технология ClickOnce использует эти хэш-значения, чтобы гарантировать, что никто не изменял файлы развертывания со времени создания манифеста. При изменении любого из файлов развертывания можно запустить программу Mage.exe с командой -Update и параметром -FromDirectory, и она обновит хэш-значения и версии сборки для всех указанных файлов. -FromDirectory включает все файлы во всех подкаталогах, найденных в каталоге directoryPath. При использовании параметра -FromDirectory с командой -Update программа Mage.exe удалит из манифеста приложения все файлы, больше не существующие в каталоге.
-if, -IconFile filePath		Манифесты приложений.	Задает полный путь к ICO-файлу значка. Этот значок отображается рядом с именем приложения в меню "Пуск" и в разделе "Установка или удаление программ". Если значок не задан, то используется значок по умолчанию.
-ip, -IncludeProviderURL url	true	Манифесты развертывания.	Указывает, содержит ли манифест развертывания значение расположения обновления, заданное -ProviderURL .
-i, -Install willInstall	true	Манифесты развертывания.	Показывает, должно ли приложение ClickOnce устанавливаться на локальном компьютере или оно должно запускаться из Интернета. Установка приложения приводит к появлению этого приложения в меню Пуск Windows. Допустимыми являются значения "true" или "t" и "false" или "f". Если задан параметр -MinVersion и пользователь использует версию, меньшую заданного значения -MinVersion, этот параметр вызывает принудительную установку приложения, независимо от значения, переданного в -Install. Данный параметр не может использоваться одновременно с параметром -BrowserHosted. Попытка задать оба параметра в одном манифесте приведет к ошибке.
-mv, -MinVersion [version]	Версия, используемая в манифесте развертывания ClickOnce и заданная флагом -Version.	Манифесты развертывания.	Минимальная версия этого приложения, которую может выполнить пользователь. Этот флаг делает названную версию приложения обязательным обновлением. Если разработчик выпускает версию своего продукта с исправлением критического изменения или критической уязвимости безопасности, можно использовать этот флаг, чтобы указать обязательность установки этого обновления и невозможность для пользователя дальнейшего использования предыдущих версий приложения. Семантика параметра version совпадает с семантикой аргумента флага -Version.
-n, -Name nameString	Развертывание	Все типы файлов.	Имя, используемое для идентификации приложения. Технология ClickOnce будет использовать это имя для идентификации приложения в меню Пуск (если для приложения настроена автоматическая установка) и в диалоговых окнах повышения уровня разрешений. Примечание Если при обновлении существующего манифеста имя издателя не указывается с помощью этого параметра, программа Mage.exe обновляет манифест, используя имя организации, определенное на компьютере.Чтобы использовать другое имя, обязательно используйте этот параметр и задайте нужное имя издателя.
-pwd, -Password passwd		Все типы файлов.	Пароль, используемый для подписания манифеста с помощью цифрового сертификата. Должен использоваться вместе с параметром -CertFile.
-p, Processor processorValue	Msil	Манифесты приложений. Манифесты развертывания.	Архитектура микропроцессора, на которой будет выполняться это развертывание. Это значение обязательно при подготовке одной или нескольких инсталляций, компиляция сборок которых для конкретного микропроцессора была выполнена заранее. Допустимые значения — msil, x86, ia64 и amd64. msil – это язык MSIL, который означает, что все сборки являются независимыми от платформы, и среда CLR будет выполнять JIT-компиляцию их при первом запуске приложения.
-pu, -ProviderURL url		Манифесты развертывания.	Задает URL-адрес, который будет использоваться технологией ClickOnce для обновлений приложений.
-pub, -Publisher publisherName		Манифесты приложений. Манифесты развертывания.	Добавляет имя издателя в элемент описания либо манифеста развертывания, либо манифеста приложения. При использовании этого параметра для манифеста приложения должен быть также задан параметр -UseManifestForTrust со значением "true" или "t", в противном случае этот параметр вызовет ошибку.
-s, -SupportURL url		Манифесты приложений. Манифесты развертывания.	Указывает ссылку, которая появляется в диалоговом окне "Установка и удаление программ" для приложения ClickOnce.
-ti, -TimestampUri uri		Манифесты приложений. Манифесты развертывания.	URL-адрес службы цифровых штампов времени. Установка меток времени в манифестах предотвращает необходимость повторной подписи манифестов в случае, когда срок действия цифрового сертификата истекает до развертывания следующей версии приложения. Дополнительные сведения см. на странице .
-t, -ToFile filePath	Новая: Deployment: deploy.application Application: application.exe.manifest Update: Входной файл.	Все типы файлов.	Задает выходной путь для созданного или измененного файла. Если при использовании команды -New не задан параметр -ToFile, результат записывается в текущий рабочий каталог. Если при использовании команды -Update не задан параметр -ToFile, программа Mage.exe записывает файл обратно во входной файл.
-tr, -TrustLevel level	Intranet	Манифесты приложений.	Уровень доверия, предоставляемый приложению на клиентских компьютерах. Возможными значениями являются Internet, Intranet и FullTrust.
-um, -UseManifestForTrust willUseForTrust	False	Манифесты приложений.	Определяет, будет ли использоваться цифровая подпись манифеста приложения для принятия решений о доверии при выполнении приложения на клиенте. Задание значения "true" или "t" показывает, что для решений о доверии будет использоваться манифест приложения. Задание значения "false" или "f" показывает, что будет использоваться подпись манифеста развертывания.
-v, -Version versionNumber	1.0.0.0	Манифесты приложений. Манифесты развертывания.	Версия развертывания. Этот аргумент должен быть допустимой версией строки в формате "N.N.N.N", где "N" — это 32-разрядное целое число без знака.
-wpf, -WPFBrowserApp isWPFApp	false	Манифесты приложений. Манифесты развертывания.	Этот флаг используется, только если приложение является приложением Windows Presentation Foundation (WPF), размещаемым внутри обозревателя Internet Explorer, а не автономным исполняемым файлом. Допустимыми являются значения "true" или "t" и "false" или "f". Для манифестов приложений вставляет атрибут hostInBrowser под элементом entryPoint манифеста приложения. Для манифестов развертывания устанавливает значение атрибута install для элемента deployment равным false и сохраняет манифест развертывания, используя расширение XBAP. Задание этого аргумента вместе с аргументом -Install приводит к ошибке, так как приложение, помещаемое в обозреватель, не может быть устанавливаемым, автономным приложением.

Параметры команды Sign

Следующая таблица содержит параметры, поддерживаемые командой -Sign, применяемой ко всем типам файлов.

Заметки

Все аргументы программы Mage.exe не зависят от регистра символов. Командам и параметрам должен предшествовать дефис (-) или косая черта (/).

Все аргументы, используемые с командой -Sign, всегда можно использовать и вместе с командами -New или -Update. Следующие команды являются эквивалентными.

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

Подписание — это последняя задача, которую должен выполнить разработчик, так как подписанный документ использует хэш-значение файла, чтобы проверить правильность подписи документа. При внесении в файл любых изменений разработчик должен подписать этот файл снова. Если подписывается документ, который уже был подписан, программа Mage.exe заменяет старую подпись новой.

При использовании параметра -AppManifest для заполнения манифеста развертывания программа Mage.exe предполагает, что манифест приложения будет находиться в том же каталоге, что и манифест развертывания, в подкаталоге, название которого соответствует текущей версии развертывания, и соответствующим образом настраивает манифест развертывания. Если манифест приложения будет находиться в другом месте, для установки альтернативного местонахождения можно использовать параметр -AppCodeBase.

Перед развертыванием приложения манифест развертывания и манифест приложения должны быть подписаны. Руководство по подписанию документов см. в разделе Общие сведения о развертывании доверенных приложений.

Параметр -TrustLevel для манифестов приложений описывает набор разрешений, необходимых приложению для выполнения на клиентском компьютере. По умолчанию уровень доверия, назначаемый приложениями, зависит от зоны, в которой находится URL-адрес. Приложения, развертываемые по корпоративной сети, обычно помещаются в зоне интрасети, а приложения, развертываемые через Интернет, помещаются в зоне Интернет. Обе зоны безопасности налагают на приложение ограничения доступа к локальные ресурсам. При этом зона интрасети предоставляет чуть больше прав, чем зона Интернет. Зона надежных узлов (FullTrust) предоставляет приложениям полный доступ к локальным ресурсам компьютера. При использовании параметра -TrustLevel для помещения приложения в эту зону компонент CLR "Диспетчер доверия" предложит пользователю решить, предоставлять ли этот повышенный уровень доверия. Если приложение развертывается по корпоративной сети, можно использовать развертывание надежных приложений, чтобы повысить уровень доверия приложения без участия пользователя.

Манифесты приложения также поддерживают настраиваемые разделы доверия. Это помогает приложению соблюдать принцип безопасности (запрос минимально необходимых разрешений), позволяя настроить манифест на запрос только конкретных разрешений, требуемых приложению для выполнения. Программа Mage.exe непосредственно не поддерживает добавление настраиваемого раздела доверия. Такой раздел можно добавить с помощью текстового редактора, анализатора XML или графического средства MageUI.exe. Дополнительные сведения об использовании средства MageUI.exe для добавления настраиваемых разделов доверия см. в разделе MageUI.exe (средство создания и редактирования манифестов, графический клиент).

Новые манифесты, созданные с помощью Mage.exe версии 4, включенной в Visual Studio 2010, предназначены для Клиентский профиль .NET Framework 4. Для использования более ранних требуемых версий платформы .NET Framework следует использовать более раннюю версию программы Mage.exe. При добавлении или удалении сборок из существующего манифеста или повторном подписывании существующего манифеста MageUI.exe не перенацеливает манифест на Клиентский профиль .NET Framework 4. В следующих таблицах показаны эти возможности и ограничения.

Mage.exe создает новые манифесты, предназначенные для Клиентский профиль .NET Framework 4. Приложения ClickOnce, предназначенные для Клиентский профиль .NET Framework 4, могут работать как в Клиентский профиль .NET Framework 4, так и в полной версии .NET Framework 4. Если приложение предназначено для полной версии .NET Framework 4 и не может выполняться в Клиентский профиль .NET Framework 4, удалите клиентский элемент <framework> с помощью текстового редактора и повторно подпишите манифест. Ниже приведен пример элемента <framework>, предназначенного для Клиентский профиль .NET Framework 4.

<framework targetVersion="4.0" profile="client" supportedRuntime="4.0.20506" />

Примеры

В следующем примере открывается пользовательский интерфейс для Mage (MageUI.Exe).

mage

В следующих примерах создаются манифест развертывания по умолчанию и манифест приложения. Эти файлы создаются в текущем рабочем каталоге и называются deploy.application и application.exe.manifest, соответственно.

mage -New Deployment
mage -New Application

В следующем примере создается манифест приложения, заполненный всеми сборками и файлами ресурсов из текущего каталога.

mage -New Application -FromDirectory . -Version 1.0.0.0

Следующие пример продолжает предыдущий пример, задавая имя развертывания и целевой микропроцессор. В нем также задается URL-адрес, который технология ClickOnce должна использовать для проверки обновлений.

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

В следующем примере показывается создание пары манифестов для развертывания приложения WPF, размещаемого в обозревателе Internet Explorer.

mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp true
mage -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 <passwd>

См. также

Задачи

Разбор примера: развертывание вручную приложения ClickOnce

Ссылки

MageUI.exe (средство создания и редактирования манифестов, графический клиент)

Командная строка Visual Studio и пакета Windows SDK

Основные понятия

Развертывание и безопасность технологии ClickOnce

Общие сведения о развертывании доверенных приложений