Outil Manifest Generation and Editing (Mage.exe)
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, un client graphique, au lieu de Mage.exe. Pour plus d'informations, consultez Outil Manifest Generation and Editing, client graphique (MageUI.exe).
Mage [commands] [commandOptions]
Paramètres
| Commande | Description |
|---|---|
-cc, ClearApplicationCache |
Efface 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 :
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 –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 ne devez pas spécifier le type de fichier que vous modifiez ; Mage.exe examine le fichier à l'aide d'un ensemble de paramètres heuristiques et détermine s'il s'agit d'un manifeste de déploiement ou de l'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. |
-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 |
Décrit toutes les commandes disponibles et leurs options. |
-v, -Verbose |
Fournit des informations plus détaillées sur une opération lors de l'exécution. |
Le tableau suivant affiche les options prises en charge par les commandes –New et –Update.
| Options | Description |
|---|---|
-appc, -AppCodeBase manifestReference |
(Manifestes de déploiement uniquement) 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, -AppManifest manifestPath |
(Manifestes de déploiement uniquement) 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 filePath |
(Tous les types de fichier) Spécifie l'emplacement d'un certificat numérique destiné à signer un manifeste. Cette option peut être utilisée conjointement avec l'option –Password, si le certificat exige un mot de passe. |
-ch, -CertHash hashSignature |
(Tous les types de fichier) 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 fournie 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 entourée de part et d'autre par des guillemets. |
-fd, -FromDirectory directoryPath |
(Manifestes d'application uniquement) 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 Mage.exe ne marque jamais automatiquement un fichier comme un fichier de « données » ; vous devez le faire 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, -Install willInstall |
(Manifestes de déploiement uniquement) Indique si l'application ClickOnce doit être installée sur l'ordinateur local ou 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 elle n'est pas spécifiée, la valeur par défaut est "true". 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. |
-mv, -MinVersion [version] |
(Manifestes de déploiement uniquement) 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. Si aucune version n'est spécifiée, Mage.exe utilise la version répertoriée dans le manifeste de déploiement ClickOnce, telle qu'elle est spécifiée par l'indicateur -Version. version possède la même sémantique que l'argument de l'indicateur -Version. |
-n, -Name nameString |
(Tous les types de fichier) 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. Si aucun nom n'est spécifié, la valeur par défaut est "deploy". |
-pwd, -Password passwd |
(Tous les types de fichier) 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, Processor processorValue |
(Manifestes de déploiement et d'application uniquement) Architecture du microprocesseur sur laquelle cette distribution doit s'exécuter. 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. La valeur par défaut est msil (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, -ProviderUrl url |
(Manifestes de déploiement uniquement) Spécifie l'URL vérifiée par ClickOnce pour les mises à jour d'application. |
-tr, -TrustLevel level |
(Manifestes d'application uniquement) Niveau de confiance à accorder à l'application sur les ordinateurs clients. Les valeurs possibles sont "Internet", "Intranet" et "FullTrust". Lors de la création d'un nouveau manifeste d'application, la valeur par défaut est "Intranet". |
-tf, -ToFile filePath |
(Tous les types de fichier) Spécifie le chemin de sortie du fichier créé ou modifié. Si –ToFile n'est pas fourni lors de l'utilisation de –New, la sortie est écrite dans le répertoire de travail actif avec un nom de fichier par défaut dont le nom exact dépend du type de fichier que vous créez :
Si –ToFile n'est pas fourni lors de l'utilisation de –Update, Mage.exe réécrit le fichier dans le fichier d'entrée. |
-v, -Version versionNumber |
(Manifestes de déploiement et d'application uniquement) 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é. La valeur par défaut est "1.0.0.0". |
Le tableau suivant affiche les options prises en charge par la commande –Sign applicables à tous les types de fichiers.
| Options | Description |
|---|---|
-cf, -CertFile filePath |
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, -CertHash hashSignature |
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 entourée de part et d'autre par des guillemets. |
-p, -Password passwd |
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, -ToFile filePath |
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 Common Language Runtime 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 directement en charge 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 Outil Manifest Generation and Editing, client graphique (MageUI.exe).
Exemples
L'exemple suivant ouvre l'interface utilisateur de Mage (MageUI.Exe).
mage
Les exemples d'appels 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 actif et appelé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 spécifie également le nom du déploiement et le microprocesseur cible en plus d'indiquer l'URL utilisée par ClickOnce pour vérifier l'existence de 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 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.deployment
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
Référence
Outil Manifest Generation and Editing, client graphique (MageUI.exe)
Invite de commandes du Kit de développement SDK