Генератор образов в машинном коде (Ngen.exe), традиционный синтаксис

Статья
08/11/2011

Сведения в этом разделе предназначены для пользователей платформы .NET Framework 1.0 и 1.1. Сведения о синтаксисе версии 2.0 см. в разделе Ngen.exe (генератор образов в машинном коде).

Генератор образов в машинном коде создает образы в машинном коде на основе управляемой сборки и устанавливает их в кэш образов в машинном коде на локальном компьютере. Кэш образов в машинном коде представляет собой зарезервированную область глобального кэша сборок. После создания образа в машинном коде для сборки среда выполнения автоматически использует этот образ при каждом запуске сборки. Для того, чтобы среда выполнения использовала образ в машинном коде, не нужно предпринимать никаких дополнительных действий. Применение инструмента Ngen.exe для сборки сокращает время ее загрузки и выполнения, так как код и структуры данных сборки не создаются динамически, а восстанавливаются из кэша образов в машинном коде.

ngen [options] [assemblyName |assemblyPath ]

Параметры

Аргумент	Описание
имя_сборки	Имя сборки, для которой создается образ в машинном коде. Сборка должна находиться в текущем каталоге. Можно предоставить либо частично указанное имя сборки, например myAssembly, либо полное имя сборки, например myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Полное имя сборки необходимо указывать, если Ngen.exe должен найти и использовать файл политики издателя сборки.
путь сборки	Полный путь к сборке, для которой создается образ в машинном коде. Можно указать полный путь к сборке, например c:\applications\myApp\myApp.exe, относительный путь, например .. \ applications\myApp\myApp.exe или имя файла, например myApp.exe. Если имя файла, например, myApp.exe, указывается без полного или относительного пути, сборка должна находиться в текущем каталоге. Чтобы Ngen.exe мог идентифицировать сборку как исполняемый файл и найти ее файл конфигурации, следует использовать аргумент путь_сборки для указания сборок с расширением EXE. Если в командной строке задано более одной сборки, только одна из сборок может быть исполняемым файлом. Программа применяет параметры привязки исполняемого файла (базовой папки приложения и любых файлов конфигурации) к другим указанным в командной строке сборкам.

имя_сборки

Имя сборки, для которой создается образ в машинном коде. Сборка должна находиться в текущем каталоге. Можно предоставить либо частично указанное имя сборки, например myAssembly, либо полное имя сборки, например myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Полное имя сборки необходимо указывать, если Ngen.exe должен найти и использовать файл политики издателя сборки.

путь сборки

Полный путь к сборке, для которой создается образ в машинном коде. Можно указать полный путь к сборке, например c:\applications\myApp\myApp.exe, относительный путь, например .. \ applications\myApp\myApp.exe или имя файла, например myApp.exe.

Если имя файла, например, myApp.exe, указывается без полного или относительного пути, сборка должна находиться в текущем каталоге.

Чтобы Ngen.exe мог идентифицировать сборку как исполняемый файл и найти ее файл конфигурации, следует использовать аргумент путь_сборки для указания сборок с расширением EXE.

Если в командной строке задано более одной сборки, только одна из сборок может быть исполняемым файлом. Программа применяет параметры привязки исполняемого файла (базовой папки приложения и любых файлов конфигурации) к другим указанным в командной строке сборкам.

Параметр	Описание
/debug	Создает образ для аппаратной платформы, который может использоваться отладчиком в обычном режиме отладки.
/debugopt	Создает образ в машинном коде, который может использоваться отладчиком в оптимизированном режиме отладки в общеязыковой среде выполнения. Подробности по активации этого режима см. в документации по отладчику.
/delete [assemblyName \| путь_к_сборке \| *]	Удаляет образы с указанными значениями имя_сборки или путь_сборки из кэша образов в машинном коде. Если указать в качестве значения параметра символ '', программа удалит из кэша образов в машинном коде все содержащиеся там образы. Если после параметра /delete* не указаны значения, программа выведет на экран сообщение об ошибке. При удалении версии .NET Framework процесс удаления использует параметр /delete для удаления всех образов удаляемой версии .NET Framework. В их число войдут как образы, созданные для сборок .NET Framework во время установки, так и образы, созданные пользователем для прочих сборок. Если указать /delete * вместе с параметром /show, программа выведет на экран список удаленных образов. Если на компьютере одновременно установлены несколько версий .NET Framework, для удаления образов в машинном коде необходимо использовать ту же самую версию Ngen.exe, которая использовалась для их создания. Примечание Этот параметр влияет только на образы в машинном коде, созданные с помощью Ngen.exe.Он не влияет на реальные сборки.
/help	Отображает синтаксис команд и параметры программы.
/nologo	Отключает отображение эмблемы Майкрософт при запуске.
/prof	Выполняет генерацию образа в машинном коде, предназначенного для профилировщика, работающего с инструментированным кодом. Сведения о том, требуется ли инструментированный код применяемому профилировщику, см. в документации профилировщика.
/show	Выводит существующие файлы образов, соответствующие указанным значениям имя_сборки илипуть_сборки и содержащиеся в кэше образов в машинном коде. Если аргументы не заданы, выводится все содержимое кэша образов в машинном коде. Этот параметр выводит данные определения сборки для исходной сборки и все специальные параметры конфигурации кода для каждого образа в машинном коде. Если этот параметр указан вместе с параметром /delete *, программа выведет на экран список удаленных образов в машинном коде.
/showversion	Выводит версию среды выполнения, которая будет использоваться Ngen.exe для того, чтобы создать образ указанной сборки. Если на компьютере одновременно установлены несколько версий .NET Framework, этот параметр задает версию, которую будет использовать инструмент. Дополнительные сведения о выполнении нескольких версий среды выполнения см. в разделе Параллельное выполнение. Примечание Указание этого параметра не приводит к созданию образа в машинном коде.
/silent	Отключает отображение сообщений об успешно выполненных операциях.
/?	Отображает синтаксис команд и параметры программы.

Заметки

Ngen.exe не использует стандартные правила зондирования сборок для нахождения сборок, указанных в командной строке. В процессе поиска указанных сборок Ngen.exe просматривает только текущий каталог. Таким образом, чтобы Ngen.exe мог обнаружить сборки, необходимо или объявить рабочим каталог, содержащий сборки, для которых следует создать образы, или задать полный путь к этим сборкам.

Образ в машинном коде представляет собой файл, в котором содержится скомпилированный для конкретного процессора машинный код. Следует заметить, что образ, созданный программой Ngen.exe, не может быть использован в других Доменах приложений. Это означает, что Ngen.exe нельзя использовать в сценариях приложений, в которых требуется совместное использование сборок несколькими доменами приложений.

Предварительно скомпилированные с помощью Ngen.exe сборки могут сократить время запуска приложений, поскольку большая часть работы, необходимой для исполнения кода, уже выполнена. Таким образом, более правильным будет использовать Ngen.exe для клиентских приложений, для которых известно, что расход циклов процессора на JIT-компиляцию при запуске вызывает понижение производительности.

Примечание
Для запуска Ngen.exe необходимо обладать правами администратора.

В связи с наличием множества факторов, влияющих на время запуска приложения, необходимо точно определить, какие приложения получают преимущества от использования Ngen.exe. Проверьте путем запуска JIT-скомпилированной и предварительного скомпилированной версий сборки-кандидата в среде, в которой она будет использоваться. Это позволит сравнить показатели времени запуска сборки при использовании различных схем компиляции.

После создания образа сборки среда выполнения автоматически пытается обнаружить и использовать этот образ при каждом запуске сборки. Так, например, при запуске сборки в рамках сценария отладки или профилировки среда выполнения ищет образ, созданный с параметрами /debug, /debugopt или /prof. Если найти соответствующий образ в машинном коде не удается, среда выполнения возвращается к стандартной схеме JIT-компиляции.

При запуске Ngen.exe для сборки, для которой установлен атрибут отлаживаемого кода, программа автоматически создает такой же код, как если бы в командной строке присутствовали параметры /debug или /debugopt, в зависимости от флагов атрибута.

Если Ngen.exe обнаруживает в сборке методы, которые он не может создать, эти методы исключаются из образа. Когда среда выполнения выполняет сборку, то при обнаружении метода, отсутствующего в образе в машинном коде, выполняется JIT-компиляция.

При использовании Ngen.exe для создания образа сборки результат зависит от заданных параметров командной строки и определенных характеристик компьютера. В число этих характеристик входят:

Версия .NET Framework.
CPU-тип.
Версия операционной системы.
Полное удостоверение сборки (оно изменяется при перекомпиляции).
Полное удостоверение всех сборок, на которых ссылается данная сборка (оно изменяется при перекомпиляции).
Факторы безопасности.

Ngen.exe сохраняет эти сведения при создании образа в машинном коде. При выполнении сборки среда выполнения просматривает созданный образ на предмет таких параметров и характеристик и сравнивает их с текущими параметрами и характеристиками среды. Если среда выполнения не находит соответствующего образа, выполняется JIT-компиляция. Изменения следующих параметров компьютера и среды приводят к тому, что образы устаревают, т. е. становятся непригодными для использования:

Версия .NET Framework.

При установке обновлении .NET Framework все образы, созданные вручную при помощи Ngen.exe, устаревают. Сборки по-прежнему будут работать, но среда выполнения не будет загружать их образы в машинном коде. Необходимо вручную создать для этих сборок новые образы.

.NET Framework автоматически создает новые образы для библиотек .NET Framework, которые она устанавливает.
CPU-тип.

Если заменить процессор компьютера на процессор из другого семейства, то все образы в машинном коде, хранящиеся в кэше образов в машинном коде, устареют.
Версия операционной системы.

Если изменится версия операционной системы, установленной на компьютере, то все образы, хранящиеся в кэше образов в машинном коде, устареют.
Полное удостоверение сборки.

При перекомпиляции сборки соответствующий образ устаревает.
Полное удостоверение всех сборок, на которых ссылается данная сборка.

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

Факторы безопасности.

Изменение политики безопасности на компьютере, сопровождающееся отменой разрешений, выданных сборке ранее, может привести к устареванию ранее скомпилированного образа сборки. К такому результату приводит, в частности, отмена любого из следующих разрешений:

Декларативное разрешение наследования, затребованное классом, от которого порождена сборка.
Декларативное разрешение этапа компоновки, затребованное методом, который вызывает сборка.
Разрешение SkipVerification, если сборка содержит непроверяемые методы. Дополнительные сведения о данном разрешении см. в разделе Свойство SecurityPermissionAttribute.SkipVerification.
Разрешение UnmanagedCode, если сборка использует вызовы PInvoke. Дополнительные сведения о данном разрешении см. в разделе Свойство SecurityPermissionAttribute.UnmanagedCode.

Если Ngen.exe выполняется для сборки с отключенным управлением доступа для кода, после включения защиты доступа для кода созданный образ устареет. Отметим, что по умолчанию управление доступом для кода включено.

Подробные сведения об управлении доступом для кода в среде CLR и об использовании разрешений см. в разделе Управление доступом для кода.

Примечание
В версии 1.0 общеязыковой среды выполнения автоматическое создание новых образов и удаление устаревших образов не предусмотрено.Необходимо вручную создавать и удалять все образы с помощью Ngen.exe.

При использовании Ngen.exe для создания образов в машинном коде во время установки необходимо указать имя файла приложения и полные имена сборок файлов .dll, на которые приложение ссылается во время компиляции. При указании полностью определенных имен файлов .dll, на которые ссылается приложение, Ngen.exe обращается к файлам политики издателей соответствующих сборок. В дальнейшем при обновлении файлов .dll и использовании политики издателя для перенаправления версий Ngen.exe будет использовать политику издателя.

Получить требуемые полные имена сборок можно, запустив для приложения программу Ildasm.exe и просмотрев манифест сборки. В манифесте содержится имя сборки, ее версия, язык и маркер открытого ключа для библиотек DLL, к которым приложение обращается во время компиляции. Так, например, чтобы создать образ для приложения с именем ClientApp.exe, которое компилируется с библиотекой myLibrary.dll версии 1.0.0.0, с параметрами culture=neutral и PublicKeyToken=0038abc9deabfle5, используйте команду ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".

Отметим, что в предыдущем примере образы сборок, на которые ссылается myLibrary.dll, не создавались. Чтобы определить полные имена сборок, на которые ссылается myLibrary.dll, запустите Ildasm.exe для myLibrary.dll. Например, если запустить Ildasm.exe для myLibrary.dll и определить, что она ссылается на myMath.dll, версии 1.0.0.0, с параметрами culture=neutral и PublicKeyToken=0039def8abcbste7, используйте следующую команду для создания образов в машинном коде для всего дерева ссылок сборок ClientApp.exe.

ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7".

Дополнительные сведения об этом формате см. ниже в разделе "Примеры".

В процессе удаления приложения следует использовать параметр /delete[имя_сборки| assemblyPath] – этот параметр используется для удаления собственных изображений, созданных во время установки приложения. Необходимо указать, какие образы следует удалить, задав параметр имя_сборки или путь_сборки. Задание параметра /delete * приведет к удалению всех образов в машинном коде из кэша образов в машинном коде, задание параметра /delete без аргументов вызовет ошибку.

Примеры

Следующая команда создает образ в машинном коде для программы ClientApp.exe, расположенной в текущем каталоге. Если для приложения имеется файл конфигурации, Ngen.exe будет использовать его. Программа не будет создавать образы для DLL, на которые ссылается ClientApp.exe.

ngen ClientApp.exe

Если ClientApp.exe напрямую ссылается на две библиотеки, myLibOne.dll и myLibTwo.dll, следует запустить Ngen.exe, указав ему полные имена сборок для этих DLL, чтобы создать образы для них. Чтобы определить полные имена библиотек DLL, на которые они ссылаются, запустите Ildasm.exe для ClientApp.exe. В нашем примере полные имена сборок myLibOne.dll и myLibTwo.dll следующие: "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" и "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Получив эти данные, можно составить команду, которая создаст образы для ClientApp.exe, myLibOne.dll, и myLibTwo.dll. Если для ClientApp.exe имеется файл конфигурации, Ngen.exe будет использовать его. Если для myLibOne.dll или myLibTwo.dll, имеется файл политики издателя, Ngen.exe будет использовать его.

ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

В предыдущем примере библиотеки DLL myLibOne.dll и myLibTwo.dll могут ссылаться на другие сборки. Чтобы определить полные имена сборок, на которые выполняются ссылки, запустите Ildasm.exe для myLibOne.dll и myLibTwo.dll.. В данном примере, предположим, что myLibOne.dll не ссылается ни на какие другие сборки, а myLibTwo.dll ссылается на "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7". Используя эти сведения, составим команду для создания образов полного дерева сборок, на которые ссылается приложение.

ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

Следующая команда создает образ в машинном коде для myAssembly.exe с указанным путем.

ngen c:\myfiles\myAssembly.exe

Следующая команда создает образ в машинном коде для myLibrary.dll, с указанным путем.

ngen c:\myfiles\myLibrary.dll

Ngen.exe просматривает кэш образов в машинном коде и удаляет сборку с указанным частичным именем. Следующая команда удаляет все образы в машинном коде с именем myAssembly.

ngen /delete myAssembly

Следующая команда удаляет образ в машинном коде myAssembly с полным именем сборки.

ngen /delete "myAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

Следующая команда выводит все образы в машинном коде в кэше образов в машинном коде.

ngen /show

Следующая команда выводит все содержащиеся в кэше образы в машинном коде с именем myAssembly.

ngen /show myAssembly

Следующая команда выводит все содержащиеся в кэше образы в машинном коде с именем myAssembly и версией 1.0.

ngen /show "myAssembly, version=1.0.0.0"

См. также

Генератор образов в машинном коде (Ngen.exe), традиционный синтаксис

Параметры

Заметки

Примеры

См. также

Ссылки

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

Другие ресурсы

Дополнительные ресурсы