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 della riga di comando che consente di creare e modificare i manifesti delle applicazioni e di distribuzione e che può essere eseguito sia da script batch sia da altre applicazioni basate su Windows, incluse le applicazioni ASP.NET.

In alternativa, è possibile utilizzare l'applicazione grafica MageUI.exe anziché Mage.exe. Per ulteriori informazioni, vedere MageUI.exe (Strumento per la generazione e la modifica di manifesti, client grafico).

• Due versioni di Mage.exe e MageUI.exe sono incluse come componenti del pacchetto d'installazione di Visual Studio 2010. Per vedere informazioni sulla versione, eseguire MageUI.exe, selezionare Guida e selezionare Su. In questa documentazione viene descritta la versione 4.0.x.x di Mage.exe e MageUI.exe.

Mage [commands] [commandOptions]

Parametri

Nella tabella riportata di seguito vengono illustrati i comandi supportati da Mage.exe. Per ulteriori informazioni sulle opzioni supportate da questi comandi, vedere Opzioni dei comandi New e Update e Opzioni del comando Sign.

Comando	Oggetto di descrizione
-cc, ClearApplicationCache	Cancella il contenuto della cache dell'applicazione di download di tutte le applicazioni solo online.
-n, -New fileType [newOptions]	Crea un nuovo file del tipo specificato. I tipi validi sono: Deployment: Crea un nuovo manifesto di distribuzione. Application: Crea un nuovo manifesto dell'applicazione. Se non si specificano parametri aggiuntivi con questo comando, verrà creato automaticamente un file del tipo appropriato, con i valori di attributo e i tag predefiniti corretti. Utilizzare l'opzione -ToFile (vedere la tabella riportata di seguito) per specificare il nome e il percorso del nuovo file. Utilizzare l'opzione -FromDirectory, descritta nella tabella seguente, per creare un manifesto di un'applicazione con tutti gli assembly relativi a un'applicazione inclusi nella sezione <dependency>.
-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 insieme di regole euristiche per determinare se si tratta di un manifesto di distribuzione o di un manifesto dell'applicazione. Se un file è già stato firmato con un certificato, -Update rimuoverà il blocco relativo alla firma della chiave. Questo avviene perché la firma della chiave contiene un hash del file e l'operazione di modifica comprometterebbe la validità dell'hash. Utilizzare l'opzione -ToFile (vedere la tabella riportata di seguito) 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.
-h, -?, -Help[verbose]	Descrive tutti i comandi disponibili e le rispettive opzioni. Specificare verbose per ottenere informazioni dettagliate.

Opzioni dei comandi New e Update

Nella tabella seguente sono descritte le opzioni supportate dai comandi -New e -Update.

Opzioni	Valore predefinito	Si applica a	Oggetto di descrizione
-appc, -AppCodeBase manifestReference		Manifesti di distribuzione.	Inserisce un URL o un riferimento al percorso del file nel manifesto dell'applicazione. Questo valore deve corrispondere al percorso completo del manifesto dell'applicazione.
-appm, -AppManifest manifestPath		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, verrà generato un errore. Lo stesso avviene se il file a cui fa riferimento manifestPath non è un manifesto di applicazione.
-cf, -CertFile filePath		Tutti i tipi di file.	Specifica il percorso di un certificato digitale X509 per la firma di un manifesto. Questa opzione può essere utilizzata insieme all'opzione -Password se per il certificato è necessaria una password.
-ch, -CertHash hashSignature		Tutti i tipi di file.	Hash di un certificato digitale presente 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 parametro hashSignature può essere costituito da caratteri maiuscoli e 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.
-fd, -FromDirectory directoryPath		Manifesti dell'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, viene determinato automaticamente 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 la versione, la codebase e il nome dell'assembly. Nel secondo caso, verrà aggiunto un tag <file>. In base a un insieme semplice di criteri euristici, verrà inoltre rilevato l'eseguibile principale dell'applicazione, che verrà contrassegnato come punto di ingresso dell'applicazione ClickOnce nel manifesto. I file non vengono mai contrassegnati automaticamente come file di dati da Mage.exe. L'operazione deve essere eseguita manualmente. Per ulteriori informazioni, vedere Procedura: includere un file di dati in un'applicazione ClickOnce. Viene inoltre generato un hash per ciascun file in base alla relativa dimensione. Gli hash vengono utilizzati per verificare che i file di distribuzione non abbiano subito modifiche dopo la creazione del manifesto. Se si modifica un file nella distribuzione, è possibile eseguire Mage.exe con il comando -Update e l'opzione -FromDirectory affinché vengano aggiornati 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 utilizza -FromDirectory con il comando -Update, i file nel manifesto dell'applicazione che non sono più presenti nella directory verranno rimossi.
-if, -IconFile filePath		Manifesti dell'applicazione.	Specifica il percorso completo di un file di icona (.ICO). Questa icona viene visualizzata accanto al nome dell'applicazione nel menu di avvio e nella voce Installazione applicazioni. Se non viene fornita nessun'icona, viene utilizzata l'icona predefinita.
-ip, -IncludeProviderURL url	true	Manifesti di distribuzione.	Indica se il manifesto di distribuzione include il valore del percorso di aggiornamento impostato da -ProviderURL.
-i, -Install willInstall	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 dispone di una versione precedente rispetto a -MinVersion, l'applicazione verrà sempre installata, indipendentemente dal valore passato a -Install. Non è possibile utilizzare questa opzione con l'opzione -BrowserHosted. Il tentativo di specificare entrambe le opzioni per lo stesso manifesto genera un errore.
-mv, -MinVersion [version]	Versione indicata nel manifesto di distribuzione ClickOnce, così come specificata dal flag -Version.	Manifesti di distribuzione.	Versione minima dell'applicazione che può essere eseguita da un utente. Il flag contrassegna la versione specificata 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 parametro version ha la stessa semantica dell'argomento del flag -Version.
-n, -Name nameString	Distribuzione	Tutti i tipi di file.	Nome utilizzato per identificare l'applicazione. ClickOnce utilizzerà questo nome 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 editore con questa opzione, Mage.exe aggiorna il manifesto con il nome della società definito sul computer.Per utilizzare un nome diverso, assicurarsi di utilizzare questa opzione e specificare il nome desiderato dell'editore.
-pwd, -Password passwd		Tutti i tipi di file.	Password utilizzata per firmare un manifesto con un certificato digitale. Questa opzione deve essere utilizzata insieme a -CertFile.
-p, Processor processorValue	Msil	Manifesti dell'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 includono msil, x86, IA64 e amd64. msil è Microsoft Intermediate Language, che indica che tutti gli assembly sono indipendenti dalla piattaforma e vengono compilati in Common Language Runtime (CLR) quando l'applicazione viene eseguita per la prima volta.
-pu, -ProviderURL url		Manifesti di distribuzione.	Specifica l'URL che verrà esaminato da ClickOnce per verificare la disponibilità di aggiornamenti dell'applicazione.
-pub, -Publisher publisherName		Manifesti dell'applicazione. Manifesti di distribuzione.	Aggiunge il nome dell'editore all'elemento di descrizione del manifesto di distribuzione o del manifesto dell'applicazione. In caso di utilizzo su un manifesto dell'applicazione, specificare anche l'opzione -UseManifestForTrust con il valore impostato su true (o t). In caso contrario il parametro genera un errore.
-s, -SupportURL url		Manifesti dell'applicazione. Manifesti di distribuzione.	Specifica il collegamento visualizzato per l'applicazione ClickOnce in Installazione applicazioni.
-ti, -TimestampUri uri		Manifesti dell'applicazione. Manifesti di distribuzione.	URL di un servizio di aggiunta di timestamp digitale. L'aggiunta di timestamp nei manifesti consente di evitare la necessità di firmare nuovamente i manifesti in caso di scadenza del certificato digitale prima della distribuzione della versione successiva dell'applicazione. Per ulteriori informazioni, vedere Membri del programma Microsoft Root Certificate Program.
-t, -ToFile filePath	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 utilizza -New, l'output viene scritto nella directory di lavoro corrente. Se non si specifica -ToFile quando si utilizza -Update, l'output viene scritto nel file di input.
-tr, -TrustLevel level	Intranet	Manifesti dell'applicazione.	Livello di attendibilità da assegnare all'applicazione nei computer client. I valori possibili sono Internet, Intranet e FullTrust.
-um, -UseManifestForTrust willUseForTrust	False	Manifesti dell'applicazione.	Specifica se la firma digitale del manifesto dell'applicazione verrà utilizzata per prendere decisioni sull'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 sull'attendibilità. Se il valore è impostato su false (o f), verrà utilizzata la firma del manifesto di distribuzione.
-v, -Version versionNumber	1.0.0.0	Manifesti dell'applicazione. Manifesti di distribuzione.	Versione della distribuzione. L'argomento deve essere una stringa di versione valida in formato "N.N.N.N", dove "N" è un valore di tipo Unsigned Integer a 32 bit.
-wpf, -WPFBrowserApp isWPFApp	false	Manifesti dell'applicazione. Manifesti di distribuzione.	Utilizzare questo flag unicamente se si tratta di un'applicazione Windows Presentation Foundation (WPF) che verrà ospitata all'interno di Internet Explorer anziché di un file eseguibile autonomo. I valori validi sono true (o t) e false (o f). Per i manifesti dell'applicazione, l'attributo hostInBrowser viene inserito nell'elemento entryPoint del manifesto dell'applicazione. Per i manifesti di distribuzione, l'attributo install dell'elemento deployment viene impostato su false e il manifesto di distribuzione viene salvato con estensione xbap. Se l'argomento viene 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	Oggetto di descrizione
-cf, -CertFile filePath	Specifica il percorso di un certificato digitale per la firma di un manifesto. Questa opzione può essere utilizzata insieme a -Password.
-ch, -CertHash hashSignature	Hash di un certificato digitale presente 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 parametro hashSignature può essere costituito da caratteri maiuscoli e 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.
-pwd, -Password passwd	Password utilizzata per firmare un manifesto con un certificato digitale. Questa opzione deve essere utilizzata insieme a -CertFile.
-t, -ToFile filePath	Specifica il percorso di output del file creato o modificato.

Note

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

Tutti gli argomenti utilizzati con il comando -Sign possono essere utilizzati 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

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, la firma precedente verrà sostituita con quella nuova.

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

Prima di distribuire l'applicazione, è necessario firmare l'assembly di distribuzione e quello dell'applicazione. Per informazioni sulla firma degli assembly, vedere Cenni preliminari sulla distribuzione di applicazioni attendibili.

L'opzione -TrustLevel relativa ai manifesti delle applicazioni 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 utilizza l'opzione -TrustLevel per inserire un'applicazione in questa area, il gestore di attendibilità di Common Language Runtime chiederà all'utente di specificare se desidera concedere questo livello di attendibilità. Se si distribuisce l'applicazione in una rete aziendale, è possibile utilizzare la distribuzione di applicazioni attendibili per aumentare il livello di attendibilità dell'applicazione senza chiedere conferma all'utente.

Nei manifesti delle applicazioni sono supportate anche sezioni personalizzate relative all'attendibilità. 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 personalizzata relativa all'attendibilità. A tale scopo, è possibile utilizzare un editor di testo, un parser XML o lo strumento MageGUI.exe con interfaccia grafica. Per ulteriori informazioni sull'utilizzo di MageGUI.exe per aggiungere sezioni personalizzate relative all'attendibilità, vedere MageUI.exe (Strumento per la generazione e la modifica di manifesti, client grafico).

I nuovi manifesti creati con la versione 4 di Mage.exe, inclusa in Visual Studio 2010, vengono destinati a .NET Framework 4 Client Profile. Per scegliere versioni precedenti di .NET Framework, è necessario utilizzare una versione precedente di Mage.exe. In caso di aggiunta o rimozione di assembly da un manifesto esistente o firmando nuovamente un manifesto esistente, MageUI.exe non aggiorna il manifesto sul .NET Framework 4 Client Profile target. 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	Aprire	OK	OK
	Chiudi	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	Aprire	OK	OK
	Chiudi	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
	Aggiungi 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
	Aggiungi un assembly	Non supportato	OK
	Rimuovere un assembly	Non supportato	OK

I nuovi manifesti creati con Mage.exe vengono destinati a .NET Framework 4 Client Profile. Le applicazioni ClickOnce destinate a .NET Framework 4 Client Profile possono essere in esecuzione su .NET Framework 4 Client Profile e sulla versione completa di .NET Framework 4. Se l'applicazione è destinata alla versione completa di .NET Framework 4 e non può essere in esecuzione su .NET Framework 4 Client Profile, rimuovere l'elemento del client <framework> tramite un editor di testo e firmare nuovamente il manifesto. Quello che segue è un elemento <framework> di esempio destinato a .NET Framework 4 Client Profile.

<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 riportati di seguito vengono creati un manifesto di distribuzione e un manifesto dell'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

Nell'esempio riportato di seguito viene creato un manifesto dell'applicazione in cui sono inseriti tutti gli assembly e i file di risorse presenti nella directory corrente.

mage -New Application -FromDirectory . -Version 1.0.0.0

L'esempio riportato di seguito 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 riportato di seguito viene dimostrato come creare una coppia di manifesti per la distribuzione di un'applicazione WPF che dovrà essere ospitata in 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

Nell'esempio seguente viene aggiornato un manifesto di distribuzione con le informazioni provenienti da un manifesto dell'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 nel computer client.

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 presente nella directory di lavoro corrente.

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

Vedere anche

Attività

Procedura dettagliata: distribuzione manuale di un'applicazione ClickOnce

Riferimenti

MageUI.exe (Strumento per la generazione e la modifica di manifesti, client grafico)

Prompt dei comandi di Visual Studio e Windows SDK

Concetti

Sicurezza e distribuzione di ClickOnce

Cenni preliminari sulla distribuzione di applicazioni attendibili