Mage.exe (Herramienta de generación y edición de manifiestos)
La Herramienta de generación y edición de manifiestos (Mage.exe) es una herramienta de línea de comandos que permite crear y editar manifiestos de aplicación y de implementación. Como herramienta de línea de comandos, Mage.exe se puede ejecutar desde scripts por lotes y desde otras aplicaciones basadas en Windows, incluidas las aplicaciones de ASP.NET.
También puede utilizar MageUI.exe, una aplicación gráfica, en lugar de Mage.exe. Para obtener más información, vea MageUI.exe (Herramienta de generación y edición de manifiestos, cliente gráfico).
- Se incluyen dos versiones de Mage.exe y MageUI.exe como un componente del programa de instalación de Visual Studio 2010. Para ver información de la versión, ejecute MageUI.exe, seleccione Ayuda y seleccione Acerca de. En esta documentación se describe la versión 4.0.x.x de Mage.exe y MageUI.exe.
Mage [commands] [commandOptions]
Parámetros
La tabla siguiente muestra los comandos admitidos por Mage.exe. Para obtener más información sobre las opciones admitidas por estos comandos, vea Opciones de los comandos New y Update y Opciones del comando Sign.
Comando |
Descripción |
|---|---|
-cc, ClearApplicationCache |
Borra la caché de aplicaciones descargada de todas las aplicaciones que sólo están disponibles en línea. |
-n, -New tipo de archivo [opciones de New] |
Crea un nuevo archivo del tipo especificado. Los tipos válidos son:
Si no especifica parámetros adicionales con este comando, se creará un archivo del tipo adecuado con etiquetas y valores de atributo predeterminados adecuados. Utilice la opción -ToFile (vea la tabla siguiente) para especificar el nombre de archivo y ruta de acceso del nuevo archivo. Utilice la opción -FromDirectory (ver tabla siguiente) para crear un manifiesto de aplicación con todos los ensamblados de una aplicación agregados a la sección <dependency> del manifiesto. |
-u, -Update [ruta de acceso de archivo] [opciones de Update] |
Realiza uno o más cambios en un archivo de manifiesto. No tiene que especificar el tipo de archivo que está editando. Mage.exe examinará el archivo utilizando un conjunto de técnicas heurísticas para determinar si es un manifiesto de implementación o un manifiesto de aplicación. Si ya ha firmado un archivo con un certificado, -Update quitará el bloque de firma clave. Esto se debe a que la firma clave contiene un hash del archivo, y al modificar el archivo se invalida el hash. Utilice la opción -ToFile (vea la tabla siguiente) para especificar un nuevo nombre de archivo y ruta de acceso en lugar de sobrescribir el archivo existente. |
-s, -Sign [signOptions] |
Usa un par de claves o un certificado X509 para firmar un archivo. Las firmas se insertan como elementos XML dentro de los archivos. Debe estar conectado a Internet al firmar un manifiesto que especifica un valor -TimestampUri. |
-h, -?, -Help[detallado] |
Describe todos los comandos disponibles y sus opciones. Especifique verbose para obtener ayuda detallada. |
Opciones de los comandos New y Update
La tabla siguiente muestra las opciones admitidas por los comandos -New y -Update.
Opciones |
Valor predeterminado |
Se aplica a |
Descripción |
|---|---|---|---|
-appc, -AppCodeBase manifestReference |
Manifiestos de implementación. |
Inserta una dirección URL o una referencia a la ruta de acceso del archivo en el archivo de manifiesto de aplicación. Este valor debe ser la ruta de acceso completa al manifiesto de aplicación. |
|
-appm, -AppManifest manifestPath |
Manifiestos de implementación. |
Inserta una referencia al manifiesto de aplicación de una implementación en su manifiesto de implementación. El archivo indicado por manifestPath debe existir, o Mage.exe emitirá un error. Si el archivo al que se hace referencia mediante manifestPath no es un manifiesto de aplicación, Mage.exe emitirá un error. |
|
-cf, -CertFile filePath |
Todos los tipos de archivo. |
Especifica la ubicación de un certificado digital X509 para firmar un manifiesto. Esta opción se puede utilizar junto con la opción -Password, si el certificado requiere una contraseña. |
|
-ch, -CertHash hashSignature |
Todos los tipos de archivo. |
El hash de un certificado digital guardado en el almacén de certificados personales del equipo cliente. Corresponde a la cadena de la huella digital de un certificado digital descrito en la consola de Certificados de Windows. hashSignature puede ir en mayúsculas o minúsculas y puede proporcionarse como cadena única, o bien, separando cada octeto de la huella digital mediante espacios y entrecomillando toda la huella digital. |
|
-fd, -FromDirectory directoryPath |
Manifiestos de aplicación. |
Rellena el manifiesto de aplicación con las descripciones de todos los ensamblados y archivos que se encuentran en directoryPath y todos sus subdirectorios, donde directoryPath es el directorio que contiene la aplicación que desea implementar. Para cada archivo en el directorio, Mage.exe decide si el archivo es un ensamblado o un archivo estático. Si es un ensamblado, agrega una etiqueta <dependency> y un atributo installFrom a la aplicación con el nombre del ensamblado, base del código y versión. Si es un archivo estático, agrega una etiqueta <file>. Mage.exe también utiliza un sencillo conjunto heurístico para detectar el principal archivo ejecutable de la aplicación, y lo marcará como punto de entrada de la aplicación ClickOnce en el manifiesto. Mage.exe nunca marcará automáticamente un archivo como de "datos". Esto debe hacerlo manualmente. Para obtener más información, vea Cómo: Incluir un archivo de datos en una aplicación ClickOnce. Mage.exe también genera un hash para cada archivo basado en su tamaño. ClickOnce utiliza estos hash para garantizar que nadie haya manipulado los archivos de implementación desde que se creó el manifiesto. Si se modifica alguno de los archivos de implementación, puede ejecutar Mage.exe con el comando -Update y la opción -FromDirectory, para actualizar los hash y las versiones del ensamblado de todos los archivos a los que se hace referencia. -FromDirectory incluirá todos los archivos en todos los subdirectorios situados dentro de directoryPath. Si utiliza -FromDirectory con el comando -Update, Mage.exe quitará los archivos del manifiesto de aplicación que ya no existen en el directorio. |
|
-if, -IconFile filePath |
Manifiestos de aplicación. |
Especifica la ruta de acceso completa a un archivo de iconos .ICO. Este icono aparece junto al nombre de la aplicación en el menú Inicio y en su entrada Agregar o quitar programas. Si no se proporciona ningún icono, se usará el icono predeterminado. |
|
-ip, -IncludeProviderURL url |
true |
Manifiestos de implementación. |
Indica si el manifiesto de implementación incluye el valor de ubicación de actualización establecido por -ProviderURL. |
-i, -Install willInstall |
true |
Manifiestos de implementación. |
Indica si la aplicación ClickOnce debe instalarse en el equipo local o si debe ejecutarse desde el web. Instalar una aplicación hace presente dicha aplicación en el menú Inicio de Windows. Los valores válidos son "true" o "t", y "false" o "f". Si especifica la opción -MinVersion y un usuario tiene instalada una versión anterior a -MinVersion, se ejecutará la instalación de la aplicación independientemente del valor que se pase a -Install. Esta opción no se puede combinar con la opción -BrowserHosted. Intentar especificar ambos para el mismo manifiesto provocará un error. |
-mv, -MinVersion [version] |
Versión indicada en el manifiesto de implementación ClickOnce tal y como especifica el marcador -Version. |
Manifiestos de implementación. |
Versión mínima de esta aplicación que un usuario puede ejecutar. Este marcador hace que la versión con nombre de su aplicación sea una actualización necesaria. Si lanza una versión del producto con un cambio importante o un error crítico de seguridad, puede utilizar este marcador para especificar que se debe instalar esta actualización y que el usuario no puede continuar ejecutando las versiones anteriores. version tiene la misma semántica que el argumento del marcador -Version. |
-n, -Name nameString |
Implementar |
Todos los tipos de archivo. |
Nombre utilizado para identificar la aplicación. ClickOnce utilizará este nombre para identificar la aplicación en el menú Inicio (si la aplicación se ha configurado para instalarse automáticamente) y los cuadros de diálogo Permisos y Elevación. .gif "Nota") Nota
Si va a actualizar un manifiesto existente y no especifica el nombre de publicador con esta opción, Mage.exe actualiza el manifiesto con el nombre de la organización definido en el equipo.Para usar un nombre distinto, asegúrese de utilizar esta opción y especificar el nombre de publicador deseado.
|
-pwd, -Password passwd |
Todos los tipos de archivo. |
Contraseña utilizada para firmar un manifiesto con un certificado digital. Se debe utilizar conjuntamente con la opción -CertFile. |
|
-p, Processor processorValue |
Msil |
Manifiestos de aplicación. Manifiestos de implementación. |
Arquitectura de microprocesador donde se ejecutará esta distribución. Se requiere este valor si está preparando una o varias instalaciones cuyos ensamblados se han precompilado para un microprocesador concreto. Los valores válidos incluyen msil, x86, ia64 y amd64. msil es el lenguaje intermedio de Microsoft, lo que significa que todos los ensamblados son independientes de la plataforma y Common Language Runtime los compilará just-in-time cuando la aplicación se ejecute por primera vez. |
-pu, -ProviderURL url |
Manifiestos de implementación. |
Especifica la dirección URL que ClickOnce examinará para buscar actualizaciones de la aplicación. |
|
-pub, -Publisher publisherName |
Manifiestos de aplicación. Manifiestos de implementación. |
Agrega el nombre del editor al elemento de descripción del manifiesto de implementación o de aplicación. Cuando se utiliza en un manifiesto de aplicación, también se debe especificar -UseManifestForTrust con un valor de "true" o "t"; de lo contrario, este parámetro producirá un error. |
|
-s, -SupportURL url |
Manifiestos de aplicación. Manifiestos de implementación. |
Especifica el vínculo que aparece en Agregar o quitar programas para la aplicación ClickOnce. |
|
-ti, -TimestampUri uri |
Manifiestos de aplicación. Manifiestos de implementación. |
La dirección URL de un servicio de marca de tiempo digital. Marcar el tiempo en los manifiestos evita tener que volver a firmar los manifiestos en caso de que su certificado digital expire antes de implementar la versión siguiente de su aplicación. Para obtener más información, vea Windows root certificate program members. |
|
-t, -ToFile filePath |
|
Todos los tipos de archivo. |
Especifica la ruta de acceso de salida del archivo que se ha creado o modificado. Si no se proporciona -ToFile al utilizar -New, el resultado se escribe en el directorio de trabajo actual. Si no se proporciona -ToFile al utilizar -Update, Mage.exe volverá a escribir el archivo en el archivo de entrada. |
-tr, -TrustLevel level |
Intranet |
Manifiestos de aplicación. |
Nivel de confianza que se concederá a la aplicación en los equipos cliente. Los valores incluyen "Internet", "Intranet" y "FullTrust." |
-um, -UseManifestForTrust willUseForTrust |
False |
Manifiestos de aplicación. |
Especifica si se utilizará la firma digital del manifiesto de aplicación para tomar decisiones de confianza cuando la aplicación se ejecute en el cliente. Especificar "true" o "t" indica que el manifiesto de aplicación se utilizará para las decisiones de confianza. Si se especifica "false" o "f", se utilizará la firma del manifiesto de implementación. |
-v, -Version versionNumber |
1.0.0.0 |
Manifiestos de aplicación. Manifiestos de implementación. |
Versión de la implementación. El argumento debe ser una cadena de la versión válida con el formato "N.N.N.N", donde "N" es un entero de 32 bits sin signo. |
-wpf, -WPFBrowserApp isWPFApp |
false |
Manifiestos de aplicación. Manifiestos de implementación. |
Utilice este marcador sólo para aplicaciones de Windows Presentation Foundation (WPF) que se hospedarán dentro de Internet Explorer, y no para aplicaciones ejecutables independientes. Los valores válidos son "true" o "t", y "false" o "f". Para los manifiestos de aplicación, inserta el atributo hostInBrowser en el elemento entryPoint del manifiesto de aplicación. Para los manifiestos de implementación, establece el atributo install del elemento deployment en false y guarda el manifiesto de implementación con una extensión .xbap. Al especificar este argumento junto con el argumento -Install se produce un error, porque una aplicación hospedada por el explorador no puede ser una aplicación sin conexión instalada. |
Opciones del comando Sign
En la siguiente tabla se muestran las opciones admitidas por el comando -Sign, que se aplica a todos los tipos de archivos.
Opciones |
Descripción |
|---|---|
-cf, -CertFile filePath |
Especifica la ubicación de un certificado digital para firmar un manifiesto. Esta opción se puede utilizar junto con la opción -Password. |
-ch, -CertHash hashSignature |
El hash de un certificado digital guardado en el almacén de certificados personales del equipo cliente. Corresponde a la propiedad de la huella digital de un certificado digital descrito en la consola de Certificados de Windows. hashSignature puede ir en mayúsculas o minúsculas y puede proporcionarse como cadena única, o bien, separando cada octeto de la huella digital mediante espacios y entrecomillando toda la huella digital. |
-pwd, -Password passwd |
Contraseña utilizada para firmar un manifiesto con un certificado digital. Se debe utilizar conjuntamente con la opción -CertFile. |
-t, -ToFile filePath |
Especifica la ruta de acceso de salida del archivo que se ha creado o modificado. |
Comentarios
Todos los argumentos a Mage.exe no distinguen entre mayúsculas y minúsculas. Los comandos y opciones se pueden prefijar con un guión (-) o una barra diagonal (/).
Todos los argumentos utilizados con el -Sign comando también se pueden utilizar en cualquier momento con los comandos -New o -Update. Los siguientes comandos son equivalentes.
mage -Sign c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx
La tarea de firmar es la última que debe realizar, ya que un documento firmado utiliza un hash del archivo para comprobar que la firma es válida para el documento. Si realiza cambios en un archivo firmado, debe firmarlo de nuevo. Si firma un documento que estuvo previamente firmado, Mage.exe reemplazará la firma anterior con la nueva.
Cuando utiliza la opción -AppManifest para rellenar un manifiesto de implementación, Mage.exe supondrá que su manifiesto de aplicación reside en el mismo directorio que el manifiesto de implementación dentro de un subdirectorio con el mismo nombre que la versión actual de la implementación, y configurará su manifiesto de implementación adecuadamente. Si su manifiesto de aplicación reside en otro lugar, utilice la opción -AppCodeBase para establecer la ubicación alternativa.
Debe firmar su manifiesto de implementación y de aplicación antes de implementar su aplicación. Para obtener instrucciones sobre cómo firmar los manifiestos, vea Información general sobre la implementación de aplicaciones de confianza.
La opción -TrustLevel de los manifiestos de aplicación describe el conjunto de permisos que una aplicación exige para ejecutarse en el equipo cliente. De manera predeterminada, se asigna a las aplicaciones un nivel de confianza basado en la zona donde reside su dirección URL. Las aplicaciones implementadas en una red corporativa se colocan generalmente en la zona de Intranet, mientras que las que se implementan en Internet se colocan en la zona de Internet. Ambas zonas de seguridad imponen restricciones en el acceso de la aplicación a los recursos locales, siendo la zona de Intranet ligeramente más permisiva que la zona de Internet. La zona FullTrust da a las aplicaciones acceso completo a los recursos locales de un equipo. Si utiliza la opción -TrustLevel para colocar una aplicación en esta zona, el componente del administrador de confianza (Trust Manager) de CLR pedirá al usuario que decida si desea otorgar este mayor nivel de confianza. Si está implementando su aplicación en una red corporativa, puede utilizar la implementación de aplicaciones de confianza para aumentar el nivel de confianza de la aplicación sin solicitar información al usuario.
Los manifiestos de aplicación también admiten las secciones de confianza personalizadas. Esto facilita que la aplicación obedezca al principio de seguridad de solicitar un permiso mínimo, ya que se puede configurar el manifiesto para que exija sólo los permisos específicos para ejecutar la aplicación. Mage.exe no permite agregar directamente una sección de confianza personalizada. Puede agregar una utilizando un editor de texto, un analizador XML o la herramienta gráfica MageUI.exe. Para obtener más información sobre cómo utilizar MageUI.exe para agregar secciones de confianza personalizadas, vea MageUI.exe (Herramienta de generación y edición de manifiestos, cliente gráfico).
Los nuevos manifiestos que se crean con la versión 4 de Mage.exe, que va incluida en Visual Studio 2010, tiene .NET Framework 4 Client Profile como destino. Para usar versiones de destino anteriores de .NET Framework, debe usar una versión anterior de Mage.exe. Cuando se agregan o quitan ensamblados de un manifiesto existente, o cuando se vuelve a firmar una manifiesto existente, Mage.exe no actualiza el manifiesto para destinarlo a .NET Framework 4 Client Profile. En las siguientes tablas se muestran estas características y restricciones.
Versión del manifiesto |
Operación |
Mage 2.0 |
Mage 4.0 |
|---|---|---|---|
Manifiesto para aplicaciones que tienen como destino la versión 2.0 ó 3.x de .NET Framework |
Abra . |
OK |
OK |
Cerrar |
OK |
OK |
|
Guardar |
OK |
OK |
|
Volver a firmar |
OK |
OK |
|
Nuevo |
OK |
No compatible |
|
Actualización (ver abajo) |
OK |
OK |
|
Manifiesto para aplicaciones que tienen como destino la versión 4 de .NET Framework |
Abra . |
OK |
OK |
Cerrar |
OK |
OK |
|
Guardar |
OK |
OK |
|
Volver a firmar |
OK |
OK |
|
Nuevo |
No compatible |
OK |
|
Actualización (ver abajo) |
No compatible |
OK |
Versión del manifiesto |
Detalles de la operación de actualización |
Mage 2.0 |
Mage 4.0 |
|---|---|---|---|
Manifiesto para aplicaciones que tienen como destino la versión 2.0 ó 3.x de .NET Framework |
Modificar un ensamblado |
OK |
OK |
Agregar un ensamblado |
OK |
OK |
|
Quitar un ensamblado |
OK |
OK |
|
Manifiesto para aplicaciones que tienen como destino la versión 4 de .NET Framework |
Modificar un ensamblado |
No compatible |
OK |
Agregar un ensamblado |
No compatible |
OK |
|
Quitar un ensamblado |
No compatible |
OK |
Mage.exe crea nuevos manifiestos que tienen .NET Framework 4 Client Profile como destino. Las aplicaciones ClickOnce que tienen como destino .NET Framework 4 Client Profile se pueden ejecutar en .NET Framework 4 Client Profile y en la versión completa de .NET Framework 4. Si la aplicación tiene como destino la versión completa de .NET Framework 4 y no se puede ejecutar en .NET Framework 4 Client Profile, quite el elemento <framework> de cliente mediante un editor de texto y vuelva a firmar el manifiesto. Lo siguiente es un elemento <framework> de ejemplo destinado a .NET Framework 4 Client Profile.
<framework targetVersion="4.0" profile="client" supportedRuntime="4.0.20506" />
Ejemplos
En el siguiente ejemplo se abre la interfaz de usuario para Mage (MageUI.exe).
mage
Los ejemplos siguientes crean un manifiesto de implementación y un manifiesto de aplicación predeterminados. Estos archivos se crean todos ellos en el directorio de trabajo actual y se denominan deploy.application y application.exe.manifest, respectivamente.
mage -New Deployment
mage -New Application
En el siguiente ejemplo se crea un manifiesto de aplicación con todos los ensamblados y archivos de recursos del directorio actual.
mage -New Application -FromDirectory . -Version 1.0.0.0
En el ejemplo siguiente se continúa el ejemplo anterior especificando el nombre de implementación y el microprocesador de destino. También especifica la dirección URL donde ClickOnce debe comprobar las actualizaciones.
mage -New Application -FromDirectory . -Name "Hello, World! Application" -Version 1.0.0.0 -Processor "x86" -ProviderUrl http://internalserver/HelloWorld/
En el ejemplo siguiente se muestra cómo crear un par de manifiestos para implementar una aplicación de WPF que se hospedará en Internet Explorer.
mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp true
mage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true
En el siguiente ejemplo se actualiza un manifiesto de implementación con información de un manifiesto de aplicación y se establece la base del código para la ubicación del manifiesto de aplicación.
mage -Update HelloWorld.deploy -AppManifest 1.0.0.0\application.manifest -AppCodeBase http://internalserver/HelloWorld.deploy
En el siguiente ejemplo se edita el manifiesto de implementación para forzar una actualización de la versión instalada del usuario.
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -MinVersion 1.1.0.0
En el ejemplo siguiente se indica al manifiesto de implementación que recupere el manifiesto de aplicación de otro directorio.
mage -Update HelloWorld.deploy -AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/
En el ejemplo siguiente se firma un manifiesto de implementación existente utilizando un certificado digital en el directorio de trabajo actual.
mage -Sign deploy.application -CertFile cert.pfx -Password <passwd>
Vea también
Tareas
Tutorial: Implementar manualmente una aplicación ClickOnce
Referencia
MageUI.exe (Herramienta de generación y edición de manifiestos, cliente gráfico)
Símbolos del sistema del SDK de Windows y Visual Studio
Conceptos
Seguridad e implementación ClickOnce
Información general sobre la implementación de aplicaciones de confianza