Outil Manifest Generation and Editing (Mage.exe)

  • Article

Mise à jour : novembre 2007

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 de 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 Manifest Generation and Editing, outil du client graphique (MageUI.exe).

Mage.exe et MageUI.exe sont disponibles dans différents emplacements, y compris les emplacements suivants :

  • Kit de développement .NET Framework 2.0 SDK. Le Kit de développement .NET Framework 2.0 SDK est disponible en tant que composant de l'installation Visual Studio 2005 ou peut être téléchargé à partir de Microsoft.

  • Kit de développement logiciel (SDK) Windows pour Windows Vista. Le Kit de développement logiciel (SDK) Windows pour Windows Vista peut être téléchargé à partir du Centre de téléchargement Microsoft.

  • Visual Studio 2008. Les versions ultérieures de Mage.exe et MageUI.exe sont incluses en tant que composant d'installation de Visual Studio 2008.

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.

Commande

Description

-cc, ClearApplicationCache

Efface le cache d'application téléchargé de toutes les applications en ligne uniquement.

-n, -NewTypeFichier [OptionsNew]

Crée un nouveau fichier du type donné. Les types valides sont :

  • Deployment : crée un nouveau manifeste de déploiement.

  • Application : crée un nouveau 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 balises par défaut adéquates.

Utilisez l'option –ToFile (voir le tableau ci-dessous) pour spécifier le nom de fichier et le chemin d'accès 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[CheminFichier] [OptionsUpdate]

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 chemin d'accès et nom de fichier au lieu de remplacer le fichier existant.

-s, -Sign[signOptions]

Utilise un certificat pour signer un fichier. Les signatures sont insérées en tant qu'éléments XML dans les fichiers.

-h, -?, -Help[verbose]

Décrit toutes les commandes disponibles et leurs options. Spécifiez verbose pour obtenir une aide détaillée.

Options des commandes New et Update

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

Options

Valeur par défaut

S'applique à

Description

-appc, -AppCodeBasemanifestReference

Manifestes de déploiement.

Insère une référence d'URL ou de chemin d'accès au fichier manifeste d'application. Ce fichier doit représenter le chemin d'accès complet au manifeste d'application.

-appm, -AppManifestmanifestPath

Manifestes 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, -CertFilefilePath

Tous les types de fichiers.

Spécifie l'emplacement d'un certificat numérique servant à signer un manifeste. Cette option peut être utilisée conjointement avec l'option –Password, si le certificat exige un mot de passe.

-ch, -CertHashhashSignature

Tous 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, -FromDirectorydirectoryPath

Manifestes d'application.

Remplit le manifeste d'application avec les descriptions de tous les assemblys et fichiers trouvés dans directoryPath, directoryPath étant le répertoire qui contient l'application que vous souhaitez 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 Comment : inclure un fichier de données dans une application ClickOnce.

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 l'un des fichiers de votre déploiement est modifié, vous pouvez exécuter Mage.exe avec la commande –Update et l'option –FromDirectory afin qu'il mette à jour les hachages et les versions d'assembly de tous les fichiers référencés.

-FromDirectory inclut tous les fichiers dans 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.

-i, -InstallwillInstall

true

Manifestes 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, cela 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 comme 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 possède la même sémantique que l'argument de l'indicateur -Version.

-n, -NamenameString

deploy

Tous 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.

-pwd, -Passwordpasswd

Tous les types de fichiers.

Mot de passe utilisé pour signer un manifeste avec un certificat numérique. Cette option doit être utilisée en conjonction avec l'option –CertFile.

-p, ProcessorprocessorValue

msil

Manifestes 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 incluent msil, x86, ia64 et amd64. msil correspond à Microsoft Intermediate Language, ce qui signifie que tous vos assemblys sont indépendants de la plateforme et que le Common Language Runtime (CLR) effectue une compilation juste-à-temps de ces assemblys lors de la première exécution de votre application.

-pu,-ProviderUrlurl

Manifestes de déploiement.

Spécifie l'URL vérifiée par ClickOnce pour les mises à jour d'application.

-pub, -PublisherpublisherName

Manifestes d'application.

Manifestes de déploiement.

Nouveauté dans le .NET Framework 3.5

Ajoute le nom de l'éditeur à l'élément de description du manifeste de déploiement ou d'application. En cas d'utilisation sur un manifeste d'application, -UseManifestForTrust doit également être spécifié avec la valeur "true" ou "t" ; dans le cas contraire, ce paramètre lève une erreur.

-ti, -TimestampUriuri

Manifestes 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. Actuellement, seul Verisign prend en charge le service d'horodatage. L'URI fourni comme argument doit être "http://timestamp.verisign.com/scripts/timstamp.dll".

-tr, -TrustLevellevel

Intranet

Manifestes d'application.

Niveau de confiance à accorder à l'application sur les ordinateurs clients. Les valeurs possibles sont "Internet", "Intranet" et "FullTrust".

-t, -ToFilefilePath

  • New :

  • Déploiement : deploy.application

  • Application : application.exe.manifest

  • Update :

  • 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 lorsque vous utilisez –New, la sortie est écrite dans le répertoire de travail actuel. Si –ToFile n'est pas fourni lorsque vous utilisez –Update, Mage.exe réécrit le fichier dans le fichier d'entrée.

-u, -UseManifestForTrustwillUseForTrust

false

Manifestes d'application.

Nouveauté dans le .NET Framework 3.5

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, -VersionversionNumber

1.0.0.0

Manifestes 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 isWPFApp

false

Manifestes d'application.

Manifestes de déploiement.

Nouveauté dans le .NET Framework 3.5

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, parce qu'une application hébergée par le navigateur ne peut pas être une application hors ligne installée.

Options de la commande Sign

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

Options

Description

-cf, -CertFilefilePath

Spé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, -CertHashhashSignature

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.

-p, -Passwordpasswd

Mot de passe utilisé pour signer un manifeste avec un certificat numérique. Cette option doit être utilisée en conjonction avec l'option –CertFile.

-t, -ToFilefilePath

Spécifie le chemin de sortie du fichier créé ou modifié.

Notes

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 employé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.

Lorsque vous utilisez l'option –AppManifest pour remplir un manifeste de déploiement, Mage.exe suppose que votre manifeste d'application résidera dans le même répertoire que le manifeste de déploiement, dans un sous-répertoire nommé d'après la version de déploiement actuelle et configure votre manifeste de déploiement de manière appropriée. Si votre manifeste d'application doit résider 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.

Pour les manifestes de l'application, l'option –TrustLevel 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 vous demande si vous souhaitez 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 MageGUI.exe. Pour plus d'informations sur l'utilisation de MageGUI.exe pour ajouter des sections Trust personnalisées, consultez Manifest Generation and Editing, outil du client graphique (MageUI.exe).

Exemples

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
mage –New TrustLicense

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

mage –New Application –FromDirectory \bin -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 où ClickOnce doit rechercher des mises à jour.

mage –New Application –FromDirectory \bin -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 \bin -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>

Voir aussi

Tâches

Procédure pas à pas : déploiement manuel d'une application ClickOnce

Concepts

Vue d'ensemble du déploiement d'applications approuvées

Référence

Manifest Generation and Editing, outil du client graphique (MageUI.exe)

Invite de commandes du Kit de développement SDK