Strumento di unione di ASP.NET (Aspnet_merge.exe)
Aggiornamento: novembre 2007
Lo strumento di unione di ASP.NET (Aspnet_merge.exe) consente di combinare e gestire assembly creati dallo strumento per la compilazione di ASP.NET (Aspnet_compiler.exe). Lo strumento di unione di ASP.NET opera su assembly creati utilizzando ASP.NET 2.0 o versioni successive.
È possibile utilizzare lo strumento per la compilazione di ASP.NET per precompilare un'applicazione da distribuire. Lo strumento crea un assembly per ciascuna cartella dati nel sito Web di destinazione oppure crea un assembly per ciascun file di dati. Lo strumento di unione di ASP.NET offre una maggiore flessibilità in termini di distribuzione e gestione del rilascio e consente di effettuare le operazioni seguenti:
Creare un assembly per l'intero sito Web.
Creare un assembly per ciascuna cartella del sito Web e aggiungere un prefisso al nome dell'assembly.
Creare un unico assembly soltanto per gli elementi dell'interfaccia utente (UI) del sito Web, ad esempio pagine e controlli.
aspnet_merge [-?]
applicationPath
[-keyfile filename [-delaysign]]
[-o assemblyname | -w assemblyname | -prefix prefix]
[-copyattrs [assemblyfile]]
[-debug]
[-nologo]
[-errorstack]
[-r]
[-xmldocs]
[-a]
[-logfile logfile]
[-allowattrs textfile]
Argomenti
Argomento |
Descrizione |
|---|---|
applicationPath |
(Obbligatorio) Specifica il nome della cartella contenente l'applicazione per la quale si desidera creare assembly. Questa è l'operazione di unione predefinita. Crea un numero di assembly inferiore rispetto al numero generato dall'opzione fixednames del compilatore. |
Opzioni
Opzione |
Descrizione |
||
|---|---|---|---|
-keyfile filename |
Specifica la necessità di applicare l'attributo AssemblyKeyFileAttribute all'assembly compilato. L'attributo specifica il nome del file contenente la coppia di chiavi, pubblica e privata, utilizzate per generare un nome sicuro. Se gli assembly di input sono firmati e lo strumento di unione non firma gli assembly, verrà visualizzato un messaggio con l'avviso che le chiavi sono state rimosse. Se non viene specificato un nome file di chiave e solo un assembly è dotato di una chiave pubblica, l'esecuzione dello strumento di unione non produce risultati. |
||
-delaysign |
Specifica la necessità di applicare l'attributo AssemblyDelaySignAttribute all'assembly generato. L'attributo specifica che l'assembly deve essere firmato soltanto con il token di chiave pubblica anziché con la coppia di chiavi pubblica e privata. Questa opzione deve essere combinata con -keyfile. Se l'attributo è già applicato all'assembly nei file di codice, lo strumento di unione genera un'eccezione. Se si utilizza l'opzione delaysign e la verifica del nome sicuro non è attivata, il codice prodotto dallo strumento di unione può essere eseguito prima che il codice venga firmato. Se la verifica del nome sicuro non è attivata, assicurarsi che il codice non sia vulnerabile agli attacchi da parte di utenti malintenzionati prima del completamento della firma. |
||
-o assemblyname |
Specifica il nome di un unico assembly unito per tutto il contenuto dell'interfaccia utente Web e gli assembly di primo livello. Tutti i file con estensione di file compiled vengono modificati in modo da fare riferimento all'unico assembly. Tali file vengono compilati, ad esempio, dal contenuto di file con estensione aspx, master e ascx. Non è possibile combinare questa opzione con le opzioni w o prefix. Il parametro assemblyname è obbligatorio. |
||
-w assemblyname |
Specifica il nome di un unico assembly unito per tutto il contenuto dell'interfaccia utente Web, ad esempio pagine e controlli utente. Tutti i file con estensione aspx, master e ascx compilati vengono modificati per fare riferimento all'unico assembly. In questo modo è possibile aggiornare gli elementi dell'interfaccia utente separatamente rispetto all'aggiornamento del codice. Gli assembly di primo livello per le risorse locali e globali non vengono uniti. Non è possibile combinare questa opzione con le opzioni o o prefix. Il parametro assemblyname è obbligatorio. |
||
-prefix prefix |
Specifica un prefisso per i nomi di assembly. Il nome dell'assembly della cartella radice è costituito unicamente dal parametro prefix. Per gli assembly delle sottocartelle il parametro prefix viene combinato con il nome della sottocartella. Se, ad esempio, una sottocartella è denominata Admin, l'assembly risultante sarà denominato prefix.Admin.dll. Per i siti Web non aggiornabili, temi e risorse locali vengono compilati dallo strumento per la compilazione in assembly separati nella cartella Bin. Per i siti Web aggiornabili, temi e risorse locali non vengono compilati in assembly nella cartella Bin, ma vengono lasciati nelle rispettive cartelle originali all'interno dell'applicazione. Per i siti aggiornabili, inoltre, i file con estensione aspx, master e ascx vengono modificati dallo strumento di unione in modo che puntino al nuovo assembly unito per la cartella in cui si trovano i file. Non è possibile combinare questa opzione con le opzioni o o w. Il parametro prefix è obbligatorio. |
||
-copyattrs assemblyfile |
Specifica la necessità di assegnare agli assembly uniti gli stessi attributi di assembly dell'assembly specificato. Se l'oggetto assemblyFile non è specificato, viene utilizzato l'assembly App_Code anche se l'assembly di primo livello App_Code.dll non è incluso nell'output unito. In presenza di un attributo incoerente tra un assembly da unire e l'assembly assemblyFile, viene generato un errore. Utilizzare l'opzione a per ignorare il controllo di coerenza degli attributi oppure utilizzare l'opzione allowattrs per specificare l'attributo da escludere dal controllo. Per gli attributi esclusi dal controllo di coerenza, vedere la descrizione dell'opzione allowattrs in un altro punto della tabella. |
||
-debug |
Specifica che l'output di debug deve essere mantenuto nell'assembly unito. |
||
-nologo |
Non visualizza le informazioni sul copyright. |
||
-errorstack |
Specifica che lo strumento deve includere informazioni sull'analisi dello stack se la compilazione dell'applicazione non riesce. |
||
-r |
Rimuove i file con estensione compiled per l'assembly del codice principale (contenuto nella cartella App_Code). Non utilizzare questa opzione se l'applicazione contiene un riferimento di tipo esplicito all'assembly del codice principale. |
||
-xmldocs |
Unisce i file di documentazione XML associati agli assembly di input. Nella cartella Bin del sito unito viene incluso un file XML. |
||
-a |
Forza lo strumento di unione a unire assembly con attributi incoerenti o nei quali l'oggetto AllowPartiallyTrustedCallersAttribute può non essere stato applicato. L'oggetto AllowPartiallyTrustedCallersAttribute consente l'accesso a un assembly da parte di chiamanti parzialmente attendibili e viene specificato in fase di compilazione dallo strumento per la compilazione.
|
||
-log logfile |
Scrive i messaggi nel file specificato. |
||
-allowattrs textfile |
Specifica un file contenente gli attributi da escludere dal controllo effettuato dallo strumento sulla coerenza degli attributi negli assembly uniti. Ogni riga del file può rappresentare il nome completo di un attributo o uno spazio dei nomi completo. Tutti gli attributi rilevati all'interno dell'eventuale spazio dei nomi specificato verranno esclusi. Ciascun attributo o spazio dei nomi deve trovarsi in una riga separata. Alcuni attributi non devono necessariamente essere specificati in modo esplicito. Quando rileva gli attributi indicati di seguito, lo strumento di unione genera un avviso e quindi continua l'elaborazione. |
||
-? |
Visualizza la sintassi e le opzioni dei comandi dello strumento. |
.gif "Nota importante")
Nota importante:Note
Le applicazioni Web ASP.NET possono essere compilate sul posto o essere precompilate per la distribuzione in un percorso di destinazione, ad esempio un server di produzione. La compilazione di un'applicazione sul posto è denominata compilazione dinamica ed è utile in scenari di sviluppo rapido. La precompilazione di un'applicazione per la distribuzione può essere eseguita in due modi:
Compilazione e rimozione di tutti i file di origine, ad esempio file code-behind e file di markup.
Compilazione e mantenimento dei file di markup in modo che sia possibile aggiornarli.
Lo strumento di unione di ASP.NET offre una maggiore flessibilità in fase di precompilazione di siti Web rispetto al solo strumento per la compilazione di ASP.NET.
Lo strumento di unione di ASP.NET produce assembly mediante l'unione dell'output dello strumento per la compilazione di ASP.NET. Gli assembly uniti contribuiscono a migliorare la gestione del rilascio e la distribuzione per i siti Web di grandi dimensioni. È possibile utilizzare lo strumento di unione di ASP.NET in tre modi:
Unione di tutti gli output in un unico assembly.
Unione del contenuto dell'interfaccia utente Web (pagine Web, interfacce e così via) di ciascuna cartella nel relativo assembly.
Unione di tutto il contenuto dell'interfaccia utente Web del sito in un unico assembly.
Nelle sezioni seguenti vengono descritti i due scenari. Per esempi relativi all'utilizzo dello strumento di unione di ASP.NET, vedere Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command sul sito Web MSDN (informazioni in lingua inglese).
Lo strumento di unione di ASP.NET è incluso in Visual Studio 2005 Web Deployment Projects (informazioni in lingua inglese), un componente aggiuntivo di Visual Studio che consente di gestire le configurazioni della build, di specificare attività di pre-compilazione e post-compilazione e di unire assembly. Per ulteriori informazioni, vedere Using Web Deployment Projects with Visual Studio 2005 (informazioni in lingua inglese).
Gruppi di assembly
Lo strumento per la compilazione crea gli assembly in modo diverso a seconda del tipo di cartelle e file di origine. L'output dello strumento per la compilazione può essere classificato in due gruppi di assembly che vengono uniti in modo diverso dallo strumento di unione.
I due gruppi di assembly sono:
Assembly di contenuto dell'interfaccia utente Web generati da file di dati dell'interfaccia utente Web, ad esempio i file con estensione aspx, ascx, master, ashx, skin e file resx locali (nella cartella App_LocalResources). Il modo in cui tali assembly vengono uniti varia a seconda che il sito precompilato sia o meno aggiornabile, caratteristica determinata dall'opzione u dello strumento per la compilazione. Se un sito compilato è aggiornabile, è possibile aggiornare il contenuto dell'interfaccia utente senza dover ricompilare il sito. I file di dati di un sito Web aggiornabile rimangono nelle rispettive cartelle originali e vengono uniti soltanto i file di codice associati. Se il sito non è aggiornabile, file di dati con estensione ascx, master e skin vengono rimossi dalle cartelle originali. I file ASP.NET con estensione aspx vengono sostituiti con un file indicatore privo di contenuto. In questo caso il codice e il contenuto dell'interfaccia utente vengono uniti.
Assembly di primo livello, vale a dire assembly generati da cartelle dell'applicazione quali App_Code, App_GlobalResources o App_WebReferences. Gli assembly di primo livello vengono inoltre generati per file speciali, ad esempio Global.asax. Gli assembly di primo livello vengono sempre compilati nella cartella Bin del sito di distribuzione. Il sito di distribuzione finale non disporrà di una cartella App_Code, App_GlobalResources o App_WebReferences o di un file Global.asax, ma avrà a disposizione uno o più assembly nella directory Bin a seconda delle opzioni utilizzate con lo strumento di unione. Vengono sempre compilate anche le cartelle definite dall'utente, con la differenza che il sito di distribuzione finale mantiene la cartella definita dall'utente quando questa contiene file di dati dell'interfaccia utente. Per ulteriori informazioni sulle cartelle riservate, vedere Layout del sito Web ASP.NET.
Il contenuto statico, costituito ad esempio da file con estensione css, gif, htm, html, jpg o js, viene lasciato nelle posizioni originali nella struttura di directory precompilata senza essere modificato dallo strumento di unione.
Scenari di compilazione e di unione
ASP.NET 2.0 consente di utilizzare una combinazione di precompilazione mediante lo strumento per la compilazione, unione mediante lo strumento di unione e compilazione dinamica, allo scopo di soddisfare gli obiettivi di distribuzione e gestione del rilascio dell'utente. Nella tabella riportata di seguito vengono elencati diversi scenari di compilazione ed evidenziati i casi in cui utilizzare lo strumento di unione.
Scenario |
Note |
|---|---|
Compilazione dinamica (nessuna precompilazione) |
La compilazione dinamica è utile negli scenari di sviluppo rapidi. Visual Studio utlizza la compilazione dinamica. Premendo il tasto F5 o la combinazione di tasti CTRL+F5, viene compilata in modo dinamico soltanto la pagina sulla quale si sta lavorando con le relative dipendenze. In questo modo è possibile evitare la compilazione di un intero sito Web. Per ulteriori informazioni, vedere Informazioni sulla compilazione dinamica ASP.NET. |
Utilizzo della funzionalità di precompilazione per creare un unico assembly per ciascun file di dati dell'interfaccia utente Web utilizzando Aspnet_compiler.exe con l'opzione fixednames. |
Quando si esegue la precompilazione utilizzando l'opzione fixednames, è possibile effettuare aggiornamenti incrementali delle unità, fino alle singole pagine, e ridistribuire soltanto le pagine modificate. L'utilizzo dell'opzione u con l'opzione fixednames consente di creare siti precompilati aggiornabili e non aggiornabili. L'opzione fixednames non influisce sul modo in cui gli assembly vengono uniti in un secondo momento mediante lo strumento di unione. Per i siti di grandi dimensioni, il gran numero di assembly creati dall'opzione fixednames può provocare problemi in termini di distribuzione o di gestione del rilascio. Per ulteriori informazioni, vedere la classe Strumento per la compilazione di ASP.NET (Aspnet_compiler.exe). |
Utilizzo della funzionalità di unione per creare un assembly per ciascuna cartella dati dell'interfaccia utente Web utilizzando Aspnet_merge.exe con l'opzione prefix. |
In questo scenario è possibile controllare gli assembly a livello di cartella dati dell'interfaccia utente. La situazione presentata in questo scenario è simile a quella che si ottiene omettendo l'opzione fixenames quando si utilizza lo strumento per la compilazione. La differenza sta nel fatto che lo strumento di unione garantisce un maggiore controllo sui nomi degli assembly finali derivati dalla cartella radice e dalle cartelle dati definite dall'utente. L'operazione non ha alcun effetto sugli assembly di primo livello e sul contenuto statico. In questo scenario, se un file di una cartella viene modificato è necessario ridistribuire sia l'assembly della cartella sia la pagina modificata. È possibile unire siti precompilati aggiornabili e non aggiornabili utilizzando l'opzione prefix. Quello appena descritto è lo scenario predefinito nel caso in cui lo strumento di unione viene eseguito senza opzioni. |
Utilizzo della funzionalità di unione per creare un unico assembly per tutti i file di dati dell'interfaccia utente Web utilizzando Aspnet_merge.exe con l'opzione w. |
In questo scenario, tutto il contenuto dell'interfaccia utente viene unito in un unico assembly con il nome specificato dall'utente nel parametro assemblyname. In questo modo è possibile ridurre il numero complessivo di assembly nel sito finale distribuito. In caso di modifica di un qualsiasi file di dati, tuttavia, l'assembly del contenuto dell'interfaccia utente dovrà essere ridistribuito. L'operazione non ha alcun effetto sugli assembly di primo livello e sul contenuto statico. |
Utilizzo della funzionalità di unione per creare un unico assembly per l'intero sito Web utilizzando Aspnet_merge.exe con l'opzione o. |
In questo scenario, il sito finale distribuito contiene un solo assembly con il nome specificato dall'utente nel parametro assemblyname. La presenza di un unico assembly semplifica la distribuzione del sito. In questo modo, tuttavia, la modifica di qualsiasi contenuto del sito comporta la necessità di ricreare e ridistribuire l'assembly del sito. L'operazione ha effetto sugli assembly di primo livello (App_Code, App_GlobalResources e App_WebReferences), in quanto inclusi nell'unico assembly, ma non ha effetto sul contenuto statico. |
Unione di applicazioni per la distribuzione
Per unire gli assembly di un sito Web, eseguire lo strumento di unione e specificare il percorso del sito precompilato mediante il parametro applicationPath. Lo strumento di unione di ASP.NET unisce un sito precompilato sul posto. Vale a dire che non crea una nuova copia unita del sito precompilato. Il parametro applicationPath può rappresentare il percorso finale dell'applicazione Web. In alternativa, l'applicazione compilata può essere ulteriormente distribuita, ad esempio mediante la copia della directory.
Nell'unione di un sito precompilato, lo strumento di unione mantiene il percorso dei file dinamici man mano che vengono visualizzati nel passaggio precompilato. L'unica modifica apportata dallo strumento di unione al contenuto dei file dinamici riguarda le direttive @ Page, @ Control e @ Master. Lo strumento fa in modo che i file con tali direttive ereditino dall'assembly unito corretto nella cartella Bin. Per informazioni dettagliate sul trattamento dei tipi di file da parte dello strumento per la compilazione, vedere la sezione Osservazioni di Strumento per la compilazione di ASP.NET (Aspnet_compiler.exe)
Per gli assembly derivati dalle cartelle definite dall'utente (compresa la cartella radice del sito), alcune opzioni di unione possono creare nomi diversi da quelli visualizzati nel sito precompilato. Nella tabella riportata di seguito vengono elencati, ad esempio, i nomi degli assembly uniti ottenuti utilizzando lo strumento di unione senza alcuna opzione. Il nome assembly di ciascuna cartella definita dall'utente è App_Web_nnnn.dll, in cui nnnn è un valore hash generato internamente.
Cartella del sito precompilato |
Nome dell'assembly unito senza l'uso di opzioni di Aspnet_merge.exe |
|---|---|
\ |
Root.dll |
Admin |
Admin.dll |
Nella tabella riportata di seguito vengono elencati i nomi degli assembly uniti ottenuti utilizzando l'opzione prefix e il parametro NewName.
Cartella del sito precompilato |
Nome dell'assembly unito utilizzando l'opzione prefisso di Aspnet_merge.exe |
|---|---|
\ |
NewName.dll |
Admin |
NewName.Admin.dll |
I temi vengono trattati in modo diverso in un sito unito non aggiornabile. Nel sito precompilato non unito è presente un assembly separato per ciascun tema. Ogni assembly è denominato App_Theme_NomeTema.dll. Nel sito unito è presente un solo assembly denominato Theme.dll. Se il sito precompilato è aggiornabile, la cartella Bin unita non contiene assembly basati su temi.
Risoluzione dei problemi relativi al processo di unione
Durante la compilazione o l'unione di un sito Web, il percorso di un assembly può superare la lunghezza massima consentita per un percorso di file in Microsoft Windows. In tal caso, la richiesta di una risorsa all'assembly unito genera un errore HttpException che indica l'impossibilità di richiedere la risorsa poiché non è stata precompilata.
La lunghezza massima consentita per un percorso di file in Microsoft Windows è di 260 caratteri. Se il percorso di un assembly supera tale limite è necessario abbreviare il percorso del sito Web o delle sue sottocartelle. Potrebbe anche essere necessario disattivare la creazione di copie shadow nel file Web.config utilizzando la proprietà ShadowCopyBinAssemblies dell'elemento hostingEnvironment. Per ulteriori informazioni sui nomi file, vedere Naming a File sul sito Web MSDN (informazioni in lingua inglese).
Se si utilizza lo strumento di unione con l'opzione o per creare un unico assembly per il sito, in presenza di riferimenti circolari creati dal processo di unione viene generato un errore. La situazione ammette due soluzioni alternative:
Utilizzare in alternativa l'opzione w, in modo che il file di origine contenente i riferimenti circolari rimanga un riferimento esterno e non venga unito.
Separare i controlli coinvolti in un riferimento circolare in directory diverse.
Per garantire la riuscita dell'operazione di unione di assembly con attributi incoerenti, attenersi alle linee guida riportate di seguito:
Elencare gli attributi incoerenti utilizzando l'opzione allowattrs.
Utilizzare le opzioni copyattrs e verificare che tutti gli assembly da unire dispongano di attributi corrispondenti.
Utilizzare l'opzione a.
Firma di assembly
Le opzioni delaysign e keyfile consentono di utilizzare lo strumento di unione per creare assembly con nome sicuro senza ricorrere allo strumento Nome sicuro (Sn.exe). L'opzione delaysign corrisponde all'attributo AssemblyDelaySignAttribute, mentre l'opzione keyfile corrisponde all'attributo AssemblyKeyFileAttribute.
Ciascuna opzione applica l'attributo corrispondente all'assembly unito. Gli attributi applicati vengono contrassegnati con un attributo AttributeUsageAttribute la cui proprietà AllowMultiple è impostata su false. Se, pertanto, si utilizzano tali opzioni nell'unione di assembly già contrassegnati con uno degli attributi, il processo di unione non riesce.
Esempi
Mediante il seguente comando gli assembly del sito precompilato vengono uniti nella directory C:\PrecompiledSite.
Aspnet_merge C:\PrecompiledSite
Mediante il seguente comando gli assembly di un sito precompilato vengono uniti nella directory C:\PrecompiledSite e gli assembly uniti vengono firmati utilizzando il file KeyFile.snk. Il sito unito avrà un assembly per ciascuna cartella del sito precompilato.
Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk
Mediante il seguente comando tutti gli assembly del sito precompilato nella directory C:\PrecompiledSite vengono uniti in un unico assembly, denominato MyApp.dll. Il sito unito avrà un solo assembly per tutto il contenuto dell'interfaccia utente del sito Web.
Aspnet_merge C:\PrecompiledSite -w MyApp.dll
Mediante il seguente comando tutti gli assembly del sito precompilato nella directory C:\PrecompiledSite vengono uniti in un unico assembly, denominato MyApp.dll.
Aspnet_merge C:\PrecompiledSite -o MyApp.dll
Vedere anche
Concetti
Ritardo della firma di un assembly
Riferimenti
AllowPartiallyTrustedCallersAttribute
Strumento Nome sicuro (Sn.exe)
Strumento per la compilazione di ASP.NET (Aspnet_compiler.exe)