Sintaxis heredada del generador de imágenes nativas (Ngen.exe)

Artículo
08/10/2011

La información de este tema se proporciona para los usuarios de las versiones 1.0 y 1.1 de .NET Framework. Para obtener información sobre la sintaxis de la versión 2.0, vea Ngen.exe (Generador de imágenes nativas).

Esta herramienta crea una imagen nativa a partir de un ensamblado administrado y la instala en la caché de imágenes nativas del equipo local. La caché de imágenes nativas es un área reservada de la caché global de ensamblados. Una vez creada una imagen nativa de un ensamblado, el motor en tiempo de ejecución utiliza automáticamente la imagen nativa cada vez que se ejecuta el ensamblado. No es necesario realizar ningún procedimiento adicional para que el motor en tiempo de ejecución utilice una imagen nativa. Al ejecutar la herramienta Ngen.exe, el ensamblado se carga y se ejecuta con mayor rapidez, ya que restaura las estructuras de datos y código en la caché de imágenes nativas, en lugar de generarlas dinámicamente.

ngen [options] [assemblyName |assemblyPath ]

Parámetros

Argumento	Descripción
assemblyName	Nombre del ensamblado para el que se genera una imagen nativa. El ensamblado debe estar ubicado en el directorio actual. Puede proporcionar un nombre de ensamblado parcialmente especificado, como myAssembly, o un nombre de ensamblado completo, como myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Si desea que Ngen.exe encuentre y utilice el archivo de directivas del editor de un ensamblado, debe utilizar un nombre de ensamblado completo.
assemblyPath	Ruta de acceso explícita al ensamblado para el que se genera la imagen nativa. Puede especificar una ruta de acceso completa a un ensamblado como c:\applications\myApp\myApp.exe, una ruta de acceso relativa como .. \applications\myApp\myApp.exe o un nombre de archivo, como myApp.exe. Si especifica un nombre de archivo como myApp.exe sin una ruta de acceso completa o relativa, el ensamblado debe estar ubicado en el directorio actual. Para permitir que Ngen.exe identifique un ensamblado como archivo ejecutable y encuentre su archivo de configuración, debe utilizar el argumento assemblyPath a fin de especificar los ensamblados con una extensión .exe. Si especifica más de un ensamblado en la línea de comandos, sólo uno de ellos puede ser un archivo ejecutable. Esta herramienta aplica las propiedades de enlace del archivo ejecutable (base de la aplicación y archivos de configuración) al resto de los ensamblados especificados.

assemblyName

Nombre del ensamblado para el que se genera una imagen nativa. El ensamblado debe estar ubicado en el directorio actual. Puede proporcionar un nombre de ensamblado parcialmente especificado, como myAssembly, o un nombre de ensamblado completo, como myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Si desea que Ngen.exe encuentre y utilice el archivo de directivas del editor de un ensamblado, debe utilizar un nombre de ensamblado completo.

assemblyPath

Ruta de acceso explícita al ensamblado para el que se genera la imagen nativa. Puede especificar una ruta de acceso completa a un ensamblado como c:\applications\myApp\myApp.exe, una ruta de acceso relativa como .. \applications\myApp\myApp.exe o un nombre de archivo, como myApp.exe.

Si especifica un nombre de archivo como myApp.exe sin una ruta de acceso completa o relativa, el ensamblado debe estar ubicado en el directorio actual.

Para permitir que Ngen.exe identifique un ensamblado como archivo ejecutable y encuentre su archivo de configuración, debe utilizar el argumento assemblyPath a fin de especificar los ensamblados con una extensión .exe.

Si especifica más de un ensamblado en la línea de comandos, sólo uno de ellos puede ser un archivo ejecutable. Esta herramienta aplica las propiedades de enlace del archivo ejecutable (base de la aplicación y archivos de configuración) al resto de los ensamblados especificados.

Opción	Descripción
/debug	Genera la imagen nativa que utiliza el depurador en el modo de depuración normal.
/debugopt	Genera la imagen nativa que utiliza el depurador en el modo de depuración optimizado de Common Language Runtime. Vea la documentación específica del depurador para obtener más información sobre cómo activar este modo.
/delete [nombreDeEnsamblado \| assemblyPath \| *]	Elimina las imágenes nativas de la caché de imágenes para el argumento assemblyName o assemblyPath especificado. Si especifica el parámetro '', la herramienta elimina todas las imágenes nativas de la caché de imágenes nativas. Si no especifica un parámetro con la opción /delete, la herramienta muestra un mensaje de error. A la hora de desinstalar una versión de .NET Framework, el proceso de desinstalación utiliza la opción /delete* para quitar todas las imágenes nativas de la versión de .NET Framework que se va a desinstalar. Entre estas imágenes nativas se encuentran las imágenes nativas creadas para ensamblados de .NET Framework en el momento de la instalación, así como las imágenes nativas creadas por el usuario para ensamblados personalizados. Si especifica la opción /delete * con la opción /show, la herramienta muestra una lista de las imágenes nativas que elimina. Si hay varias versiones de .NET Framework instaladas en el mismo equipo a la vez, para eliminar una imagen nativa debe utilizar la misma versión de Ngen.exe que utilizó para crear dicha imagen. Nota Esta opción sólo afecta a las imágenes nativas generadas con Ngen.exe.No afecta a los ensamblados reales.
/help	Muestra la sintaxis de comandos y opciones para la herramienta.
/nologo	Suprime la presentación de la portada de inicio de Microsoft.
/prof	Genera la imagen nativa que utiliza un generador de perfiles que requiera código instrumentado. Vea la documentación del generador de perfiles para determinar si requiere código instrumentado.
/show	Muestra los archivos existentes en la caché de imágenes nativas para el argumento assemblyName o assemblyPath especificado. Si no se especifica un argumento, la herramienta muestra todo el contenido de la caché de imágenes nativas. Esta opción muestra la información de definición del ensamblado de origen y las opciones especiales de configuración de código para cada imagen nativa. Si se especifica esta opción con la opción /delete *, la herramienta muestra una lista de las imágenes nativas que elimina.
/showversion	Muestra la versión del motor en tiempo de ejecución que Ngen.exe utilizará para generar una imagen nativa del ensamblado especificado. Si hay varias versiones de .NET Framework instaladas en el mismo equipo a la vez, utilice esta opción para determinar la versión que utilizará la herramienta. Para obtener más información sobre la forma de ejecutar varias versiones del motor en tiempo de ejecución, vea Ejecución en paralelo. Nota Esta opción no genera ninguna imagen nativa.
/silent	Suprime la presentación de mensajes de operaciones correctas.
/?	Muestra la sintaxis de comandos y opciones para la herramienta.

Comentarios

Ngen.exe no utiliza las reglas estándar de búsqueda de ensamblados para encontrar los ensamblados que el usuario especifica en la línea de comandos. Ngen.exe sólo busca los ensamblados especificados por el usuario en el directorio actual. Por lo tanto, para permitir que Ngen.exe localice los ensamblados, el usuario debe establecer como directorio de trabajo aquel que contiene los ensamblados de los que desea crear imágenes nativas o bien especificar las rutas de acceso exactas a los ensamblados.

Una imagen nativa es un archivo que contiene código máquina compilado específico del procesador. Tenga en cuenta que la imagen nativa generada por Ngen.exe no se puede compartir a través de dominios de aplicación. Por eso, Ngen.exe no puede utilizarse en los escenarios de aplicaciones que requieren el uso compartido de los ensamblados entre los dominios de aplicación.

Los ensamblados precompilados con Ngen.exe pueden mejorar el tiempo de inicio de las aplicaciones, porque la mayor parte del trabajo requerido para ejecutar código ya se ha hecho previamente. Por tanto, es más apropiado utilizar Ngen.exe para las aplicaciones cliente en las que se ha determinado que los ciclos de la CPU consumidos por la compilación Just-In-Time (JIT) provoquen un rendimiento más lento.

Nota
Para ejecutar Ngen.exe, es necesario disponer de privilegios administrativos.

Dado que hay muchos factores que afectan al tiempo de inicio de una aplicación, debería determinar cuidadosamente qué aplicaciones se beneficiarían del uso de Ngen.exe. Experimente ejecutando una versión compilada JIT y una versión precompilada de un ensamblado candidato en el entorno en el que se utilizará. Esto permitirá comparar los tiempos de inicio de un ensamblado ejecutado con diferentes esquemas de compilación.

Una vez generada la imagen nativa de un ensamblado, el motor en tiempo de ejecución intenta localizar y utilizar automáticamente la imagen nativa cada vez que se ejecuta el ensamblado. Por ejemplo, si ejecuta un ensamblado en un escenario de depuración o en un escenario de creación de perfiles, el motor en tiempo de ejecución busca la imagen nativa generada con las opciones /debug, /debugopt o /prof. Si no puede encontrar una imagen nativa coincidente, el motor en tiempo de ejecución volverá a la compilación JIT estándar.

Si se ejecuta Ngen.exe en un ensamblado que contenga un atributo de código depurable, en función de los marcadores del atributo, la herramienta automáticamente genera código como si se hubiesen especificado las opciones /debug o /debugopt.

Si Ngen.exe encuentra algún método en un ensamblado que no puede generar, excluye el método de la imagen nativa. Una vez que el motor de ejecución ejecuta este ensamblado, volverá a la compilación Just-In-Time para los métodos que no se han incluido en la imagen nativa.

Cuando se utiliza Ngen.exe para crear una imagen nativa de un ensamblado, los resultados dependen de las opciones especificadas en la línea de comandos y de determinadas opciones de configuración del equipo. Entre estas opciones de configuración, se incluyen las siguientes:

Versión de .NET Framework
Tipo de CPU
Versión del sistema operativo
Identidad exacta del ensamblado (identidad de nueva compilación de cambios)
Identidad exacta de todos los ensamblados a los que hace referencia el ensamblado (identidad de nueva compilación de cambios).
Factores de seguridad.

Ngen.exe guarda esta información cuando genera una imagen nativa. Al ejecutar un ensamblado, el motor en tiempo de ejecución busca la imagen nativa generada con las opciones y los valores de configuración que coinciden con el entorno actual del equipo. El motor en tiempo de ejecución vuelve a la compilación Just-In-Time (JIT) de un ensamblado, si no encuentra una imagen nativa coincidente. Si se realizan los siguientes cambios en la configuración y el entorno de un equipo, las imágenes nativas dejarán de ser válidas:

Versión de .NET Framework

Si se aplica una actualización a .NET Framework, todas las imágenes nativas que se hayan creado manualmente mediante Ngen.exe dejarán de ser válidas. Estos ensamblados seguirán ejecutándose, pero el motor en tiempo de ejecución no cargará la imagen nativa correspondiente del ensamblado. Debe crear nuevas imágenes nativas de estos ensamblados de forma manual.

.NET Framework crea nuevas imágenes nativas de forma automática para las bibliotecas de .NET Framework que instala.
Tipo de CPU

Si actualiza el procesador de un equipo a una nueva familia de procesadores, todas las imágenes nativas almacenadas en la caché de imágenes nativas dejan de ser válidas.
Versión del sistema operativo

Si modifica la versión del sistema operativo que se está ejecutando en un equipo, todas las imágenes nativas almacenadas en la caché de imágenes nativas dejan de ser válidas.
Identidad exacta del ensamblado.

Si vuelve a compilar un ensamblado, la imagen nativa correspondiente al ensamblado deja de ser válida.
Identidad exacta de todos los ensamblados a los que hace referencia el ensamblado.

Si vuelve a compilar cualquiera de los ensamblados a los que hace referencia un ensamblado, la imagen nativa correspondiente al ensamblado deja de ser válida.

Factores de seguridad.

Al modificar la directiva de seguridad del equipo para restringir los permisos previamente concedidos a un ensamblado puede ocurrir que la imagen nativa compilada con anterioridad para dicho ensamblado deje de ser válida. La anulación de cualquiera de los siguientes permisos en concreto hace que la imagen nativa actual de un ensamblado deje de ser válida:

Permiso de herencia declarativo solicitado por una clase de la que se deriva el ensamblado.
Permiso en tiempo de vínculo declarativo solicitado por un método al que el ensamblado llama.
Permiso SkipVerification, si el ensamblado contiene métodos no comprobables. Para obtener más información sobre este permiso, vea SecurityPermissionAttribute.SkipVerification (Propiedad).
Permiso UnmanagedCode, si el ensamblado realiza llamadas PInvoke. Para obtener más información sobre este permiso, vea SecurityPermissionAttribute.UnmanagedCode (Propiedad).

Si ejecuta Ngen.exe en un ensamblado que tenga desactivada la seguridad de acceso a código, la imagen nativa que genere dejará de ser válida cuando se active la seguridad de acceso a código. Tenga en cuenta que la seguridad de acceso a código está activada de forma predeterminada.

Para obtener información detallada sobre la forma en que Common Language Runtime administra la seguridad de acceso del código y sobre la forma de utilizar los permisos, vea Seguridad de acceso del código

Nota
La versión 1.0 de Common Language Runtime no presenta las opciones de creación o eliminación automática de imágenes nativas que dejan de ser válidas.Todas las imágenes nativas se deben crear y eliminar manualmente utilizando la herramienta Ngen.exe.

Si utiliza Ngen.exe para generar imágenes nativas de una aplicación en el momento de la instalación, debe especificar el nombre de archivo de la aplicación y los nombres de ensamblado completos de los archivos .dll a los que la aplicación hacía referencia en el momento en que se compiló. El hecho de proporcionar nombres de ensamblado completos de los archivos DLL a los que hace referencia una aplicación, permite que Ngen.exe tenga acceso a los archivos de directivas del editor de los ensamblados a los que se hace referencia. En el futuro, si se actualizan los archivos DLL y se utiliza la directiva del editor para el redireccionamiento de versiones, Ngen.exe aplicará la directiva del editor.

Para obtener los nombres de ensamblado completos que se deben utilizar, ejecute Ildasm.exe en una aplicación y vea el manifiesto del ensamblado. El manifiesto muestra el nombre del ensamblado, la versión, la referencia cultural y el símbolo (token) de clave pública de los archivos DLL a los que la aplicación hacía referencia en el momento en que se compiló. Por ejemplo, si desea crear una imagen nativa de una aplicación denominada ClientApp.exe que se compiló con myLibrary.dll, version 1.0.0.0, culture=neutral y PublicKeyToken=0038abc9deabfle5, utilice el comando ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".

Tenga en cuenta que el ejemplo anterior no generará imágenes nativas de los ensamblados a los que hace referencia myLibrary.dll. Para determinar los nombres totalmente especificados de los ensamblados a los que myLibrary.dll hace referencia, ejecute Ildasm.exe en myLibrary.dll. Por ejemplo, si ejecuta Ildasm.exe en myLibrary.dll y determina que hace referencia a myMath.dll, versión 1.0.0.0, referencia cultural de todos los idiomas y PublicKeyToken=0039def8abcbste7, utilice el siguiente comando a fin de generar imágenes nativas para el árbol completo de referencias de ensamblado de 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".

Para obtener más información sobre este formato, vea la sección de ejemplos más adelante en este mismo tema.

El proceso de desinstalación para una aplicación debe utilizar /delete [nombreDeEnsamblado| assemblyPath] opción para quitar las imágenes nativas que se crearon en el momento que se instaló la aplicación. Para especificar la imagen nativa en particular que desea eliminar, debe utilizar el parámetro assemblyName o assemblyPath. Si se especifica la opción /delete * se quitan todas las imágenes nativas de la caché de imágenes nativas; si se especifica la opción /delete sin parámetros se produce un error.

Ejemplos

El siguiente comando genera una imagen nativa para ClientApp.exe, que se encuentra en el directorio actual. Si existe un archivo de configuración para la aplicación, Ngen.exe lo utilizará. La herramienta no generará imágenes nativas para los archivos DLL a los que hace referencia ClientApp.exe.

ngen ClientApp.exe

Si ClientApp.exe hace referencia directa a dos archivos DLL (myLibOne.dll y myLibTwo.dll), debe suministrar a Ngen.exe los nombres de ensamblado completos para estos archivos DLL a fin de generar imágenes nativas para ellos. Ejecute Ildasm.exe en ClientApp.exe para determinar los nombres de ensamblado completos de los archivos DLL a los que se hace referencia. En el ejemplo, los nombres completos de los ensamblados especificados de myLibOne.dll y myLibTwo.dll son "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" y "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Utilizando esta información, el siguiente comando genera imágenes nativas para ClientApp.exe, myLibOne.dll y myLibTwo.dll. Si existe un archivo de configuración para ClientApp.exe, Ngen.exe lo utilizará. Si existe un archivo de directivas del editor para myLibOne.dll o myLibTwo.dll, Ngen.exe lo utilizará.

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

En el ejemplo anterior, los archivos DLL myLibOne.dll y myLibTwo.dll podrían hacer referencia a otros ensamblados. Para determinar los nombres completos de los ensamblados a los que se hace referencia, ejecute Ildasm.exe en myLibOne.dll y myLibTwo.dll. Para este ejemplo, suponga que myLibOne.dll no hace referencia a ningún otro ensamblado y que myLibTwo.dll hace referencia a "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7". Utilizando esta información, el siguiente comando genera imágenes nativas para todo el árbol de referencias de ensamblado de la aplicación.

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"

El siguiente comando genera una imagen nativa para myAssembly.exe con la ruta de acceso especificada.

ngen c:\myfiles\myAssembly.exe

El siguiente comando genera una imagen nativa para myLibrary.dll, con la ruta especificada.

ngen c:\myfiles\myLibrary.dll

Ngen.exe busca en la caché de imágenes nativas un ensamblado especificado con un nombre de ensamblado parcial para eliminarlo. El comando siguiente elimina todas las imágenes nativas con el nombre myAssembly.

ngen /delete myAssembly

El siguiente comando elimina la imagen nativa myAssembly con el nombre completo de ensamblado especificado.

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

El siguiente comando muestra todas las imágenes nativas que contiene la caché de imágenes nativas.

ngen /show

El siguiente comando muestra todas las imágenes nativas que contiene la caché de imágenes nativas con el nombre myAssembly.

ngen /show myAssembly

El siguiente comando muestra todas las imágenes nativas incluidas en la caché de imágenes nativas con el nombre myAssembly y la versión 1.0.

ngen /show "myAssembly, version=1.0.0.0"

Vea también

Sintaxis heredada del generador de imágenes nativas (Ngen.exe)

Parámetros

Comentarios

Ejemplos

Vea también

Referencia

Conceptos

Otros recursos

Recursos adicionales