Mage.exe (Strumento per la generazione e la modifica di manifesti)

Lo Strumento per la generazione e la modifica di manifesti (Mage.exe) è uno strumento da riga di comando che supporta la creazione e la modifica dei manifesti delle applicazioni e delle distribuzioni. Come strumento della riga di comando, Mage.exe può essere eseguito da script batch e altre applicazioni basate su Windows, incluse le applicazioni ASP.NET.

È anche possibile usare l'applicazione con interfaccia grafica MageUI.exe anziché Mage.exe. Per altre informazioni, vedere MageUI.exe (Manifest Generation and Editing Tool, Graphical Client).

Viene installato automaticamente con Visual Studio. Per eseguire lo strumento, usare il prompt dei comandi per gli sviluppatori di Visual Studio o Visual Studio Developer PowerShell.

Due versioni di Mage.exe e MageUI.exe sono incluse con Visual Studio. Per visualizzare le informazioni sulla versione, eseguire MageUI.exe, scegliere ? e quindi Informazioni su. In questa documentazione viene descritta la versione 4.0.x.x di Mage.exe e MageUI.exe.

Sintassi

Mage [commands] [commandOptions]

Parametri

La tabella seguente illustra i comandi supportati da Mage.exe. Per altre informazioni sulle opzioni supportate da questi comandi, vedere Opzioni dei comandi New e Update e Opzioni del comando Sign.

Comando Descrizione
-cc, ClearApplicationCache Cancella il contenuto della cache di download di tutte le applicazioni solo online.
-n, -NewfileType [newOptions] Crea un nuovo file del tipo specificato. I tipi validi sono:

- Deployment: crea un nuovo manifesto di distribuzione.
- Application: crea un nuovo manifesto di applicazione.

Se non si specificano parametri aggiuntivi con questo comando, verrà creato automaticamente un file del tipo appropriato, con gli adeguati tag e valori di attributo predefiniti.

Usare l'opzione -ToFile (vedere la tabella seguente) per specificare il nome e il percorso del nuovo file.

Usare l'opzione -FromDirectory (vedere nella tabella seguente) per creare un manifesto dell'applicazione con tutti gli assembly per un'applicazione aggiunta alla <sezione dependency> del manifesto.
-u, -Update[filePath] [updateOptions] Esegue una o più modifiche in un file manifesto. Non è necessario specificare il tipo di file che si sta modificando. Mage.exe esaminerà il file utilizzando un set di regole euristiche per determinare se si tratta di un manifesto di distribuzione o di un manifesto di applicazione.

Se un file è già stato firmato con un certificato, -Update rimuoverà il blocco della firma con chiave. Questo è necessario perché la firma con chiave contiene un hash del file e la modifica di quest'ultimo rende l'hash non valido.

Usare l'opzione -ToFile (vedere la tabella seguente) per specificare un nuovo nome e percorso del file anziché sovrascrivere il file esistente.
-s, -Sign[signOptions] Utilizza una coppia di chiavi o il certificato X509 per firmare un file. Le firme vengono inserite nei file come elementi XML.

È necessario essere connessi a Internet quando si firma un manifesto che specifica un valore -TimestampUri .
-ver, -Verify[nomefile-manifesto] Verifica che il manifesto sia firmato correttamente. Non può essere combinato con altri comandi.

Disponibile in .NET Framework 4.7 e versioni successive.
-h, -?, -Help[verbose] Descrive tutti i comandi disponibili e le rispettive opzioni. Specificare verbose per ottenere informazioni dettagliate.

Opzioni dei comandi New e Update

La tabella seguente illustra le opzioni supportate dai comandi -New e -Update:

Opzioni Valore predefinito Si applica a Descrizione
-a, -Algorithm sha1RSA Manifesti di applicazione.

Manifesti di distribuzione.
Specifica l'algoritmo con cui generare i digest di dipendenza. Il valore deve essere "sha256RSA" o "sha1RSA".

Utilizzare con l'opzione "-Update". Questa opzione viene ignorata quando si utilizza l'opzione "-Sign".
-appc, -AppCodeBasemanifestReference Manifesti di distribuzione. Inserisce un riferimento a un URL o a percorso di file nel file manifesto dell'applicazione. Questo valore deve corrispondere al percorso completo del manifesto dell'applicazione.
-appm, -AppManifestmanifestPath Manifesti di distribuzione. Inserisce un riferimento a un manifesto dell'applicazione di distribuzione nel relativo manifesto di distribuzione.

Se il file indicato in manifestPath non esiste, Mage.exe genera un errore. Lo stesso avviene se il file a cui fa riferimento manifestPath non è un manifesto dell'applicazione.
-cf, -CertFilefilePath Tutti i tipi di file. Specifica il percorso di un certificato digitale X509 per la firma di un manifesto o di un file di licenza. Questa opzione può essere usata insieme all'opzione -Password se il certificato richiede una password per i file PFX (Personal Information Exchange). A partire da .NET Framework 4.7, se il file non contiene una chiave privata, è necessario usare una combinazione delle opzioni -CryptoProvider e -KeyContainer.

A partire da .NET Framework 4.6.2, Mage.exe firma i manifesti con certificati CNG e CAPI.
-ch, -CertHashhashSignature Tutti i tipi di file. Hash di un certificato digitale contenuto nell'archivio dei certificati personali del computer client. Corrisponde alla stringa di identificazione digitale di un certificato digitale visualizzata nella console dei certificati di Windows.

Il parametrohashSignature può essere costituito da caratteri maiuscoli o minuscoli e può essere specificato sia come stringa singola sia con gli ottetti dell'identificazione digitale separati da spazi e l'intera identificazione digitale racchiusa tra virgolette.
-csp, -CryptoProviderprovider-name Tutti i tipi di file. Specifica il nome di un provider del servizio di crittografia (CSP) che include il contenitore di chiavi private. È necessaria l'opzione -KeyContainer.

Questa opzione è disponibile a partire da .NET Framework 4.7.
-fd, -FromDirectorydirectoryPath Manifesti di applicazione. Inserisce nel manifesto dell'applicazione le descrizioni di tutti gli assembly e i file trovati in directoryPath, incluse tutte le sottodirectory, dove directoryPath corrisponde alla directory contenente l'applicazione che si desidera distribuire. Per ogni file incluso nella directory, Mage.exe determina se si tratta di un assembly o di un file statico. Nel primo caso, verranno aggiunti un tag <dependency> e un attributo installFrom all'applicazione con il nome, la codebase e la versione dell'assembly. Nel secondo caso, verrà aggiunto un tag <file> . In base a un semplice set di regole euristiche, Mage.exe rileva anche l'eseguibile principale dell'applicazione e lo contrassegna come punto di ingresso dell'applicazione ClickOnce nel manifesto.

Mage.exe non contrassegna mai i file come file di dati. L'operazione deve essere eseguita manualmente. Per altre informazioni, vedere Procedura: Includere un file di dati in un'applicazione ClickOnce.

Mage.exe genera anche un hash per ogni file in base alla relativa dimensione. Gli hash vengono utilizzati da ClickOnce per verificare che i file di distribuzione non siano stati manomessi dopo la creazione del manifesto. Se uno dei file della distribuzione viene modificato, è possibile eseguire Mage.exe con il comando -Update e l'opzione -FromDirectory per aggiornare gli hash e le versioni degli assembly di tutti i file a cui viene fatto riferimento.

L'opzione-FromDirectory includerà tutti i file in tutte le sottodirectory trovate all'interno di directoryPath.

Se si usa -FromDirectory con il comando -Update, Mage.exe rimuove dal manifesto dell'applicazione i file che non sono più presenti nella directory.
-if, -IconFilefilePath Manifesti di applicazione. Specifica il percorso completo di un file icona (.ICO). Questa icona viene visualizzata accanto al nome dell'applicazione nel menu Start e nella voce in Installazione applicazioni. Se non viene fornita nessun'icona, viene utilizzata l'icona predefinita.
-ip, -IncludeProviderURLurl true Manifesti di distribuzione. Indica se il manifesto di distribuzione include il valore del percorso di aggiornamento impostato da -ProviderURL.
-i, -InstallwillInstall true Manifesti di distribuzione. Indica se installare o meno l'applicazione ClickOnce nel computer locale o se eseguirla dal Web. Se l'applicazione viene installata, nel menu Start di Windows verrà creato un collegamento corrispondente. I valori validi sono "true" (o "t") e "false" (o "f").

Se si specifica l'opzione -MinVersion e l'utente ha una versione precedente rispetto a -MinVersion , l'applicazione verrà sempre installata, indipendentemente dal valore passato a -Install.

Non è possibile usare questa opzione con l'opzione -BrowserHosted . Il tentativo di specificare entrambe le opzioni per lo stesso manifesto genera un errore.
-kc, -KeyContainername Tutti i tipi di file. Specifica il contenitore di chiavi che include il nome della chiave privata. È necessaria l'opzione CryptoProvider.

Questa opzione è disponibile a partire da .NET Framework 4.7.
-mv, -MinVersion[version] Versione indicata nel manifesto di distribuzione ClickOnce, come specificata dal flag -Version . Manifesti di distribuzione. Versione minima dell'applicazione che può essere eseguita da un utente. Il flag contrassegna la versione denominata dell'applicazione come aggiornamento obbligatorio. Se si rilascia una versione del prodotto contenente un aggiornamento relativo a una modifica importante o a una correzione di un difetto critico nella sicurezza, è possibile utilizzare tale flag per specificare che l'aggiornamento è obbligatorio e che l'utente non può continuare a eseguire versioni precedenti.

Il parametroversion ha la stessa semantica dell'argomento del flag -Version .
-n, -NamenameString Distribuzione Tutti i tipi di file. Nome utilizzato per identificare l'applicazione. Questo nome verrà usato da ClickOnce per identificare l'applicazione nel menu Start (se l'applicazione è configurata per l'installazione) e nelle finestre di dialogo relative all'elevazione delle autorizzazioni. Nota: se si sta aggiornando un manifesto esistente e non si specifica un nome di editore con questa opzione, Mage.exe aggiorna il manifesto con il nome dell'organizzazione definito nel computer. Per utilizzare un nome diverso, assicurarsi di utilizzare questa opzione e specificare il nome dell'editore desiderato.
-pwd, -Passwordpasswd Tutti i tipi di file. Password utilizzata per firmare un manifesto con un certificato digitale. Questa opzione deve essere usata insieme a -CertFile .
-p, ProcessorprocessorValue Msil Manifesti di applicazione.

Manifesti di distribuzione.
Architettura del microprocessore sulla quale verrà eseguita la distribuzione. Questo valore è obbligatorio se si preparano installazioni con assembly precompilati per un microprocessore specifico. I valori validi includono msil, x86, ia64e amd64. msil sta per Microsoft Intermediate Language. Questo indica che tutti gli assembly sono indipendenti dalla piattaforma e verranno sottoposti a una compilazione JIT (just-in-time) in Common Language Runtime (CLR) alla prima esecuzione dell'applicazione.
-pu,-ProviderURLurl Manifesti di distribuzione. Specifica l'URL che verrà esaminato da ClickOnce per verificare la disponibilità di aggiornamenti dell'applicazione.
-pub, -PublisherpublisherName Manifesti di applicazione.

Manifesti di distribuzione.
Aggiunge il nome dell'editore all'elemento di descrizione del manifesto di distribuzione o del manifesto dell'applicazione. Se usata sul manifesto di un'applicazione, l'opzione -UseManifestForTrust deve essere specificata anche con il valore "true" (o "t"). In caso contrario, il parametro genererà un errore.
-s, -SupportURLurl Manifesti di applicazione.

Manifesti di distribuzione.
Specifica il collegamento visualizzato per l'applicazione ClickOnce in Installazione applicazioni.
-ti, -TimestampUriuri Manifesti di applicazione.

Manifesti di distribuzione.
URL di un servizio di aggiunta di timestamp digitale. L'aggiunta di timestamp nei manifesti evita la necessità di firmarli nuovamente in caso di scadenza del certificato digitale prima della distribuzione della versione successiva dell'applicazione. Per altre informazioni, vedere Windows root certificate program members(Membri del programma Windows Root Certificate).
-t, -ToFilefilePath - Nuovo:
- Distribuzione: deploy.application
- Applicazione: application.exe.manifest
- Aggiornamento:
- File di input.
Tutti i tipi di file. Specifica il percorso di output del file creato o modificato.

Se non si specifica -ToFile quando si usa -New, l'output viene scritto nella directory di lavoro corrente. Se non si specifica -ToFile quando si usa -Update, Mage.exe riscrive il file nel file di input.
-tr, -TrustLevellevel Basato sulla zona in cui risiede l'URL dell'applicazione. Manifesti di applicazione. Livello di attendibilità da concedere all'applicazione nei computer client. I valori possibili sono "Internet","Intranet" e "FullTrust".
-um, -UseManifestForTrustwillUseForTrust Falso Manifesti di applicazione. Specifica se la firma digitale del manifesto dell'applicazione verrà utilizzata per prendere decisioni di attendibilità quando l'applicazione è in esecuzione sul client. Se il valore è impostato su "true" (o "t"), il manifesto dell'applicazione viene utilizzato per prendere decisioni di attendibilità. Se il valore è impostato su "false" (o "f"), verrà utilizzata la firma del manifesto di distribuzione.
-v, -VersionversionNumber 1.0.0.0 Manifesti di applicazione.

Manifesti di distribuzione.
Versione della distribuzione. L'argomento deve essere una stringa di versione valida nel formato "N.N.N.N", dove "N" è un Integer senza segno a 32 bit.
-wpf, -WPFBrowserAppisWPFApp false Manifesti di applicazione.

Manifesti di distribuzione.
Usare questo flag solo se l'applicazione è un'applicazione Windows Presentation Foundation (WPF) che verrà ospitata all'interno di un browser e non è un eseguibile autonomo. I valori validi sono "true" (o "t") e "false" (o "f").

Per i manifesti di applicazione, inserisce l'attributo hostInBrowser nell'elemento entryPoint del manifesto.

Per i manifesti di distribuzione, imposta l'attributo install dell'elemento deployment su false e salva il manifesto di distribuzione con l'estensione .xbap. Se l'argomento è specificato insieme all'argomento -Install , viene generato un errore dovuto al fatto che un'applicazione ospitata dal browser non può essere un'applicazione installata offline.

Opzioni del comando Sign

Nella tabella seguente sono descritte le opzioni supportate dal comando -Sign , valide per tutti i tipi di file.

Opzioni Descrizione
-cf, -CertFilefilePath Specifica il percorso di un certificato digitale per la firma di un manifesto. Questa opzione può essere usata insieme all'opzione -Password se il certificato richiede una password per i file PFX (Personal Information Exchange). A partire da .NET Framework 4.7, se il file non contiene una chiave privata, è necessario usare una combinazione delle opzioni -CryptoProvider e -KeyContainer.

A partire da .NET Framework 4.6.2, Mage.exe firma i manifesti con certificati CNG e CAPI.
-ch, -CertHashhashSignature Hash di un certificato digitale contenuto nell'archivio dei certificati personali del computer client. Corrisponde alla proprietà Thumbprint di un certificato digitale visualizzata nella console dei certificati di Windows.

Il parametrohashSignature può essere costituito da caratteri maiuscoli o minuscoli e può essere specificato sia come stringa singola sia con gli ottetti dell'identificazione digitale separati da spazi e l'intera identificazione digitale racchiusa tra virgolette.
-csp, -CryptoProviderprovider-name Specifica il nome di un provider del servizio di crittografia (CSP) che include il contenitore di chiavi private. È necessaria l'opzione -KeyContainer.

Questa opzione è disponibile a partire da .NET Framework 4.7.
-kc, -KeyContainername Specifica il contenitore di chiavi che include il nome della chiave privata. È necessaria l'opzione CryptoProvider.

Questa opzione è disponibile a partire da .NET Framework 4.7.
-pwd, -Passwordpasswd Password utilizzata per firmare un manifesto con un certificato digitale. Questa opzione deve essere usata insieme a -CertFile .
-t, -ToFilefilePath Specifica il percorso di output del file creato o modificato.

Osservazioni:

Nessun argomento di Mage.exe fa distinzione tra maiuscole e minuscole. I comandi e le opzioni possono essere preceduti da un trattino (-) o da una barra (/).

Tutti gli argomenti usati con il comando -Sign possono essere usati in qualsiasi momento anche con il comando -New o -Update . I comandi indicati di seguito sono equivalenti.

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

Nota

A partire da .NET Framework versione 4.6.2 sono supportati anche i certificati CNG.

L'applicazione della firma è l'ultima attività da eseguire su un documento perché per verificare la validità della firma viene utilizzato un hash del file. Qualsiasi modifica apportata a un file firmato comporta la necessità di firmarlo nuovamente. Se si firma un documento già firmato in precedenza, Mage.exe sostituisce la firma precedente con quella nuova.

Quando si usa l'opzione -AppManifest per inserire dati in un manifesto di distribuzione, Mage.exe presuppone che il manifesto dell'applicazione si trovi nella stessa directory del manifesto della distribuzione, all'interno di una sottodirectory denominata in base alla versione della distribuzione corrente, e configura il manifesto della distribuzione di conseguenza. Se il manifesto dell'applicazione si trova in un altro percorso, usare l'opzione -AppCodeBase per impostare il percorso alternativo.

Prima di distribuire l'applicazione, è necessario firmare il manifesto di distribuzione e quello dell'applicazione. Per indicazioni sulla firma dei manifesti, vedere Trusted Application Deployment Overview.

L'opzione -TrustLevel relativa ai manifesti di applicazione definisce il set di autorizzazioni necessarie per l'esecuzione dell'applicazione sul computer client. Per impostazione predefinita, alle applicazioni viene assegnato un livello di attendibilità in base all' area in cui si trovano i rispettivi URL. Le applicazioni distribuite in una rete aziendale vengono in genere inserite nell'area Intranet, mentre quelle distribuite su Internet vengono inserite nell'area Internet. Entrambe le aree di sicurezza limitano l'accesso dell'applicazione alle risorse locali, ma l'area Intranet è leggermente meno restrittiva dell'area Internet. Nell'area FullTrust le applicazioni dispongono dell'accesso completo alle risorse locali di un computer. Se si usa l'opzione -TrustLevel per inserire un'applicazione in questa zona, il componente Gestione attendibilità di CLR chiederà all'utente di decidere se concedere questo livello di attendibilità superiore. Se si distribuisce l'applicazione in una rete aziendale, è possibile utilizzare la funzionalità di distribuzione di applicazioni attendibili per aumentare il livello di attendibilità dell'applicazione senza chiedere conferma all'utente.

Nei manifesti di applicazioni sono supportate anche sezioni Trust personalizzate. In questo modo, viene rispettato il principio di sicurezza in base al quale devono essere richieste autorizzazioni minime, poiché è possibile configurare il manifesto in modo da richiedere solo le autorizzazioni necessarie per l'esecuzione dell'applicazione. Mage.exe non consente di aggiungere direttamente una sezione Trust personalizzata. A tale scopo, è possibile usare un editor di testo, un parser XML o lo strumento con interfaccia grafica MageUI.exe. Per altre informazioni sull'uso di MageUI.exe per aggiungere sezioni Trust personalizzate, vedere MageUI.exe (Strumento per la generazione e la modifica di manifesti, client grafico).

Visual Studio 2017 include la versione 4.6.1 di Mage.exe. I manifesti creati con questa versione di Mage.exe usano come destinazione .NET Framework 4. Per usare come destinazione versioni precedenti di .NET Framework, usare una versione precedente di Mage.exe.

In caso di aggiunta o rimozione di assembly da un manifesto esistente o di nuova firma di un manifesto esistente, Mage.exe non aggiorna il manifesto con .NET Framework 4 come destinazione.

Nelle tabelle seguenti vengono mostrate queste funzionalità e limitazioni:

Versione del manifesto Operazione Mage v2.0 Mage v4.0
Manifesto per applicazioni destinate alla versione 2.0 o 3.x di .NET Framework Apertura Ok Ok
Chiusura Ok Ok
Salva Ok Ok
Ripetere la firma Ok Ok
Nuovo Ok Non supportato
Aggiornare (vedere di seguito) Ok Ok
Manifesto per applicazioni destinate alla versione 4 di .NET Framework Apertura Ok Ok
Chiusura Ok Ok
Salva Ok Ok
Ripetere la firma Ok Ok
Nuovo Non supportato Ok
Aggiornare (vedere di seguito) Non supportato Ok
Versione del manifesto Dettagli dell'operazione di aggiornamento Mage v2.0 Mage v4.0
Manifesto per applicazioni destinate alla versione 2.0 o 3.x di .NET Framework Modificare un assembly Ok Ok
Aggiungere un assembly Ok Ok
Rimuovere un assembly Ok Ok
Manifesto per applicazioni destinate alla versione 4 di .NET Framework Modificare un assembly Non supportato Ok
Aggiungere un assembly Non supportato Ok
Rimuovere un assembly Non supportato Ok

Mage.exe crea nuovi manifesti destinati al profilo client .NET Framework 4. Le applicazioni ClickOnce destinate al profilo client .NET Framework 4 possono essere eseguite sia nel profilo client .NET Framework 4 che nella versione completa di .NET Framework 4. Se l'applicazione è destinata alla versione completa di .NET Framework 4 e non può essere eseguita nel profilo client .NET Framework 4, rimuovere l'elemento client <framework> usando un editor di testo e firmare nuovamente il manifesto.

Di seguito è riportato un elemento di esempio <framework> destinato al profilo client .NET Framework 4:

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

Esempi

Nell'esempio seguente viene visualizzata l'interfaccia utente per Mage (MageUI.Exe).

mage

Negli esempi seguenti vengono creati un manifesto di distribuzione e un manifesto di applicazione predefiniti. Tutti i file vengono creati nella directory di lavoro corrente e sono denominati rispettivamente deploy.application e application.exe.manifest.

mage -New Deployment
mage -New Application

L'esempio seguente crea un manifesto dell'applicazione in cui sono inseriti tutti gli assembly e tutti i file di risorse presenti nella directory corrente.

mage -New Application -FromDirectory . -Version 1.0.0.0

L'esempio seguente continua l'esempio precedente specificando il nome di distribuzione e il microprocessore di destinazione. Nell'esempio viene inoltre specificato l'URL in cui ClickOnce dovrà controllare la disponibilità di aggiornamenti.

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

Nell'esempio seguente viene illustrato come creare una coppia di manifesti per la distribuzione di un'applicazione WPF che verrà ospitata in un browser.

mage -New Application -FromDirectory . -Version 1.0.0.0 -WPFBrowserApp true
mage -New Deployment -AppManifest 1.0.0.0\application.manifest -WPFBrowserApp true

L'esempio seguente crea un manifesto dell'applicazione in cui sono inseriti tutti gli assembly e tutti i file di risorse presenti nella directory corrente e applica la firma.

mage -New Application -FromDirectory . -Version 1.0.0.0 -KeyContainer keypair.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"

Nell'esempio seguente viene aggiornato un manifesto di distribuzione con le informazioni provenienti da un manifesto di applicazione e viene impostata la codebase per il percorso del manifesto dell'applicazione.

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

Nell'esempio seguente viene modificato il manifesto di distribuzione in modo da imporre un aggiornamento della versione installata dall'utente.

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

Nell'esempio seguente viene indicato al manifesto di distribuzione di recuperare il manifesto dell'applicazione da un'altra directory.

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

Nell'esempio seguente viene firmato un manifesto di distribuzione esistente mediante un certificato digitale nella directory di lavoro corrente.

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

L'esempio seguente firma un manifesto di distribuzione esistente tramite un certificato digitale e una chiave privata nella directory di lavoro corrente.

mage -Sign deploy.application -CertFile cert.pfx -KeyContainer keyfile.snk -CryptoProvider "Microsoft Enhanced Cryptographic Provider v1.0"

Vedi anche