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

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. Nota importante: Quando si utilizza l'opzione a, gli assembly uniti non contrassegnati in precedenza come assembly che accettano chiamanti parzialmente attendibili vengono contrassegnati con AllowPartiallyTrustedCallersAttribute. È quindi possibile che l'assembly venga chiamato da codice parzialmente attendibile.
-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. System.CodeDom.Compiler.GeneratedCodeAttribute System.Runtime.CompilerServices.CompilationRelaxationsAttribute System.Runtime.CompilerServices.RuntimeCompatibilityAttribute System.Diagnostics.DebuggableAttribute Microsoft.JScript.ReferenceAttribute
-?	Visualizza la sintassi e le opzioni dei comandi dello strumento.

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.

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.

Nella tabella riportata di seguito vengono elencati i nomi degli assembly uniti ottenuti utilizzando l'opzione prefix e il parametro NewName.

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

Assembly con nomi sicuri

Riferimenti

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

Strumenti di .NET Framework

Strumento Nome sicuro (Sn.exe)

Strumento per la compilazione di ASP.NET (Aspnet_compiler.exe)