Herramienta Combinación de ASP.NET (Aspnet_merge.exe)
Actualización: noviembre 2007
La herramienta Combinación de ASP.NET (Aspnet_merge.exe) permite combinar y administrar ensamblados creados por la herramienta Compilación de ASP.NET (Aspnet_compiler.exe). La herramienta Combinación de ASP.NET funciona en los ensamblados creados con ASP.NET versión 2.0 o posteriores.
La herramienta Compilación de ASP.NET se utiliza para precompilar una aplicación para su implementación. La herramienta crea un ensamblado para cada carpeta de contenido del sitio web de destino o crea un ensamblado para cada archivo de contenido. La herramienta Combinación de ASP.NET aporta flexibilidad para la implementación y administración de lanzamientos. Permite hacer lo siguiente:
Crear un ensamblado para todo el sitio web.
Crear un ensamblado para cada carpeta del sitio web y agregar un prefijo al nombre de ensamblado.
Crear un único ensamblado sólo para los elementos de la interfaz de usuario del sitio web, como páginas y controles.
aspnet_merge [-?]
applicationPath
[-keyfile filename [-delaysign]]
[-o assemblyname | -w assemblyname | -prefix prefix]
[-copyattrs [assemblyfile]]
[-debug]
[-nologo]
[-errorstack]
[-r]
[-xmldocs]
[-a]
[-logfile logfile]
[-allowattrs textfile]
Argumentos
Argumento |
Descripción |
|---|---|
applicationPath |
(Necesario) Especifica el nombre de la carpeta que contiene la aplicación para la que desea crear los ensamblados. Ésta es la operación de combinación predeterminada. Crea un número menor de ensamblados que la opción fixednames del compilador. |
Opciones
Opción |
Descripción |
||
|---|---|---|---|
-keyfile filename |
Especifica que se debe aplicar el atributo AssemblyKeyFileAttribute al ensamblado compilado. El atributo especifica el nombre del archivo que contiene el par de claves pública y privada utilizadas para generar un nombre seguro. Si se firman los ensamblados de entrada y la herramienta Combinación no firma los ensamblados, recibirá un mensaje que advierte que se han quitado las claves. Si no se especifica un nombre de archivo de claves y un ensamblado tiene una clave pública y otro ensamblado no, se producirá un error en la herramienta Combinación . |
||
-delaysign |
Especifica que se debe aplicar el atributo AssemblyDelaySignAttribute al ensamblado generado. Este atributo especifica que un ensamblado sólo se debería firmar con el token de clave pública en lugar del par de claves pública/privada. Esta opción debe combinarse con la opción -keyfile. Si el atributo ya se aplica al ensamblado en los archivos de código, la herramienta Combinación produce una excepción. Cuando se utiliza la opción delaysign, si la comprobación del nombre seguro no está habilitada, el código generado por la herramienta Combinación se puede ejecutar antes de que se firme el código. Si no está habilitada la comprobación del nombre seguro, asegúrese de que el código no sea vulnerable a los ataques de usuarios malintencionados antes de que se complete la firma. |
||
-o assemblyname |
Especifica el nombre de un único ensamblado combinado para todo el contenido de la interfaz de usuario web y los ensamblados de nivel superior. Todos los archivos que tienen la extensión .compiled se modifican para que hagan referencia al ensamblado único. (Los archivos con la extensión .compiled se compilan a partir de contenido como .aspx, .master y .ascx.) Esta opción no se puede combinar con las opciones w o prefix. El parámetro assemblyname es necesario. |
||
-w assemblyname |
Especifica el nombre de un único ensamblado combinado para todo el contenido de la interfaz de usuario web (páginas y controles de usuario). Todos los archivos .aspx, .master y .ascx compilados se modifican para que hagan referencia al ensamblado único. Esto permite actualizar los elementos de la interfaz de usuario independientemente de la actualización del código. Los ensamblados de nivel superior para los recursos locales y globales no se combinan. Esta opción no se puede combinar con las opciones o o prefix. El parámetro assemblyname es necesario. |
||
-prefix prefix |
Especifica un prefijo para los nombres de ensamblados. El ensamblado de carpeta raíz sólo tiene el parámetro prefix como nombre del ensamblado. Los ensamblados de subcarpeta tienen el parámetro prefix combinado con el nombre de la subcarpeta. Por ejemplo, si una subcarpeta se denomina Admin, el ensamblado resultante se denominaría prefix.Admin .dll. Para los sitios web que no pueden ser actualizados, la herramienta Compilación compila los temas y recursos locales en ensamblados independientes en la carpeta Bin. Para los sitios web que se pueden actualizar, los temas y los recursos locales no se compilan en ensamblados en la carpeta Bin. En su lugar, se dejan en sus carpetas originales en la aplicación. Además, para los sitios actualizables, la herramienta Combinación modifica los archivos .aspx, .master y .ascx para que señalen al nuevo ensamblado combinado para la carpeta en la que residen los archivos. Esta opción no se puede combinar con las opciones o o w. El parámetro prefix es necesario. |
||
-copyattrs assemblyfile |
Especifica que los ensamblados combinados debe tener asignados los mismos atributos de ensamblado que el ensamblado especificado. Si no se especifica assemblyFile, se utiliza el ensamblado App_Code, aunque el ensamblado de nivel superior App_Code.dll no esté incluido en el resultado combinado. Si hay una incoherencia de atributos entre un ensamblado que se va a combinar y el ensamblado assemblyFile, se produce un error. Utilice la opción a para omitir la comprobación de atributos incoherentes o utilice la opción allowattrs para especificar el atributo que se excluirá de la comprobación. Para los atributos que no están incluidos en la comprobación de coherencia, vea la descripción de la opción allowattrs en la tabla. |
||
-debug |
Especifica que el resultado de la depuración debe conservarse en el ensamblado combinado. |
||
-nologo |
Suprime el mensaje de copyright. |
||
-errorstack |
Especifica que la herramienta debería incluir información del seguimiento de la pila si se produce un error a la hora de compilar la aplicación. |
||
-r |
Quita los archivos .compiled del ensamblado de código principal (código de la carpeta App_Code). No utilice esta opción si su aplicación contiene una referencia de tipo explícito al ensamblado de código principal. |
||
-xmldocs |
Combina los archivos de documentación XML asociados a los ensamblados de entrada. La carpeta Bin del sitio combinado incluye un archivo XML. |
||
-a |
Obliga a la herramienta Combinación a combinar los ensamblados que no tienen aplicados todos los atributos AllowPartiallyTrustedCallersAttribute o que presentan incoherencias de atributos. AllowPartiallyTrustedCallersAttribute permite que los llamadores de confianza parcial tengan acceso a un ensamblado y se especifica durante la compilación realizada por la herramienta Compilación.
|
||
-log logfile |
Escribe mensajes en el archivo especificado. |
||
-allowattrs textfile |
Especifica un archivo que contiene los atributos que se excluirán cuando la herramienta compruebe la coherencia de los atributos en ensamblados combinados. Cada línea del archivo puede ser el nombre completo de un atributo o un espacio de nombres completo. Si se especifica un espacio de nombres, se excluirán todos los atributos encontrados en ese espacio de nombres. Cada atributo o espacio de nombres debe estar en una línea diferente. Algunos atributos no tienen que especificarse explícitamente. La herramienta Combinación genera una advertencia si encuentra los siguientes atributos y, a continuación, sigue procesando. |
||
-? |
Muestra la sintaxis de comandos y opciones para la herramienta. |
.gif "Nota importante")
Nota importante:Comentarios
Las aplicaciones web ASP.NET pueden compilarse en contexto o se pueden precompilar para su implementación en una ubicación de destino, como un servidor de producción. Compilar una aplicación en contexto se denomina compilación dinámica y es útil en escenarios de desarrollo rápido. Precompilar una aplicación para su implementación se puede realizar de una de dos maneras:
Compilar y quitar todos los archivos de código fuente, como archivos de código subyacente y de marcado.
Compilar y mantener los archivos de marcado para que puedan ser actualizados.
La herramienta Combinación de ASP.NET proporciona una flexibilidad mayor al precompilar el sitio web que la que se logra sólo con la herramienta Compilación de ASP.NET.
La herramienta Combinación de ASP.NET combina el resultado de la herramienta Compilación de ASP.NET para generar los ensamblados. Estos ensamblados combinados pueden mejorar administración de lanzamientos y la implementación de sitios web grandes. La herramienta Combinación de ASP.NET se puede utilizar de tres maneras:
Combinar todos los resultados en un único ensamblado.
Combinar el contenido de la interfaz de usuario web (páginas Web, máscaras, etc.) de cada carpeta en su propio ensamblado.
Combinar todo el contenido de la interfaz de usuario web del sitio en un único ensamblado.
En las secciones siguientes se describen los siguientes escenarios. Para obtener ejemplos de cómo utilizar la herramienta Combinación de ASP.NET, vea Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command en el sitio web MSDN.
La herramienta Combinación de ASP.NET está incluida en Visual Studio Web Deployment Projects, un complemento para Visual Studio que permite administrar configuraciones de compilación, especificar tareas previas y posteriores a la compilación, y combinar ensamblados. Para obtener más información, vea Using Web Deployment Projects with Visual Studio 2005.
Grupos de ensamblados
La herramienta Compilación crea ensamblados de manera diferente en función del tipo del archivo de código fuente y de carpeta. El resultado de la herramienta Compilación puede clasificarse en dos grupos de ensamblados. La herramienta Combinación combina los dos grupos de ensamblados de manera diferente.
Los dos grupos de ensamblados son los siguientes:
Ensamblados de contenido de interfaz de usuario web, que se generan a partir de archivos de contenido de interfaz de usuario web como .aspx, .ascx, .master, .ashx, .skin y archivos .resx locales (en la carpeta App_LocalResources). La manera en que se combinan estos ensamblados depende de si el sitio precompilado es actualizable, lo que se determina mediante la opción u de la herramienta Compilación. Si un sitio compilado es actualizable, el contenido de la interfaz de usuario puede actualizarse sin volver a compilar el sitio. Cuando un sitio web es actualizable, los archivos de contenido permanecen en sus carpetas originales y sólo se combinan los archivos de código asociados. Si el sitio no es actualizable, los archivos de contenido .ascx, .master y .skin se quitan de su carpeta original. Los archivos .aspx de ASP.NET se reemplazan con un archivo de marcador que no tiene ningún contenido. En este caso, se combinan el contenido de la interfaz de usuario y el código.
Ensamblados de nivel superior, que son ensamblados generados a partir de carpetas de aplicación como App_Code, App_GlobalResources, App_WebReferences. Los ensamblados de nivel superior también se generan para archivos especiales como Global.asax. Los ensamblados de nivel superior siempre se compilan en la carpeta Bin del sitio de implementación. El sitio de implementación final no tendrá una carpeta App_Code, App_GlobalResources o App_WebReferences ni un archivo Global.asax. En su lugar, el sitio de implementación final tendrá uno o varios ensamblados en el directorio Bin, en función de las opciones utilizadas con la herramienta Combinación. También se compilan siempre las carpetas definidas por el usuario, sólo que el sitio de implementación final mantiene la carpeta definida por el usuario cuando en ella hay archivos de contenido de interfaz de usuario. Para obtener más información acerca de las carpetas reservadas, vea Diseño de sitios Web ASP.NET.
El contenido estático, como los archivos que tienen las extensiones .css, .gif, .htm, .html, .jpg, .js, quedan en sus ubicaciones en la estructura de directorios precompilada. La herramienta Combinación no los mueve ni los modifica.
Escenarios de compilación y combinación
Con ASP.NET 2.0, puede utilizar una combinación de compilación dinámica, precompilación con la herramienta Compilación, y combinación con la herramienta Combinación para adecuarse a sus objetivos de implementación y administración de lanzamientos. En la tabla siguiente se enumeran los diferentes escenarios de compilación y combinación, e indica cuándo se debería utilizar la herramienta Combinación.
Escenario |
Notas |
|---|---|
Compilación dinámica (sin precompilación) |
La compilación dinámica es útil en escenarios de desarrollo rápidos. Visual Studio utiliza la compilación dinámica (cuando presiona F5 o CTRL+F5, solo se compilan dinámicamente la página en la que está trabajando y sus dependencias). Esto evita una compilación del sitio web completo. Para obtener más información, vea Descripción de la compilación dinámica de ASP.NET. |
Precompile para crear un único ensamblado para cada archivo de contenido de interfaz de usuario web utilizando Aspnet_compiler.exe con la opción fixednames. |
Cuando se precompila con la opción fixednames, puede realizar actualizaciones incrementales de unidades tan pequeñas como páginas individuales, e implementar de nuevo sólo las páginas cambiadas. Puede crear sitios precompilados actualizables y no actualizables mediante la opción u con la opción fixednames. La opción fixednames no afecta a la manera en que se combinan los ensamblados posteriormente mediante la herramienta Combinación. Para un sitio grande, el gran número de ensamblados creado por la opción fixednames puede producir problemas de administración de lanzamientos o implementación. Para obtener más información, vea Herramienta de compilación de ASP.NET (Aspnet_compiler.exe). |
Combine para crear un ensamblado para cada carpeta de contenido de interfaz de usuario web utilizando Aspnet_merge.exe con la opción prefix. |
En este escenario, puede controlar los ensamblados en el nivel de carpeta de contenido de interfaz de usuario. Este escenario es como omitir la opción fixenames cuando se utiliza la herramienta Compilación. La diferencia es que la herramienta Combinación permite más control sobre los nombres de los ensamblados finales derivados de la carpeta raíz y de las carpetas de contenido definidas por el usuario. Los ensamblados de nivel superior y el contenido estático no resultan afectados. Una posible desventaja de este escenario es que si cambia un archivo de una carpeta, debe implementar de nuevo el ensamblado de la carpeta y la página modificada. Puede combinar sitios precompilados actualizables y no actualizables mediante la opción prefix. Este escenario es el predeterminado si ejecuta la herramienta Combinación sin opciones. |
Combine para crear un único ensamblado para todos los archivos de contenido de interfaz de usuario web utilizando Aspnet_merge.exe con la opción w. |
En este escenario, todo el contenido de la interfaz de usuario se combina en un ensamblado que tiene el nombre especificado en el parámetro assemblyname. Esto reduce el número total de ensamblados en el sitio final implementado. Sin embargo, también requiere que implementa de nuevo el ensamblado de contenido de interfaz de usuario en caso de que cambie un archivo de contenido. Los ensamblados de nivel superior y el contenido estático no resultan afectados. |
Combine para crear un único ensamblado para todo el sitio web utilizando Aspnet_merge.exe con la opción o. |
En este escenario, el sitio final implementado contiene sólo un ensamblado que tiene el nombre especificado en el parámetro assemblyname. Un ensamblado único simplifica la implementación del sitio. Sin embargo, significa que si cambia cualquier contenido del sitio, debe volver a crear e implementar el ensamblado del sitio. Los ensamblados de nivel superior (App_Code, App_GlobalResources y App_WebReferences) resultan afectados porque están incluidos en el ensamblado único. El contenido estático no resulta afectado. |
Combinar una aplicación para su implementación
Para combinar los ensamblados de un sitio web, ejecute la herramienta Combinación y especifique la ubicación del sitio precompilado con el parámetro applicationPath. La herramienta Combinación de ASP.NET combina un sitio precompilado en contexto. En otras palabras, no crea una nueva copia combinada del sitio precompilado. El parámetro applicationPath puede ser la ubicación final de la aplicación web. Asimismo, se puede volver a implementar la aplicación de compilación, por ejemplo, copiando el directorio.
Cuando la herramienta Combinación combina un sitio precompilado, conserva la ubicación de los archivos dinámicos cuando aparecen en el paso precompilado. El único cambio que la herramienta Combinación realiza al contenido de los archivos dinámicos es cambiar las directivas @ Page, @ Control y @ Master. Garantiza que los archivos que tienen estas directivas heredan del ensamblado combinado correcto en la carpeta Bin. Para obtener detalles sobre cómo trata la herramienta Compilación los tipos de archivo, consulte la sección "Notas" de Herramienta de compilación de ASP.NET (Aspnet_compiler.exe)
Para los ensamblados que derivan de las carpetas definidas por el usuario (incluida la carpeta del sitio raíz), algunas opciones de combinación pueden crear nombres que difieren de los que aparecen en el sitio precompilado. Por ejemplo, la tabla siguiente muestra los nombres del ensamblado combinado cuando no se utiliza ninguna opción con la herramienta Combinación. El nombre de ensamblado para cada carpeta definida por el usuario es App_Web_nnnn.dll, donde nnnn es un valor hash generado de forma interna.
Carpeta del sitio precompilado |
Nombre del ensamblado combinado sin utilizar ninguna opción de Aspnet_merge.exe |
|---|---|
\ |
Root.dll |
Admin |
Admin.dll |
La tabla siguiente muestra los nombres del ensamblado combinado cuando se utiliza la opción prefix y el parámetro NewName.
Carpeta del sitio precompilado |
Nombre del ensamblado combinado utilizando la opción prefix de Aspnet_merge.exe |
|---|---|
\ |
Nuevo nombre.dll |
Admin |
Nuevo nombre.Admin.dll |
Los temas se tratan de manera diferente en un sitio combinado que no es actualizable. En el sitio precompilado no combinado, hay un ensamblado independiente para cada tema. Cada ensamblado recibe el nombre App_Theme_Nombre del tema.dll. En el sitio combinado, hay un ensamblado denominado Theme.dll. Si el sitio precompilado es actualizable, no hay ningún ensamblado basado en temas en la carpeta Bin combinada.
Solucionar problemas del proceso de combinación
Mientras se está compilando o combinando un sitio web, la ruta de acceso de un ensamblado podría resultar mayor que la longitud máxima permitida para una ruta de acceso de archivo de Microsoft Windows. En ese caso, cuando se solicita un recurso del ensamblado combinado, se produce un error HttpException que indica que el recurso no se precompiló y no se puede solicitar.
La longitud máxima de la ruta de acceso a archivos de Microsoft Windows es 260 caracteres. Si la ruta de acceso de un ensamblado supera este límite, debe acortar la ruta de acceso del sitio web o de sus subcarpetas. También podría tener que deshabilitar las copias sombra del archivo Web.config mediante la propiedad ShadowCopyBinAssemblies del elemento hostingEnvironment. Para obtener más información acerca de los nombres de archivos, vea Naming a File en el sitio web MSDN.
Cuando se utiliza la herramienta Combinación con la opción o para crear un único ensamblado para el sitio, se producirá un error si el proceso de combinación crea referencias circulares. Hay dos soluciones posibles para esta situación:
Utilice en su lugar la opción w para que el archivo de código fuente que contiene la referencia circular se mantenga como referencia externa y no se combine.
Separe los controles implicados en una referencia circular en directorios diferentes.
Cuando se combinan ensamblados que tienen atributos incoherentes, utilice las instrucciones siguientes para asegurarse de que la operación de combinación sea correcta:
Haga una lista de los atributos incoherentes mediante la opción allowattrs.
Utilice las opciones copyattrs y asegúrese de que coinciden los atributos de todos los ensamblados que se van a combinar.
Utilice la opción a.
Firmar ensamblados
Las opciones keyfile y delaysign permiten utilizar la herramienta Combinación para crear ensamblados con nombre seguro sin utilizar la herramienta Nombre seguro (Sn.exe). Las opciones delaysign corresponden al atributo AssemblyDelaySignAttribute y la opción keyfile corresponde al atributo AssemblyKeyFileAttribute.
Cada opción aplica el atributo correspondiente al ensamblado combinado. El atributo que se va a aplicar se marca con un atributo AttributeUsageAttribute cuya propiedad AllowMultiple es false. Por consiguiente, si utiliza estas opciones al combinar ensamblados que ya están marcados con uno de los atributos, no se realizará la combinación.
Ejemplos
El comando siguiente combina los ensamblados del sitio precompilado en el directorio C:\PrecompiledSite.
Aspnet_merge C:\PrecompiledSite
El comando siguiente combina los ensamblados de un sitio precompilado en el directorio C:\PrecompiledSite y firma los ensamblados combinados mediante el archivo KeyFile.snk. El sitio combinado tendrá un ensamblado para cada carpeta del sitio precompilado.
Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk
El comando siguiente combina todos los ensamblados del sitio precompilado en el directorio C:\PrecompiledSite en un único ensamblado y asigna el nombre MyApp.dll al ensamblado resultante. El sitio combinado tendrá un ensamblado para todo el contenido de interfaz de usuario del sitio web.
Aspnet_merge C:\PrecompiledSite -w MyApp.dll
El comando siguiente combina todos los ensamblados del sitio precompilado en el directorio C:\PrecompiledSite en un único ensamblado y asigna el nombre MyApp.dll al ensamblado resultante.
Aspnet_merge C:\PrecompiledSite -o MyApp.dll
Vea también
Conceptos
Retrasar la firma de un ensamblado
Referencia
AllowPartiallyTrustedCallersAttribute
Herramientas de .NET Framework