Средство слияния ASP.NET (Aspnet_merge.exe)
Обновлен: Ноябрь 2007
Средство слияния ASP.NET (Aspnet_merge.exe) позволяет объединять сборки, которые создаются средством компиляции ASP.NET (Aspnet_compiler.exe), и управлять ими. Средство слияния ASP.NET работает со сборками, которые были созданы с помощью ASP.NET 2.0 или более поздней версии.
Можно использовать средство компиляции ASP.NET для предварительной компиляции приложения в целях развертывания. Это средство создает одну сборку для каждой папки содержимого в целевом веб-узле или создает одну сборку для каждого файла содержимого. Средство слияния ASP.NET предоставляет дополнительную гибкость при развертывании и управлении выпуском. Оно позволяет выполнять следующие действия:
Создать одну сборку для всего веб-узла.
Создать сборку для каждой папки веб-узла и добавить префикс к имени сборки.
Создать простую сборку только для элементов пользовательского интерфейса веб-узла, таких как страницы и элементы управления.
aspnet_merge [-?]
applicationPath
[-keyfile filename [-delaysign]]
[-o assemblyname | -w assemblyname | -prefix prefix]
[-copyattrs [assemblyfile]]
[-debug]
[-nologo]
[-errorstack]
[-r]
[-xmldocs]
[-a]
[-logfile logfile]
[-allowattrs textfile]
Аргументы
Аргумент |
Описание |
|---|---|
applicationPath |
(Необходимо) Указывает имя папки, в которой содержится приложение, для которого следует создать сборки. Это операция слияния по умолчанию. Она создает меньше сборок, по сравнению с количеством, созданным параметром fixednames компилятора. |
Параметры
Параметр |
Описание |
|---|---|
-keyfile filename |
Указывает, что атрибут AssemblyKeyFileAttribute должен быть применен к скомпилированной сборке. Атрибут указывает имя файла, который содержит пару открытого и закрытого ключа, которая используется для создания строгого имени. Если входные сборки подписаны и средство слияния не подписывает сборки, будет отображено предупреждение об удалении ключей. Если имя файла ключа не указано, средство слияния завершится со сбоем в том случае, если одна сборка будет иметь открытый ключ, а другая нет. |
-delaysign |
Указывает, что атрибут AssemblyDelaySignAttribute должен быть применен к созданной сборке. Этот атрибут указывает, что сборка должна быть подписано только маркером открытого ключа, а не парой открытого и закрытого ключа. Этот параметр необходимо использовать совместно с параметром -keyfile. Если атрибут уже применен к сборке в файлах кода, средство слияния создает исключение. Если при использовании параметра delaysign проверка строгого имени не включена, код, созданный с помощью средства слияния, может работать до подписи кода. Если проверка строгого имени не включена, убедитесь, что код не подвержен атакам злоумышленников до подписания. |
-o assemblyname |
Указывает имя отдельной объединенной сборки для всего содержимого пользовательского интерфейса веб-узла и всех сборок верхнего уровня. Все файлы, которые имеют расширение COMPILED, изменяются для включения ссылки на отдельную сборку. (Файлы с расширением COMPILED компилируются из файлов содержимого ASPX, MASTER и ASCX). Данный параметр нельзя сочетать с параметрами w или prefix. Параметр assemblyname является обязательным. |
-w assemblyname |
Указывает имя отдельной объединенной сборки для всего содержимого пользовательского интерфейса веб-узла (страниц и пользовательских элементов управления). Все скомпилированные файла ASPX, MASTER и ASCX изменяются для включения ссылки на отдельную сборку. Это позволяет обновить элементы пользовательского интерфейса отдельно от кода. Сборки верхнего уровня для локальных и глобальных ресурсов не объединяются. Данный параметр несовместим с параметрами o или prefix. Параметр assemblyname является обязательным. |
-prefix prefix |
Указывает префикс для имен сборок. Корневая папка сборки содержит только параметр prefix в качестве имени сборки. Сборки во вложенных папках содержат параметр prefix, объединенный с именем вложенной папки. Например, если вложенная папка называется Admin, в результате именем сборки будет prefix.Admin.dll. Для веб-узлов, которые не могут быть обновлены, средство компиляции компилирует темы и локальные ресурсы в отдельных сборках в папке Bin. Для веб-узлов, которые могут быть обновлены, темы и локальные ресурсы не компилируются в сборки в папке Bin. Вместо этого они остаются в исходных папках приложения. Кроме того, для обновляемых узлов средство слияния изменяет файлы ASPX, MASTER и ASCX для указания на новую, объединенную сборку в папке, где находятся эти файлы. Данный параметр несовместим с параметрами o или w. Параметр prefix является обязательным. |
-copyattrs assemblyfile |
Указывает, что объединенная сборка или несколько сборок должны иметь одинаковые атрибуты сборки, как и обозначенная сборка. Если assemblyFile не указан, используется сборка App_Code, даже если сборка верхнего уровня App_Code.dll не включена в объединенные выходные данные. Если присутствует несогласованный атрибут, который отличается в объединяемой сборке и в сборке assemblyFile, создается ошибка. Используйте параметр a для обхода проверки несогласованности атрибутов или используйте параметр allowattrs для указания атрибута, который следует исключить из проверки. Атрибуты, которые не включены в проверку согласованности, см. в описании параметра allowattrs в другой части таблицы. |
-debug |
Указывает, что выходные данные отладки должны быть сохранены в объединенной сборке. |
-nologo |
Отменяет вывод уведомления об авторских правах. |
-errorstack |
Указывает, что программа должна включить информацию трассировки стека, если компиляция приложения не удалась. |
-r |
Удаляет файлы COMPILED из сборки основного кода (код в папке App_Code). Не используйте этот параметр, если приложение содержит явный ссылочный тип на сборку основного кода. |
-xmldocs |
Объединяет файлы XML-документации, которые связаны со сборками входных данных. XML-файл включен в папку Bin объединенного узла. |
-a |
Принудительно заставляет средство слияния объединять сборки, не все из которых содержат примененный атрибут AllowPartiallyTrustedCallersAttribute или которые содержат несогласованные атрибуты. Атрибут AllowPartiallyTrustedCallersAttribute позволяет вызывающим объектам с частичным доверием получать доступ к сборке. Этот атрибут определяется во время компиляции, выполняемой средством компиляции. .gif "Важное примечание") Важное примечание.
При использовании параметра a объединенные сборки, которые ранее были отмечены как разрешающие вызовы от объектов с частичным доверием, теперь отмечены как AllowPartiallyTrustedCallersAttribute. Это может привести к тому, что код с частичным доверием сможет вызвать сборку.
|
-log logfile |
Записывает сообщения в указанный файл. |
-allowattrs textfile |
Указывает файл, который содержит атрибуты, исключаемые при проверке средством согласованности атрибутов в объединенных сборках. Каждая строка этого файла может являться или полным именем атрибута или полным именем пространства имен. Если указано пространство имен, все атрибуты, найденные в этом пространстве имен, будут исключены. Каждый атрибут или пространство имен должно находиться в отдельной строке. Некоторые атрибуты не обязательно должны быть явно указаны. Средство слияния выводит предупреждение при обнаружении следующих атрибутов, а затем продолжает выполнение. |
-? |
Отображает синтаксис команд и параметров программы. |
Заметки
Веб-приложения ASP.NET могут быть скомпилированы на месте или могут быть предварительно скомпилированы для развертывания в целевом расположении, например на производственном сервере. Компиляция приложения на месте называется динамической компиляцией и бывает полезной в сценариях быстрого развертывания. Предварительная компиляция приложения для развертывания может быть выполнена двумя способами:
Компиляция и удаление всех исходных файлов, таких как файлов с выделенным кодом и файлов маркировки.
Компиляция и сохранения файлов маркировки для их последующего обновления.
Средство слияния ASP.NET предоставляет дополнительную гибкость при предварительной компиляции веб-узла по сравнению с использованием средства компиляции ASP.NET.
Средство слияния ASP.NET объединяет выходные данные средства компиляции ASP.NET для создания сборок. Эти объединенные сборки могут улучшить управления выпусками и развертыванием на больших веб-узлах. Можно использовать средство слияния ASP.NET тремя способами:
Объединить все выходные данные в одной сборке.
Объединить содержимое каждой папки пользовательского интерфейса веб-узла (веб-страницы, обложки и т. д.) в собственную сборку.
Объединить все содержимое пользовательского интерфейса веб-узла в единую сборку.
Эти сценарии описаны в следующих разделах. Примеры использования средства слияния ASP.NET Merge см. в статье посвященной управлению выходными данными предварительной компиляции ASP.NET для развертывания с помощью команды aspnet_merge.exe Command, на веб-узле MSDN (может быть на английском языке).
Средство слияния ASP.NET не включено в проекты установки и развертывания Visual Studio в Интернете — надстройку для Visual Studio, с помощью которой можно управлять конфигурациями построения, указывать задачи, которые следует выполнить до и после построения и объединять сборки. Дополнительные сведения см. в статье, посвященной использованию проектов развертывания в Интернете с помощью Visual Studio 2005 (может быть на английском языке).
Группы сборок
Средство компиляции создает сборки по-разному в зависимости от типа исходного файла и папки. Выходные данные из средства компиляции могут быть разделены на две группы сборок. Средство слияния объединяет две группы сборок по-разному.
Ниже приведены эти группы сборок:
Сборки содержимого пользовательского интерфейса веб-узла, которые создаются из файлов содержимого пользовательского интерфейса веб-узла, таких как ASPX, ASCX, MASTER, ASHX, SKIN и локальных файлов RESX (в папке App_LocalResources). Способы слияния этих сборок зависят от того, является ли предварительно скомпилированный узел обновляемым, а это определяется по параметру u в средстве компиляции. Если скомпилированный узел является обновляемым, содержимое пользовательского интерфейса может быть обновлено без повторной компиляции узла. Если веб-узел является обновляемым, файлы содержимого остаются в своих исходных папках, а объединяются только файлы связанного кода. Если узел не является обновляемым, файлы содержимого ASCX, MASTER и SKIN удаляются из своих исходных папок. Файлы ASPX в ASP.NET заменены файлом маркера, который не имеет содержимого. В этом случае содержимое и код пользовательского интерфейса объединяются.
Сборки верхнего уровня, то есть сборки, созданные из папок приложения, таких как App_Code, App_GlobalResources, App_WebReferences. Сборки верхнего уровня также создаются для определенных файлов, таких как Global.asax. Сборки верхнего уровня всегда компилируются в папке Bin на узле развертывания. Узел окончательного развертывания не будет содержать папки App_Code, App_GlobalResources и App_WebReferences или файла Global.asax. Вместо этого узел окончательного развертывания будет иметь одну или несколько сборок в каталоге Bin в зависимости от параметров, используемых в средстве слияния. Папки, определенные пользователем, всегда компилируются, кроме тех случаев, когда узел окончательного развертывания сохраняет папку, определенную пользователем, которая содержит файлы содержимого пользовательского интерфейса. Дополнительные сведения о зарезервированных папках см. в разделе Макет веб-узла ASP.NET.
Статическое содержимое, такое как файлы, имеющие расширения CSS, GIF, HTM, HTML, JPG, JS, остаются в своем исходном расположении в предварительно скомпилированной структуре каталогов. Средство слияния не перемещает и не изменяет их.
Сценарии компиляции и слияния
В ASP.NET 2.0 можно использовать комбинацию динамической компиляции, предварительной комбинации с помощью средства компиляции и объединения с помощью средства слияния для достижения целей развертывания и выпуска. В следующей таблице приведены сценарии компиляции и слияния и обозначены ситуации, в которых следует использовать средство слияния.
Сценарий |
Примечания |
|---|---|
Динамическая компиляция (без предварительной компиляции) |
Динамическая компиляция полезна в сценариях быстрой разработки. В Visual Studio используется динамическая компиляция — при нажатии клавиши F5 или сочетания клавиш CTRL+F5 динамически компилируется только та страница, с которой работает пользователь, а также все зависимые элементы. Это позволяет избежать компиляции всего веб-узла. Дополнительные сведения см. в разделе Основные сведения о динамической компиляции ASP.NET. |
Предварительная компиляция происходит с целью создания единой сборки для каждого файла содержимого пользовательского интерфейса на веб-узле с помощью Aspnet_compiler.exe с установленным параметром fixednames. |
При предварительной компиляции с использованием параметра fixednames можно выполнять добавочные обновления различных единиц, таких как отдельные страницы, и повторно развертывать только изменившиеся страницы. Можно создать как обновляемые, так и необновляемые предварительно скомпилированные узлы посредством параметра u и параметра fixednames. Параметр fixednames не влияет на способ дальнейшего слияния сборок с помощью средства слияния. На больших узлах большое количество сборок, созданных с помощью параметра fixednames, может вызвать проблемы, связанные с управлением выпусками или развертыванием. Дополнительные сведения см. в разделе Программа компиляции для ASP.NET (Aspnet_compiler.exe). |
Объединение для создания сборки для каждой папки содержимого пользовательского интерфейса веб-узла с помощью Aspnet_merge.exe с параметром prefix. |
В этом сценарии можно управлять сборками на уровне папки содержимого пользовательского интерфейса. Этот сценарий похож на исключение параметра fixenames при использовании средства компиляции. Отличие состоит в том, что средство компиляции предоставляет большее управления именами окончательных сборок, которые являются производными из корневой папки и из папок содержимого, определенных пользователем. Это не влияет на сборки верхнего уровня и статическое содержимое. Потенциальным недостатком этого сценария является то, что при изменении файла в папке необходимо будет повторно развертывать сборку папки и измененную страницу. Можно объединять как обновляемые, так и необновляемые предварительно скомпилированные узлы с помощью параметра prefix. Этот сценарий является сценарием по умолчанию, если используется средство слияния без параметров. |
Объединение для создания отдельной сборки для всех файлов содержимого пользовательского интерфейса веб-узла с помощью Aspnet_merge.exe с параметром w. |
В этом сценарии все содержимое пользовательского интерфейса объединяется в одну сборку, которое имеет имя, указанное в параметре assemblyname. Это уменьшает общее количество сборок в окончательно развернутом узле. Однако также необходимо повторно развернуть сборку содержимого пользовательского интерфейса, если один из файлов содержимого был изменен. Это не влияет на сборки верхнего уровня и статическое содержимое. |
Объединение для создания единой сборки для всего веб-узла с помощью Aspnet_merge.exe с параметром o. |
В этом сценарии окончательно развернутый узел содержит только одну сборку, которое имеет имя, указанное в параметре assemblyname. Отдельная сборка облегчает развертывание узла. Однако это означает, что если любое содержимое изменяется где-либо на узле, придется повторно создавать и повторно развертывать сборку узла. Сборки верхнего уровня (App_Code, App_GlobalResources и App_WebReferences) затрагиваются, так как они включены в единую сборку. Статическое содержимое в этом процессе не участвует. |
Объединение приложения для развертывания
Сборки для веб-узла объединяются посредством выполнения средства слияния и указания расположения предварительно скомпилированного сайта с параметром applicationPath. Средство слияния ASP.NET объединяет предварительно скомпилированный узел на месте. Другими словами, средство не создает новую объединенную копию предварительно скомпилированного узла. Параметр applicationPath может указывать окончательное расположение веб-приложения. Кроме того, скомпилированное приложение может быть в дальнейшем развернуто, например путем копирования каталога.
При объединении средством слияния предварительно скомпилированного узла, сохраняется расположение динамических файлов, как они отображались на этапе предварительной компиляции. Единственным изменением, вносимым средством слияния в содержимое динамических файлов, является изменения директив @ Page, @ Control и @ Master. Это гарантирует наследование файлами, содержащими эти директивы, правильной объединенной сборки в папке Bin. Сведения об обработке средством компиляции типов файлов см. в примечаниях к разделу Программа компиляции для ASP.NET (Aspnet_compiler.exe)
Для сборок, которые являются производными из папок, определенных пользователем (включая корневую папку узла), некоторые параметры объединения могут привести к созданию имен, которые будут отличаться от тех, что были заданы в предварительно скомпилированном узле. Например, в следующей таблице показаны имена объединенной сборки при использовании средства слияния без параметров. Имя сборки для каждой папки, определенной пользователем, является App_Web_nnnn.dll, где nnnn — это внутренне созданное хэш-значение.
Папка в предварительно скомпилированном узле |
Имя объединенной сборки без параметров Aspnet_merge.exe |
|---|---|
\ |
Root.dll |
Admin |
Admin.dll |
В следующем таблице показаны имена объединенной сборки при использовании параметра prefix и параметра NewName.
Папка в предварительно скомпилированном узле |
Имя объединенной сборки с параметром Aspnet_merge.exe prefix |
|---|---|
\ |
NewName.dll |
Admin |
NewName.Admin.dll |
Темы в объединенном узле, который не является обновляемым, обрабатываются по-другому. В предварительно скомпилированном, еще не объединенном узле существует отдельная сборка для каждой темы. Каждая сборка называется App_Theme_ThemeName.dll. В объединенном узле существует только одна сборка Theme.dll. Если предварительно скомпилированный узел является обновляемым, в объединенной папке Bin не будут присутствовать сборки, основанные на темах.
Устранение неполадок, связанных с процессом объединения
При компиляции и объединении веб-узла путь к сборке может стать длиннее, чем максимальная допустимая длина пути к файлу в Microsoft Windows. В этом случае при запросе ресурса из объединенной сборки создается ошибка HttpException, которая указывает, что ресурс не был предварительно скомпилирован и не может быть запрошен.
Максимальная длина пути к файлу в Microsoft Windows составляет 260 символов. Если длина пути сборки превышает это ограничение, необходимо укоротить путь или к самому веб-узлу, или к его вложенным папкам. Также можно отключить теневое копирование в файле Web.config с помощью свойства ShadowCopyBinAssemblies элемента hostingEnvironment. Дополнительные сведения об именах файлов см. в статье, посвященной именованию файлов File, на веб-узле MSDN (может быть на английском языке).
При использовании средства слияния с параметром o для создания отдельной сборки для узла, возникнет ошибка, если процесс объединения приведет к созданию цикличных ссылок. Существуют два способа решения этой проблемы.
Используйте параметр w, чтобы исходный файл, который содержит циклическую ссылку, воспринимался как внешняя ссылка и не участвовал в объединении.
Разнесите элементы управления, вовлеченные в циклическую ссылку, по отдельным каталогам.
При объединении сборок с несогласованными атрибутами используйте следующие правила, чтобы обеспечить успешное выполнение операции объединения:
Отобразите несогласованные атрибуты с помощью параметра allowattrs.
Используйте параметры copyattrs и убедитесь, что все сборки, которые должны объединяться, имели соответствующие атрибуты.
Используйте параметр a.
Подпись сборок
Параметры delaysign и keyfile позволяют использовать средство слияния для создания сборок со строгими именами без использования средства строгих имен (Sn.exe). Параметры delaysign соответствуют атрибуту AssemblyDelaySignAttribute, а параметр keyfile соответствует атрибуту AssemblyKeyFileAttribute.
Каждый параметр применяет соответствующий атрибут к объединенной сборке. Применяемые атрибуты помечаются с помощью атрибута AttributeUsageAttribute, свойство AllowMultiple которого задано как false. Поэтому если эти параметры используются при объединении сборок, которые уже отмечены с помощью одного из этих атрибутов, объединение завершится со сбоем.
Примеры
Следующая команда объединяет сборки предварительно скомпилированного узла в каталоге C:\PrecompiledSite.
Aspnet_merge C:\PrecompiledSite
Следующая команда объединяет сборки предварительно скомпилированного узла в каталоге C:\PrecompiledSite и подписывает объединенные сборки с помощью файла KeyFile.snk. Объединенный узел будет иметь только одну сборку для каждой предварительно скомпилированной папки.
Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk
Следующая команда объединяет все сборки предварительно скомпилированного узла в каталоге C:\PrecompiledSite directory в единую сборку и присваивает ей имя MyApp.dll. Объединенный узел будет иметь одну сборку для всего содержимого пользовательского интерфейса веб-узла.
Aspnet_merge C:\PrecompiledSite -w MyApp.dll
Следующая команда объединяет все сборки предварительно скомпилированного узла в каталоге C:\PrecompiledSite directory в единую сборку и присваивает ей имя MyApp.dll.
Aspnet_merge C:\PrecompiledSite -o MyApp.dll
См. также
Основные понятия
Ссылки
AllowPartiallyTrustedCallersAttribute