Mage.exe (outil Manifest Generation and Editing)

 

Date de publication : novembre 2016

L'outil Manifest Generation and Editing (Mage.exe) est un outil de ligne de commande qui prend en charge la création et la modification de manifestes de déploiement et d'application. En tant qu'outil en ligne de commande, Mage.exe peut être exécuté à partir de scripts de commandes et d'autres applications Windows, notamment les applications ASP.NET.

Vous pouvez également utiliser MageUI.exe, une application graphique, à la place de Mage.exe. Pour plus d'informations, consultez MageUI.exe (Manifest Generation and Editing Tool, Graphical Client).

Cet outil est installé automatiquement avec Visual Studio. Pour exécuter l'outil, utilisez l'invite de commandes développeur (ou l'invite de commandes Visual Studio dans Windows 7). Pour plus d'informations, consultez Invites de commandes.

Deux versions ultérieures de Mage.exe et MageUI.exe sont incluses en tant que composant d'installation de Visual Studio 2010. Pour afficher les informations de version, exécutez MageUI.exe et sélectionnez Aide / ?, puis À propos de. Cette documentation décrit la version 4.0.x.x de Mage.exe et MageUI.exe.

À l'invite de commandes, tapez le texte suivant :

Mage [commands] [commandOptions]  

Paramètres

Le tableau ci-dessous répertorie les commandes prises en charge par Mage.exe. Pour plus d'informations sur les options prises en charge par ces commandes, consultez Options des commandes New et Update et Options de la commande Sign.

CommandeDescription
-cc, ClearApplicationCacheEfface le cache d'application téléchargé de toutes les applications en ligne uniquement.
-n, -New fileType [newOptions]Crée un nouveau fichier du type donné. Les types valides sont :

- Deployment : crée un manifeste de déploiement.
- Application : crée un manifeste de l'application.

Si vous ne spécifiez pas de paramètres supplémentaires avec cette commande, elle crée un fichier du type approprié, avec les valeurs d’attributs et étiquettes par défaut adéquates.

Utilisez l’option -ToFile (voir le tableau ci-dessous) pour spécifier le nom de fichier et le chemin du nouveau fichier.

Utilisez l’option -FromDirectory (voir le tableau ci-dessous) pour créer un manifeste de l’application avec tous les assemblys d’une application ajoutés à la section <dependency> du manifeste.
-u, -Update [filePath] [updateOptions]Apporte une ou plusieurs modifications à un fichier manifeste. Vous n'avez pas à spécifier le type de fichier que vous modifiez. Mage.exe examinera le fichier en utilisant un jeu de paramètres heuristiques et déterminera s'il s'agit d'un manifeste de déploiement ou d'un manifeste d'application.

Si vous avez déjà signé un fichier avec un certificat, -Update supprime le bloc de signature de clé. En effet, la signature de clé contient un hachage du fichier, et la modification du fichier rend le hachage non valide.

Utilisez l’option -ToFile (voir le tableau ci-dessous) pour spécifier un nouveau nom et chemin de fichier au lieu de remplacer le fichier existant.
-s, -Sign [signOptions]Utilise une paire de clés ou un certificat X509 pour signer un fichier. Les signatures sont insérées en tant qu'éléments XML dans les fichiers.

Vous devez être connecté à Internet lors de la signature d’un manifeste qui spécifie une valeur -TimestampUri.
-h, -?, -Help [verbose]Décrit toutes les commandes disponibles et leurs options. Spécifiez verbose pour obtenir une aide détaillée.

Le tableau suivant affiche les options prises en charge par les commandes -New et -Update.

OptionsValeur par défautS'applique àDescription
-a, -Algorithmsha1RSAManifestes d'application.

Manifestes de déploiement.
Définit l'algorithme avec lequel générer des compactés de dépendance. La valeur doit être "sha256RSA" ou "sha1RSA".

N'utilisez pas avec l'option "-Update". Cette option est ignorée avec l'utilisation de l'option "-Sign".
-appc, -AppCodeBase manifestReferenceManifestes de déploiement.Insère une référence d'URL ou de chemin d'accès au fichier manifeste d'application. Cette valeur doit représenter le chemin d’accès complet au manifeste d’application.
-appm, -AppManifest manifestPathManifestes de déploiement.Insère une référence au manifeste d'application d'un déploiement dans son manifeste de déploiement.

Le fichier indiqué par manifestPath doit exister, sans quoi Mage.exe génère une erreur. Si le fichier référencé par manifestPath n'est pas un manifeste d'application, Mage.exe génère une erreur.
-cf, -CertFile filePathTous les types de fichiers.Spécifie l'emplacement d'un certificat numérique X509 pour la signature d'un manifeste. Cette option peut être utilisée conjointement avec l’option -Password si le certificat demande un mot de passe.
-ch, -CertHash hashSignatureTous les types de fichiers.Hachage d'un certificat numérique stocké dans le magasin de certificats personnel de l'ordinateur client. Il correspond à la chaîne d'empreinte numérique d'un certificat numérique affiché dans la console Certificats Windows.

 hashSignature peut être en majuscules ou en minuscules et fourni en tant que chaîne unique ou avec chaque octet de l'empreinte numérique séparé par des espaces et l'empreinte numérique complète entre guillemets.
-fd, -FromDirectory directoryPathManifestes d'application.Remplit le manifeste d'application avec les descriptions de tous les assemblys et fichiers trouvés dans directoryPath, y compris tous les sous-répertoires, directoryPath étant le répertoire qui contient l'application à déployer. Pour chaque fichier du répertoire, Mage.exe détermine s'il s'agit d'un assembly ou d'un fichier statique. Si c'est un assembly, il ajoute une balise <dependency> et un attribut installFrom à l'application avec le nom de l'assembly, la base de code et la version. S'il s'agit d'un fichier statique, il ajoute une balise <file>. Mage.exe utilise également un ensemble de paramètres heuristiques simple pour détecter le fichier exécutable principal de l'application et le marque comme point d'entrée de l'application ClickOnce dans le manifeste.

Mage.exe ne marquera jamais automatiquement un fichier en tant que fichier de « données ». Vous devez faire cela manuellement. Pour plus d'informations, consultez How to: Include a Data File in a ClickOnce Application.

Mage.exe génère également un hachage pour chaque fichier en fonction de sa taille. ClickOnce utilise ces hachages pour éviter toute falsification des fichiers du déploiement après la création du manifeste. Si un des fichiers de votre déploiement change, vous pouvez exécuter Mage.exe avec la commande -Update et l’option -FromDirectory, qui met à jour les hachages et les versions des assemblys de tous les fichiers référencés.

 -FromDirectory inclut tous les fichiers de tous les sous-répertoires trouvés dans directoryPath.

Si vous utilisez -FromDirectory avec la commande -Update, Mage.exe supprime tous les fichiers du manifeste d’application qui n’existent plus dans le répertoire.
-if, -IconFile  filePathManifestes d'application.Spécifie le chemin d'accès complet à un fichier icône .ICO. Cette icône s'affiche à côté du nom de votre application dans le menu Démarrage et dans son entrée Ajout/Suppression de programmes. Si aucune icône n'est fournie, une icône par défaut est utilisée.
-ip, -IncludeProviderURL  urltrueManifestes de déploiement.Indique si le manifeste du déploiement inclut la valeur de l’emplacement de la mise à jour définie par -ProviderURL.
-i, -Install willInstalltrueManifestes de déploiement.Indique si l'application ClickOnce doit être installée ou non sur l'ordinateur local ou si elle doit s'exécuter à partir du Web. Lorsqu'une application est installée, elle figure dans le menu Démarrer de Windows. Les valeurs valides sont "true" ou "t", et "false" ou "f".

Si vous spécifiez l’option -MinVersion et qu’un utilisateur dispose d’une version antérieure à la version -MinVersion installée, ceci force l’installation de l’application, indépendamment de la valeur passée à -Install.

Cette option ne peut pas être utilisée avec l’option -BrowserHosted. Toute tentative de spécifier ces deux options pour le même manifeste générera une erreur.
-mv, -MinVersion  [version]Version répertoriée dans le manifeste de déploiement ClickOnce telle que spécifiée par l’indicateur -Version.Manifestes de déploiement.Version minimale de cette application qu'un utilisateur peut exécuter. Cet indicateur rend obligatoire la mise à jour avec la version nommée de votre application. Si vous publiez une version de votre produit avec une mise à jour corrigeant une rupture ou une vulnérabilité de sécurité critique, vous pouvez utiliser cet indicateur pour spécifier que cette mise à jour doit être installée et que l’utilisateur ne peut pas continuer à exécuter des versions antérieures.

 version a la même sémantique que l’argument pour l’indicateur -Version.
-n, -Name nameStringDéployerTous les types de fichiers.Nom utilisé pour identifier l'application. ClickOnce utilise ce nom pour identifier l'application dans le menu Démarrer (si l'application est configurée pour s'installer) et dans les boîtes de dialogue Permission Elevation. Note: Si vous mettez à jour un manifeste existant et que vous ne spécifiez pas de nom de serveur de publication avec cette option, Mage.exe met à jour le manifeste avec le nom de l'organisation défini sur l'ordinateur. Pour utiliser un nom différent, veillez à utiliser cette option et spécifiez le nom voulu pour l'éditeur.
-pwd, -Password passwdTous les types de fichiers.Mot de passe utilisé pour signer un manifeste avec un certificat numérique. Cette option doit être utilisée conjointement avec l’option -CertFile.
-p, Processor processorValueMsilManifestes d'application.

Manifestes de déploiement.
Architecture de microprocesseur sur laquelle cette distribution s'exécutera. Cette valeur est obligatoire si vous préparez une ou plusieurs installations dont les assemblys ont été précompilés pour un microprocesseur spécifique. Les valeurs valides sont msil, x86, ia64 et amd64.msil est le langage intermédiaire Microsoft, ce qui signifie que tous vos assemblys sont indépendants des plateformes et que le Common Language Runtime (CLR) les compile juste-à-temps quand votre application est exécutée pour la première fois.
-pu, -ProviderURL urlManifestes de déploiement.Spécifie l'URL vérifiée par ClickOnce pour les mises à jour d'application.
-pub, -Publisher publisherNameManifestes d'application.

Manifestes de déploiement.
Ajoute le nom de l'éditeur à l'élément de description du manifeste de déploiement ou d'application. Quand il est utilisé sur un manifeste d’application, -UseManifestForTrust doit également être spécifié avec la valeur « true » ou « t » ; sinon, ce paramètre génère une erreur.
-s, -SupportURL  urlManifestes d'application.

Manifestes de déploiement.
Spécifie le lien dans lequel s'affiche Ajout/Suppression de programmes pour l'application ClickOnce.
-ti, -TimestampUri uriManifestes d'application.

Manifestes de déploiement.
L'URL d'un service d'horodatage numérique. Horodater les manifestes vous évite d'avoir à signer de nouveau les manifestes si votre certificat numérique expire avant le déploiement de la version suivante de votre application. Pour plus d’informations, consultez Configurer des racines de confiance et des certificats non autorisés.
-t, -ToFile filePath- Nouveau :
- Déploiement : deploy.application
- Application : application.exe.manifest
- Mise à jour :
- Fichier d'entrée.
Tous les types de fichiers.Spécifie le chemin de sortie du fichier créé ou modifié.

Si -ToFile n’est pas fourni quand vous utilisez -New, la sortie est écrite dans le répertoire de travail actuel. Si -ToFile n’est pas fourni quand vous utilisez -Update, Mage.exe réécrit le fichier dans le fichier d’entrée.
-tr, -TrustLevel levelSelon la zone dans laquelle réside l'URL de l'application.Manifestes d'application.Niveau de confiance à accorder à l'application sur les ordinateurs clients. Les valeurs possibles sont "Internet", "Intranet" et "FullTrust".
-um, -UseManifestForTrust willUseForTrustFalseManifestes d'application.Spécifie si la signature numérique du manifeste d'application sera utilisée pour prendre des décisions d'approbation lorsque l'application s'exécute sur le client. Spécifier "true" ou "t" indique que le manifeste d'application sera utilisé pour les décisions d'approbation. Spécifier "false" ou "f" indique que la signature du manifeste de déploiement sera utilisée.
-v, -Version versionNumber1.0.0.0Manifestes d'application.

Manifestes de déploiement.
Version du déploiement. L’argument doit être une chaîne de version valide au format « N.N.N.N », où « N » est un entier 32 bits non signé.
-wpf, -WPFBrowserApp  isWPFAppfalseManifestes d'application.

Manifestes de déploiement.
Utilisez cet indicateur uniquement si l'application est une application Windows Presentation Foundation (WPF) qui sera hébergée dans Internet Explorer et n'est pas un exécutable autonome. Les valeurs valides sont "true" ou "t", et "false" ou "f".

Pour les manifestes d'application, insère l'attribut hostInBrowser sous l'élément entryPoint du manifeste d'application.

Pour les manifestes de déploiement, affecte la valeur false à l'attribut install sur l'élément deployment et enregistre le manifeste de déploiement avec une extension .xbap. La spécification de cet argument avec l’argument -Install génère une erreur car une application hébergée par le navigateur ne peut pas être une application hors ligne installée.

Le tableau suivant affiche les options prises en charge par la commande -Sign applicables à tous les types de fichiers.

OptionsDescription
-cf, -CertFile filePathSpécifie l'emplacement d'un certificat numérique servant à signer un manifeste. Cette option peut être utilisée en conjonction avec l’option -Password.
-ch, -CertHash hashSignatureHachage d'un certificat numérique stocké dans le magasin de certificats personnel de l'ordinateur client. Il correspond à la propriété d'empreinte numérique d'un certificat numérique affiché dans la console Certificats Windows.

 hashSignature peut être en majuscules ou en minuscules et fourni en tant que chaîne unique ou avec chaque octet de l'empreinte numérique séparé par des espaces et l'empreinte numérique complète entre guillemets.
-pwd, -Password passwdMot de passe utilisé pour signer un manifeste avec un certificat numérique. Cette option doit être utilisée conjointement avec l’option -CertFile.
-t, -ToFile filePathSpécifie le chemin de sortie du fichier créé ou modifié.

Tous les arguments passés à Mage.exe ne respectent pas la casse. Les commandes et options peuvent être précédées d'un tiret (-) ou d'une barre oblique (/).

Tous les arguments utilisés avec la commande -Sign peuvent être toujours utilisés avec les commandes -New ou -Update. Les commandes suivantes sont équivalentes.

mage -Sign c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx  
mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -CertFile cert.pfx  

La signature est la dernière tâche à effectuer, car un document signé utilise un hachage du fichier afin de vérifier la validité de la signature pour le document. Si vous modifiez d'une quelconque façon un fichier signé, vous devez le signer de nouveau. Si vous signez un document déjà signé, Mage.exe remplace la signature précédente par la nouvelle.

Quand vous utilisez l’option -AppManifest pour remplir un manifeste de déploiement, Mage.exe suppose que votre manifeste d’application va se trouver dans le même répertoire que le manifeste de déploiement, dans un sous-répertoire nommé d’après la version du déploiement actuel et il configure votre manifeste de déploiement de façon appropriée. Si votre manifeste d’application doit se trouver ailleurs, utilisez l’option -AppCodeBase pour définir l’autre emplacement.

Vos manifestes de déploiement et de l'application doivent être signés avant de déployer votre application. Pour obtenir des instructions sur la signature des manifestes, consultez Vue d'ensemble du déploiement d'applications approuvées.

L’option -TrustLevel pour les manifestes d’application décrit le jeu d’autorisations dont une application a besoin pour s’exécuter sur l’ordinateur client. Par défaut, un niveau de confiance basé sur la zone dans laquelle leur URL réside est assigné aux applications. Les applications déployées sur un réseau d'entreprise sont généralement placées dans la zone Intranet tandis que celles déployées sur Internet sont placées dans la zone Internet. Les deux zones de sécurité placent des restrictions sur l'accès de l'application aux ressources locales, la zone Intranet étant un peu moins stricte que la zone Internet. La zone FullTrust donne aux applications l'accès complet aux ressources locales d'un ordinateur. Si vous utilisez l’option -TrustLevel pour placer une application dans cette zone, le composant Gestionnaire de confiance du CLR demande à l’utilisateur s’il veut accorder ce niveau de confiance plus élevé. Si vous déployez votre application sur un réseau d'entreprise, vous pouvez utiliser le déploiement d'applications approuvées pour élever le niveau de confiance de l'application sans affichage d'une invite utilisateur.

Les manifestes d'application prennent également en charge des sections Trust personnalisées. Cela permet à votre application de respecter le principe de sécurité qui consiste à accorder des autorisations minimales. Vous pouvez ainsi configurer le manifeste pour demander uniquement les autorisations nécessaires à l'exécution de l'application. Mage.exe ne prend pas en charge directement l'ajout d'une section Trust personnalisée. Vous pouvez en ajouter une à l'aide d'un éditeur de texte, d'un analyseur XML ou de l'outil graphique MageUI.exe. Pour plus d’informations sur l’utilisation de MageUI.exe pour ajouter des sections Trust personnalisées, consultez MageUI.exe (Manifest Generation and Editing Tool, Graphical Client).

Les nouveaux manifestes créés avec la version 4 de Mage.exe, incluse avec Visual Studio 2010, ciblent le .NET Framework 4 Client Profile. Pour cibler des versions antérieures du .NET Framework, vous devez utiliser une version antérieure de Mage.exe. Lors de l'ajout ou de la suppression d'assemblys dans un manifeste existant, ou lors de la nouvelle signature d'un manifeste existant, Mage.exe ne met pas à jour le manifeste pour cibler .NET Framework 4 Client Profile. Les tableaux suivants contiennent ces fonctionnalités et restrictions.

Version du manifesteOpérationMage v2.0Mage v4.0
Manifeste pour les applications qui ciblent la version 2.0 ou 3.x du .NET FrameworkOuvrirOKOK
FermerOKOK
EnregistrerOKOK
Nouvelle signatureOKOK
NouveauOKNon pris en charge
Mise à jour (voir ci-dessous)OKOK
Manifeste pour les applications qui ciblent la version 4 du .NET FrameworkOuvrirOKOK
FermerOKOK
EnregistrerOKOK
Nouvelle signatureOKOK
NouveauNon pris en chargeOK
Mise à jour (voir ci-dessous)Non pris en chargeOK
Version du manifesteDétails de l'opération de mise à jourMage v2.0Mage v4.0
Manifeste pour les applications qui ciblent la version 2.0 ou 3.x du .NET FrameworkModifier un assemblyOKOK
Ajouter un assemblyOKOK
Supprimer un assemblyOKOK
Manifeste pour les applications qui ciblent la version 4 du .NET FrameworkModifier un assemblyNon pris en chargeOK
Ajouter un assemblyNon pris en chargeOK
Supprimer un assemblyNon pris en chargeOK

Mage.exe crée des nouveaux manifestes qui ciblent le .NET Framework 4 Client Profile. Les applications ClickOnce qui ciblent le .NET Framework 4 Client Profile peuvent s'exécuter à la fois sur le .NET Framework 4 Client Profile et sur la version complète du .NET Framework 4. Si votre application vise la version complète du .NET Framework 4 et ne peut pas fonctionner sur le .NET Framework 4 Client Profile, supprimez l'élément client <framework> à l'aide d'un éditeur de texte et signez de nouveau le manifeste. Voici un exemple d'élément <framework> qui cible le .NET Framework 4 Client Profile.

<framework targetVersion="4.0" profile="client" supportedRuntime="4.0.20506" />  

L'exemple suivant ouvre l'interface utilisateur de Mage (MageUI.exe).

mage  

Les exemples suivants créent un manifeste de déploiement et un manifeste d'application par défaut. Ces fichiers sont tous créés dans le répertoire de travail en cours et ils sont nommés respectivement deploy.application et application.exe.manifest.

mage -New Deployment  
mage -New Application  

L’exemple suivant crée un manifeste d’application rempli avec tous les assemblys et fichiers de ressources du répertoire de l’application actuelle .

mage -New Application -FromDirectory . -Version 1.0.0.0  

L'exemple suivant prend la suite de l'exemple précédent en spécifiant le nom du déploiement et le microprocesseur cible. Il spécifie également une URL en fonction de laquelle ClickOnce doit rechercher des mises à jour.

mage -New Application -FromDirectory . -Name "Hello, World! Application" -Version 1.0.0.0 -Processor "x86" -ProviderUrl http://internalserver/HelloWorld/  

L'exemple suivant montre comment créer une paire de manifestes pour déployer une application WPF qui sera hébergée dans 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  

L'exemple suivant met à jour un manifeste de déploiement avec les informations d'un manifeste d'application et définit la base de code pour l'emplacement du manifeste d'application.

mage -Update HelloWorld.deploy -AppManifest 1.0.0.0\application.manifest -AppCodeBase http://internalserver/HelloWorld.deploy  

L'exemple suivant modifie le manifeste de déploiement pour forcer une mise à jour de la version installée de l'utilisateur.

mage -Update c:\HelloWorldDeployment\HelloWorld.deploy -MinVersion 1.1.0.0  

L'exemple suivant indique au manifeste de déploiement de récupérer le manifeste d'application d'un autre répertoire.

mage -Update HelloWorld.deploy -AppCodeBase http://anotherserver/HelloWorld/1.1.0.0/  

L'exemple suivant signe un manifeste de déploiement existant à l'aide d'un certificat numérique dans le répertoire de travail actif.

mage -Sign deploy.application -CertFile cert.pfx -Password <passwd>  

ClickOnce Security and Deployment
Walkthrough: Manually Deploying a ClickOnce Application
Vue d'ensemble du déploiement d'applications approuvées
MageUI.exe (Manifest Generation and Editing Tool, Graphical Client)
Invites de commandes

Afficher: