Questa documentazione è stata archiviata e non viene gestita.

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

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 a Mage.exe, è possibile utilizzare la versione dello strumento con interfaccia grafica, MageUI.exe. Per ulteriori informazioni, vedere Strumento per la generazione e la modifica di manifesti con interfaccia grafica (MageUI.exe).


Mage [commands] [commandOptions]

Parametri

Comando Descrizione

-cc, ClearApplicationCache

Cancella il contenuto della cache dell'applicazione di download di tutte le applicazioni solo in linea.

-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 –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 da modificare. Il file verrà analizzato automaticamente in base a un insieme di criteri euristici in modo da 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.

-s, -Sign [signOptions]

Utilizza un certificato per firmare un file. Le firme vengono inserite nei file come elementi XML.

-h, -Help

Descrive tutti i comandi disponibili e le rispettive opzioni.

-v, -Verbose

Fornisce informazioni più dettagliate su un'operazione in esecuzione.

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

Opzioni Descrizione

-appc, -AppCodeBase manifestReference

(Solo manifesti di distribuzione) Inserisce un URL o un riferimento al percorso del file manifesto dell'applicazione. È necessario specificare il percorso completo del manifesto dell'applicazione.

-appm, -AppManifest manifestPath

(Solo manifesti di applicazione) Inserisce un riferimento al manifesto di un'applicazione all'interno del 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 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 personale di un certificato digitale visualizzata nella console dei certificati di Windows.

Per hashSignature sono consentiti caratteri maiuscoli e minuscoli ed è possibile specificare sia una stringa singola sia una stringa composta da ottetti separati da spazi e racchiusa tra virgolette.

-fd, -FromDirectory directoryPath

(Solo manifesti di 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.

Un file non verrà mai contrassegnato automaticamente come file di dati. Questa 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, -Install willInstall

(Solo manifesti di distribuzione) Indica se l'applicazione ClickOnce deve essere installata nel computer locale o se deve essere eseguita 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 non è specificato alcun valore, quello predefinito è true.

Se si specifica l'opzione –RequiredUpdate, l'applicazione verrà sempre installata, indipendentemente dal valore passato a -Install.

-mv, -MinVersion [version]

(Solo manifesti di distribuzione) Versione minima dell'applicazione che può essere eseguita da un utente. Questo 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 a un difetto critico nella protezione, è possibile utilizzare questo flag per specificare che l'aggiornamento è obbligatorio e che l'utente non può continuare a eseguire versioni precedenti.

Se non viene specificata alcuna versione, verrà utilizzata quella indicata nel manifesto di distribuzione ClickOnce, come specificata dal flag -Version.

Il parametro version ha la stessa semantica dell'argomento del flag -Version.

-n, -Name nameString

(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. Se non viene specificato alcun nome, verrà utilizzato il valore predefinito "deploy".

-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

(Solo manifesti di applicazione e di distribuzione) Architettura del microprocessore su cui verrà eseguita la distribuzione. Questo valore è obbligatorio se si preparano installazioni con assembly precompilati per un microprocessore specifico. I valori validi sono msil, x86, ia64 e amd64. Il valore predefinito, 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, -ProviderUrl url

(Solo manifesti di distribuzione) Specifica l'URL che verrà esaminato da ClickOnce per verificare la disponibilità di aggiornamenti dell'applicazione.

-tr, -TrustLevel level

(Solo manifesti di applicazione) Livello di attendibilità da assegnare all'applicazione sui computer client. I valori possibili sono Internet, Intranet e FullTrust. Quando si crea un nuovo manifesto dell'applicazione, il valore predefinito è Intranet.

-tf, -ToFile filePath

(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 verrà scritto nella directory di lavoro corrente con un nome predefinito. Il nome esatto dipende dal tipo di file creato:

  • Distribuzione: deploy.application

  • Applicazione: application.exe.manifest

Se non si specifica –ToFile quando si utilizza –Update, l'output verrà scritto nel file di input.

-v, -Version versionNumber

(Solo manifesti di applicazione e 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. Il valore predefinito è 1.0.0.0.

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

Opzioni 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 personale di un certificato digitale visualizzata nella console dei certificati di Windows.

Per hashSignature sono consentiti caratteri maiuscoli e minuscoli ed è possibile specificare sia una stringa singola sia una stringa composta da ottetti separati da spazi e racchiusa tra virgolette.

-p, -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.

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. Se si modifica un file firmato, sarà necessario firmarlo di nuovo. 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 protezione 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 protezione 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 MageUI.exe con interfaccia grafica. Per ulteriori informazioni sull'utilizzo di MageUI.exe per aggiungere sezioni personalizzate relative all'attendibilità, vedere Strumento per la generazione e la modifica di manifesti con interfaccia grafica (MageUI.exe).

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

mage

Nelle chiamate di esempio seguenti vengono creati un manifesto dell'applicazione e un manifesto di distribuzione predefiniti. Questi 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 seguente viene creato un manifesto dell'applicazione in cui sono inclusi tutti gli assembly e i file di risorse presenti nella directory dell'applicazione HelloWorld .

mage –New Application –FromDirectory \bin -Version 1.0.0.0

Nell'esempio seguente vengono inoltre specificati il nome della distribuzione e il microprocessore di destinazione, nonché 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 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.deployment

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

Mostra: