Strumento per la generazione e la modifica di manifesti (Mage.exe)
Aggiornamento: novembre 2007
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 Strumento per la generazione e la modifica di manifesti con interfaccia grafica (MageUI.exe).
Mage.exe e MageUI.exe sono disponibili in vari percorsi, tra cui:
.NET Framework 2.0 SDK, disponibile come componente dell'installazione di Visual Studio 2005 o scaricabile dall'Area download Microsoft.
Windows SDK per Windows Vista, scaricabile dall'Area download Microsoft.
Visual Studio 2008. Versioni più recenti di Mage.exe e MageUI.exe sono incluse come componenti dell'installazione di Visual Studio 2008.
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 |
Descrizione |
|---|---|
-cc, ClearApplicationCache |
Cancella il contenuto della cache dell'applicazione di download di tutte le applicazioni solo in linea. |
-n, -NewfileType [newOptions] |
Crea un nuovo file del tipo specificato. I tipi validi sono:
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 un certificato per firmare un file. Le firme vengono inserite nei file come elementi XML. |
-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 |
Descrizione |
|---|---|---|---|
-appc, -AppCodeBasemanifestReference |
Manifesti di distribuzione. |
Inserisce un URL o un riferimento al percorso del file nel manifesto dell'applicazione. È necessario specificare il 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, verrà generato un errore. Lo stesso avviene se il file a cui fa riferimento manifestPath non è un manifesto di applicazione. |
|
-cf, -CertFilefilePath |
Tutti i tipi di file. |
Specifica il percorso di un certificato digitale per la firma di un manifesto. Questa opzione può essere utilizzata insieme all'opzione –Password se per il certificato è necessaria una password. |
|
-ch, -CertHashhashSignature |
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, -FromDirectorydirectoryPath |
Manifesti dell'applicazione. |
Inserisce nel manifesto dell'applicazione le descrizioni di tutti gli assembly e i file trovati in directoryPath, 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 base di codice 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. |
|
-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 di avvio 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, -NamenameString |
deploy |
Tutti i tipi di file. |
Nome utilizzato per identificare l'applicazione. ClickOnce utilizzerà questo nome per identificare l'applicazione nel menu di avvio, se l'applicazione è configurata per l'installazione, e nelle finestre di dialogo relative all'elevazione delle autorizzazioni. |
-pwd, -Passwordpasswd |
Tutti i tipi di file. |
Password utilizzata per firmare un manifesto con un certificato digitale. Questa opzione deve essere utilizzata insieme a –CertFile. |
|
-p, ProcessorprocessorValue |
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. Tra i valori validi sono inclusi msil, x86, ia64 e amd64. msil (Microsoft Intermediate Language) indica che tutti gli assembly sono indipendenti dalla piattaforma e che Common Language Runtime (CLR) eseguirà la compilazione JIT (Just-In-Time) quando l'applicazione verrà eseguita per la prima volta. |
-pu,-ProviderUrlurl |
Manifesti di distribuzione. |
Specifica l'URL che verrà esaminato da ClickOnce per verificare la disponibilità di aggiornamenti dell'applicazione. |
|
-pub, -PublisherpublisherName |
Manifesti dell'applicazione. Manifesti di distribuzione. Nuova opzione di .NET Framework 3.5. |
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. |
|
-ti, -TimestampUriuri |
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. Attualmente, soltanto Verisign supporta il servizio di aggiunta di timestamp. L'URI fornito come argomento deve essere "http://timestamp.verisign.com/scripts/timstamp.dll". |
|
-tr, -TrustLevellevel |
Intranet |
Manifesti dell'applicazione. |
Livello di attendibilità da assegnare all'applicazione nei computer client. I valori possibili sono Internet, Intranet e FullTrust. |
-t, -ToFilefilePath |
|
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. |
-u, -UseManifestForTrustwillUseForTrust |
false |
Manifesti dell'applicazione. Nuova opzione di .NET Framework 3.5. |
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, -VersionversionNumber |
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 integer a 32 bit senza segno. |
-wpf, -WPFBrowserApp isWPFApp |
false |
Manifesti dell'applicazione. Manifesti di distribuzione. Nuova opzione di .NET Framework 3.5. |
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 non in linea. |
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 utilizzata insieme a –Password. |
-ch, -CertHashhashSignature |
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. |
-p, -Passwordpasswd |
Password utilizzata per firmare un manifesto con un certificato digitale. Questa opzione deve essere utilizzata insieme a –CertFile. |
-t, -ToFilefilePath |
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 l'aggiunta di sezioni personalizzate relative all'attendibilità, vedere Strumento per la generazione e la modifica di manifesti con interfaccia grafica (MageUI.exe).
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
mage –New TrustLicense
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 dell'applicazioneHelloWorld.
mage –New Application –FromDirectory \bin -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 \bin -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 \bin -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 base di codice 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
Concetti
Cenni preliminari sulla distribuzione di applicazioni attendibili
Riferimenti
Strumento per la generazione e la modifica di manifesti con interfaccia grafica (MageUI.exe)