Средство создания и редактирования манифеста (Mage.exe)
Обновлен: Ноябрь 2007
Средство создания и редактирования манифеста (Mage.exe) — это средство командной строки, поддерживающее создание и редактирование манифестов приложений и развертываний. В качестве средства командной строки программа Mage.exe может быть выполняться как в пакетных сценариях, так и в других Windows-приложениях, включая приложения ASP.NET.
Вместо Mage.exe также можно использовать MageUI.exe, графическое приложение. Дополнительные сведения см. в разделе Средство создания и редактирования манифестов, графический клиент (MageUI.exe).
Средства Mage.exe и MageUI.exe доступны в различных местоположениях, включая следующие:
Пакет SDK .NET Framework 2.0 Пакет .NET Framework 2.0 SDK доступен в качестве компонента установки Visual Studio 2005 или он может быть загружен с веб-узла Майкрософт.
Набор инструментальных средств разработки (SDK) Windows для Windows Vista. Пакет Windows SDK для Windows Vista можно загрузить с веб-узла "Центр загрузки Майкрософт".
Visual Studio 2008. Более поздние версии средств Mage.exe и MageUI.exe включены в пакет установки Visual Studio 2008.
Mage [commands] [commandOptions]
Параметры
В следующей таблице показаны команды, поддерживаемые Mage.exe. Дополнительные сведения о параметрах, поддерживаемых этими командами, см. в разделах Параметры команд New и Update и Параметры команды Sign.
Команда |
Описание |
|---|---|
-cc, ClearApplicationCache |
Очищает кэш загруженных приложений для всех приложений, работающих интерактивно по сети. |
-n, -Newтип_файла [новые_параметры] |
Создает новый файл заданного типа. Допустимыми являются следующие типы:
Если с этой командой не задано никаких дополнительных параметров, она создаст файл соответствующего типа, с соответствующими тегами по умолчанию и значениями атрибутов. Чтобы задать имя файла и путь для нового файла, используется параметр –ToFile (см. в следующей таблице). Чтобы создать манифест приложения со всеми сборками приложения, добавленными в раздел <dependency> манифеста, используется параметр –FromDirectory (см. в следующей таблице). |
-u, -Update[путь_файла] [параметры_обновления] |
Вносит один или несколько изменений в файл манифеста. Задавать тип редактируемого файла не требуется. Программа Mage.exe проверит файл, используя набор эвристик, и определит, является ли он манифестом развертывания или манифестом приложения. Если разработчик уже подписал файл, используя сертификат, параметр -Update удалит блок подписи ключа. Это обусловлено тем, что подпись ключа содержит хэш-файла и изменение файла делает хэш недействительным. Чтобы задать имя и путь нового файла вместо перезаписи существующего файла, используется параметр –ToFile (см. в следующей таблице). |
-s, -Sign[signOptions] |
Использует сертификат для подписи файла. Подписи вставляются в файлы в виде XML-элементов. |
-h, -?, -Help[verbose] |
Описывает все доступные команды и их параметры. Задайте параметр verbose, чтобы получить подробную справку. |
Параметры команд New и Update
В следующей таблице приведены параметры, поддерживаемые командами –New и –Update.
Параметры |
Значение по умолчанию |
Применение |
Описание |
|---|---|---|---|
-appc, -AppCodeBasemanifestReference |
Манифесты развертывания. |
Вставляет в файл манифеста приложения ссылку на URL-адрес или путь к файлу. Этот файл должен быть полным путем к манифесту приложения. |
|
-appm, -AppManifestmanifestPath |
Манифесты развертывания. |
Вставляет ссылку на манифест приложения в соответствующий манифест развертывания. Файл, задаваемый параметром manifestPath, должен существовать, или программа Mage.exe выдаст ошибку. Если файл, определяемый параметром manifestPath, не является манифестом приложения, программа Mage.exe выдаст ошибку. |
|
-cf, -CertFilefilePath |
Все типы файлов. |
Задает местонахождение цифрового сертификата для подписания манифеста. Этот параметр может использоваться в сочетании с параметром –Password, если для сертификата требуется пароль. |
|
-ch, -CertHashhashSignature |
Все типы файлов. |
Хэш-значение цифрового сертификата, хранящегося в хранилище персональных сертификатов клиентского компьютера. Оно соответствует строке отпечатка цифрового сертификата, отображаемого в консоли сертификатов Windows. Параметр hashSignature может быть задан или в верхнем, или в нижнем регистре, и может предоставляться либо как целая строка, либо в виде всех октетов отпечатка, разделенных пробелами, и всего отпечатка, заключенного в кавычки. |
|
-fd, -FromDirectorydirectoryPath |
Манифесты приложений. |
Заполняет манифест приложения описаниями всех сборок и файлов, найденных в каталоге 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 удалит из манифеста приложения все файлы, больше не существующие в каталоге. |
|
-i, -InstallwillInstall |
true |
Манифесты развертывания. |
Показывает, должно ли приложение ClickOnce устанавливаться на локальном компьютере или оно должно запускаться из Интернета. Установка приложения приводит к появлению этого приложения в меню Пуск Windows. Допустимыми являются значения "true" или "t" и "false" или "f". Если задан параметр –MinVersion и пользователь использует версию, меньшую заданного значения -MinVersion, этот параметр вызывает принудительную установку приложения, независимо от значения, переданного в -Install. Данный параметр не может использоваться одновременно с параметром -BrowserHosted. Попытка задать оба параметра в одном манифесте приведет к ошибке. |
-mv, -MinVersion [version] |
Версия, используемая в манифесте развертывания ClickOnce и заданная флагом -Version. |
Манифесты развертывания. |
Минимальная версия этого приложения, которую может выполнить пользователь. Этот флаг делает названную версию приложения обязательным обновлением. Если разработчик выпускает версию своего продукта с исправлением критического изменения или критической уязвимости безопасности, можно использовать этот флаг, чтобы указать обязательность установки этого обновления и невозможность для пользователя дальнейшего использования предыдущих версий приложения. Семантика параметра version совпадает с семантикой аргумента флага -Version. |
-n, -NamenameString |
deploy |
Все типы файлов. |
Имя, используемое для идентификации приложения. Технология ClickOnce будет использовать это имя для идентификации приложения в меню Пуск (если для приложения настроена автоматическая установка) и в диалоговых окнах повышения уровня разрешений. |
-pwd, -Passwordpasswd |
Все типы файлов. |
Пароль, используемый для подписания манифеста с помощью цифрового сертификата. Должен использоваться вместе с параметром –CertFile. |
|
-p, ProcessorprocessorValue |
msil |
Манифесты приложений. Манифесты развертывания. |
Архитектура микропроцессора, на которой будет выполняться это развертывание. Это значение обязательно при подготовке одной или нескольких инсталляций, компиляция сборок которых для конкретного микропроцессора была выполнена заранее. В число допустимых значений входят msil, x86, ia64 и amd64. msil обозначает язык MSIL, показывая, что все сборки являются независимыми от платформы, и среда CLR выполнит их JIT-компиляцию при первом запуске приложения. |
-pu,-ProviderUrlurl |
Манифесты развертывания. |
Задает URL-адрес, который будет использоваться технологией ClickOnce для обновлений приложений. |
|
-pub, -PublisherpublisherName |
Манифесты приложений. Манифесты развертывания. Это новый параметр в .NET Framework 3.5. |
Добавляет имя издателя в элемент описания либо манифеста развертывания, либо манифеста приложения. При использовании этого параметра для манифеста приложения должен быть также задан параметр -UseManifestForTrust со значением "true" или "t", в противном случае этот параметр вызовет ошибку. |
|
-ti, -TimestampUriuri |
Манифесты приложений. Манифесты развертывания. |
URL-адрес службы цифровых штампов времени. Установка меток времени в манифестах предотвращает необходимость повторной подписи манифестов в случае, когда срок действия цифрового сертификата истекает до развертывания следующей версии приложения. В настоящее время службу штампов времени поддерживает только Verisign. Универсальным кодом ресурса (URI), предоставляемым в качестве аргумента, должен быть "http://timestamp.verisign.com/scripts/timstamp.dll". |
|
-tr, -TrustLevellevel |
Intranet |
Манифесты приложений. |
Уровень доверия, предоставляемый приложению на клиентских компьютерах. Возможными значениями являются Internet, Intranet и FullTrust. |
-t, -ToFilefilePath |
|
Все типы файлов. |
Задает выходной путь для созданного или измененного файла. Если при использовании команды –New не задан параметр –ToFile, результат записывается в текущий рабочий каталог. Если при использовании команды –Update не задан параметр –ToFile, программа Mage.exe записывает файл обратно во входной файл. |
-u, -UseManifestForTrustwillUseForTrust |
false |
Манифесты приложений. Это новый параметр в .NET Framework 3.5. |
Определяет, будет ли использоваться цифровая подпись манифеста приложения для принятия решений о доверии при выполнении приложения на клиенте. Задание значения "true" или "t" показывает, что для решений о доверии будет использоваться манифест приложения. Задание значения "false" или "f" показывает, что будет использоваться подпись манифеста развертывания. |
-v, -VersionversionNumber |
1.0.0.0 |
Манифесты приложений. Манифесты развертывания. |
Версия развертывания. Этот аргумент должен быть допустимой версией строки в формате "N.N.N.N", где "N" — это 32-разрядное целое число без знака. |
-wpf, -WPFBrowserApp isWPFApp |
false |
Манифесты приложений. Манифесты развертывания. Это новый параметр в .NET Framework 3.5. |
Этот флаг используется, только если приложение является приложением Windows Presentation Foundation (WPF), размещаемым внутри обозревателя Internet Explorer, а не автономным исполняемым файлом. Допустимыми являются значения "true" или "t" и "false" или "f". Для манифестов приложений вставляет атрибут hostInBrowser под элементом entryPoint манифеста приложения. Для манифестов развертывания устанавливает значение атрибута install для элемента deployment равным false и сохраняет манифест развертывания, используя расширение XBAP. Задание этого аргумента вместе с аргументом -Install приводит к ошибке, так как приложение, помещаемое в обозреватель, не может быть устанавливаемым, автономным приложением. |
Параметры команды Sign
Следующая таблица содержит параметры, поддерживаемые командой –Sign, применяемой ко всем типам файлов.
Параметры |
Описание |
|---|---|
-cf, -CertFilefilePath |
Задает местонахождение цифрового сертификата для подписания манифеста. Этот параметр может использоваться вместе с параметром –Password. |
-ch, -CertHashhashSignature |
Хэш-значение цифрового сертификата, хранящегося в хранилище персональных сертификатов клиентского компьютера. Оно соответствует свойству Thumbprint цифрового сертификата, отображаемого в консоли сертификатов Windows. Параметр hashSignature может быть задан или в верхнем, или в нижнем регистре, и может предоставляться либо как целая строка, либо в виде всех октетов свойства Thumbprint, разделенных пробелами, и всего свойства Thumbprint, заключенного в кавычки. |
-p, -Passwordpasswd |
Пароль, используемый для подписания манифеста с помощью цифрового сертификата. Должен использоваться вместе с параметром –CertFile. |
-t, -ToFilefilePath |
Задает выходной путь для созданного или измененного файла. |
Заметки
Все аргументы программы 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 или графического средства MageGUI.exe. Дополнительные сведения об использовании MageGUI.exe для добавления настраиваемых разделов доверия см. в разделе Средство создания и редактирования манифестов, графический клиент (MageUI.exe).
Примеры
В следующем примере открывается пользовательский интерфейс для Mage (MageUI.Exe).
mage
В следующих примерах создаются манифест развертывания по умолчанию и манифест приложения. Эти файлы создаются в текущем рабочем каталоге и называются deploy.application и application.exe.manifest, соответственно.
mage –New Deployment
mage –New Application
mage –New TrustLicense
В следующем примере создается манифест приложения, заполненный всеми сборками и файлами ресурсов из каталоге приложенияHelloWorld.
mage –New Application –FromDirectory \bin -Version 1.0.0.0
Следующие пример продолжает предыдущий пример, задавая имя развертывания и целевой микропроцессор. В нем также задается URL-адрес, который технология ClickOnce должна использовать для проверки обновлений.
mage –New Application –FromDirectory \bin -Name "Hello, World! Application" –Version 1.0.0.0 –Processor "x86" –ProviderUrl http://internalserver/HelloWorld/
В следующем примере показывается создание пары манифестов для развертывания приложения WPF, размещаемого в обозревателе Internet Explorer.
mage –New Application –FromDirectory \bin -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)