Generatore di file di risorse (Resgen.exe)
Aggiornamento: novembre 2007
Il generatore di file di risorse consente di convertire i file di testo (TXT o RESTEXT) e i file RESX (formato di risorsa basato su XML) in file RESOURCES binari di Common Language Runtime incorporabili in un eseguibile binario di runtime o compilabili in assembly satellite. Per informazioni sulla distribuzione e il recupero di file RESOURCES, vedere Risorse nelle applicazioni.
Resgen.exe esegue le seguenti conversioni:
Converte i file TXT o RESTEXT in file RESOURCES o RESX.
Nota
L'estensione RESTEXT è stata introdotta in .NET Framework versione 2.0. Il formato dei file RESTEXT è identico a quello dei file TXT. L'estensione RESTEXT consente però di identificare più facilmente i file di testo che contengono definizioni di risorse.
Converte i file RESOURCES in file di testo o RESX.
Converte i file RESX in file di testo o RESOURCES.
resgen [parameters] [/compile]filename.extension [outputFilename.extension] [/str:lang[,namespace[,class[,file]]]]
Parametri
Argomento |
Descrizione |
|---|---|
filename.extension |
Nome del file di input da convertire. extension deve costituito da uno dei seguenti elementi:
|
outputFilename.extension |
Nome del file di risorse da creare. Questo argomento è facoltativo quando si converte un file TXT, RESTEXT o RESX. È possibile specificare l'estensione RESOURCES quando si converte un file di testo o RESX nel formato RESOURCES. Se non si specifica alcun argomento outputFilename, verrà aggiunta automaticamente l'estensione RESOURCES all'argomento filenamedi input e il file verrà scritto nella directory contenente filename. L'argomento outputFilename è obbligatorio quando si esegue la conversione da un file RESOURCES. Specificare l'estensione RESX quando si converte un file RESOURCES in un file di risorse basato su XML. Specificare l'estensione TXT o RESTEXT quando si converte un file RESOURCES in un file di testo. È consigliabile convertire un file RESOURCES in un file TXT solo quando il file RESOURCES contiene unicamente valori di tipo stringa. |
Opzione |
Descrizione |
|---|---|
/compile |
Consente di specificare più file di testo o RESX da convertire in più file RESOURCES con una singola operazione di massa. Se non si specifica questa opzione, sarà possibile specificare un solo argomento di file di input. Non è possibile utilizzare questa opzione con l'opzione /str:. |
/publicClass |
Crea una classe di risorse fortemente tipizzata come classe pubblica. Questa opzione viene ignorata se non si utilizza l'opzione /str:. |
/r:assembly |
Specifica che i tipi devono essere caricati da assembly. Se si specifica questa opzione, un file RESX con una versione precedente di un tipo utilizzerà il tipo contenuto in assembly. |
/str:language[,namespace[,classname[,filename]]] |
Crea un file della classe di risorse fortemente tipizzate nel linguaggio di programmazione (cs o C# per C#, vb o visualbasic per Visual Basic) specificato nell'opzione language. È possibile utilizzare l'opzione namespace per specificare lo spazio dei nomi predefinito del progetto, l'opzione classname per specificare il nome della classe generata e l'opzione filename per specificare il nome del file di classe. Nota In .NET Framework versione 2.0 classname e filename vengono ignorati, se namespace non viene specificato. Viene accettato un solo file di input quando si utilizza l'opzione /str:, in modo che non possa essere utilizzato con l'opzione /compile. Se è specificata l'opzione namespace, ma non l'opzione classname, il nome della classe deriva dal nome del file di output, ad esempio le sottolineature vengono sostituite da punti. Di conseguenza è possibile che le risorse fortemente tipizzate non funzionino correttamente. Per ovviare a questo problema, specificare sia il nome della classe che il nome del file di output. |
/usesourcepath |
Specifica che occorre utilizzare la directory corrente del file di input per risolvere i percorsi di file relativi. |
Note
Resgen.exe converte i file eseguendo il wrapping dei metodi implementati dalle seguenti quattro classi:
ResourceReader Class: consente di leggere un file RESOURCES.
Classe ResourceWriter: consente di creare un file RESOURCES da risorse specificate.
Classe ResXResourceReader: consente di leggere un file RESX.
Classe ResXResourceWriter: consente di creare un file RESX da risorse specificate.
Un file RESX creato dalla classe ResXResourceWriter non può essere utilizzato direttamente da un'applicazione .NET Framework. Prima di aggiungere questo file all'applicazione, convertirlo tramite Resgen.exe in un file RESOURCES. Per ulteriori informazioni sull'implementazione di queste classi nel codice, vedere gli argomenti di riferimento relativi a ciascuna classe.
Perché Resgen.exe possa analizzare l'input, è importante che i file di testo e RESX seguano il formato corretto.
I file di testo (TXT o RESTEXT) possono contenere solo risorse di tipo stringa. Le risorse di tipo stringa sono utili se si scrive un'applicazione contenente stringhe che dovranno essere tradotte in varie lingue. È ad esempio possibile localizzare facilmente le stringhe dei menu utilizzando la risorsa di tipo stringa appropriata. Resgen.exe legge file di testo contenenti coppie nome/valore, dove il nome è una stringa che descrive la risorsa e il valore è la stringa della risorsa stessa. È necessario specificare ciascuna coppia nome/valore su una riga separata, come segue:
name=value
Le stringhe vuote sono consentite nei file di testo. Esempio:
EmptyString=
Un file di testo deve essere salvato con codifica UTF-8 o Unicode, a meno che non contenga solo caratteri dell'alfabeto latino semplice, senza contrassegni diacritici, ad esempio la cediglia, la dieresi e la tilde. Resgen.exe ad esempio rimuove i caratteri ANSI estesi quando elabora un file di testo senza codifica UTF-8 o Unicode.
Resgen.exe controlla che il file di testo non contenga nomi di risorsa doppi. Se il file di testo contiene nomi di risorsa duplicati, verrà generato un avviso e i nomi duplicati verranno ignorati. Per ulteriori informazioni sul formato dei file di testo, vedere Risorse in formato di file di testo.
Il formato di file di risorse RESX è composto da voci XML. Analogamente ai file di testo,è possibile specificare risorse di tipo stringa in queste voci XML. Uno dei principali vantaggi dei file RESX rispetto ai file di testo consiste nel fatto che i file RESX consentono anche di specificare o incorporare oggetti. Quando si visualizza un file RESX, è effettivamente possibile vedere la forma binaria di un oggetto incorporato, ad esempio un'immagine, quando queste informazioni binarie fanno parte del manifesto della risorsa. Come per i file di testo, è possibile aprire un file RESX con un editor di testo quale il Blocco note o Microsoft Word e scriverne, analizzarne e manipolarne il contenuto. Tenere presente che, per eseguire questa operazione, è necessaria una buona conoscenza dei tag XML e della struttura dei file RESX. Per ulteriori informazioni sul formato dei file RESX, vedere Risorse in formato di file RESX.
Per creare un file RESOURCES contenente oggetti non stringa incorporati, è necessario convertire, mediante Resgen.exe, un file RESX contenente oggetti oppure aggiungere le risorse di tipo oggetto al file direttamente dal codice, avvalendosi dei metodi forniti dalla classe ResourceWriter. Se si utilizza Resgen.exe per convertire un file RESOURCES contenente oggetti in un file di testo, tutte le risorse di tipo stringa verranno convertite correttamente, ma i tipi di dati degli oggetti non stringa verranno a loro volta scritti nel file sotto forma di stringhe. Gli oggetti incorporati andranno quindi persi nella conversione e Resgen.exe riferirà che si è verificato un errore nel recupero delle risorse.
In .NET Framework versione 2.0 vengono supportate solo risorse fortemente tipizzate. Il supporto per questo tipo di risorse incapsula l'accesso alle risorse mediante la creazione di classi contenenti un insieme di proprietà statiche di sola lettura (di tipo get), fornendo così una modalità di impiego delle risorse alternativa all'utilizzo diretto dei metodi della classe ResourceManager. Le funzionalità di base sono fornite dall'opzione della riga di comando /str di Resgen.exe, che esegue il wrapping delle funzionalità della classe StronglyTypedResourceBuilder. Quando si specifica l'opzione /str, Resgen.exe genera una classe che contiene le proprietà fortemente tipizzate corrispondenti alle risorse a cui si fa riferimento nel parametro di input. Questa classe fornisce l'accesso fortemente tipizzato di sola lettura alle risorse disponibili nel file elaborato.
Lo strumento Generatore di file di risorse (Resgen.exe) consente di creare file .resources e wrapper fortemente tipizzati per l'accesso a questi file. Quando si crea un wrapper fortemente tipizzato, il nome del file .resources deve corrispondere a quello dello spazio dei nomi e della classe, ad esempio MyNamespace.MyClass.resources, del codice generato. Tuttavia, mediante lo strumento Generatore di file di risorse (Resgen.exe) è possibile specificare opzioni per la generazione di un file .resources con un nome incompatibile. Per ovviare a questo problema, rinominare i file di output con nome incompatibile dopo che sono stati generati dallo strumento Generatore di file di risorse (Resgen.exe).
Dopo aver completato la creazione di file RESOURCES con Resgen.exe, utilizzare Assembly Linker (Al.exe) per incorporare le risorse in un eseguibile binario di runtime o compilarle in assembly satellite.
Nota
Se per qualsiasi motivo l'operazione ha esito negativo, il valore restituito sarà –1.
Nota
Resgen.exe non accetta un nome di file RESX contenente spazi durante la generazione di una classe di risorse fortemente tipizzata. Tutti i caratteri non validi vengono sostituiti con caratteri di sottolineatura ("_"). Per ulteriori informazioni, vedere VerifyResourceName.
Esempi
Il comando riportato di seguito, in cui non è specificata alcuna opzione, consente di visualizzare la sintassi del comando e le opzioni di Resgen.exe.
resgen
Il comando riportato di seguito consente di leggere coppie nome/valore in myResources.txt e scrive un file di risorse binario denominato myResources.resources. Poiché non viene specificato in modo esplicito, il nome del file di output corrisponde per impostazione predefinita a quello del file di input.
resgen myResources.txt
Il seguente comando legge coppie nome/valore in myResources.restext e scrive un file di risorse binarie denominato yourResources.resources.
resgen myResources.restext yourResources.resources
Il comando riportato di seguito consente di leggere il file di input basato su XML myResources.resx e scrivere un file di risorse binario denominato myResources.resources.
resgen myResources.resx myResources.resources
Il comando riportato di seguito consente di leggere il file di risorse binario myResources.resources e scrivere un file di output basato su XML denominato myResources.resx.
resgen myResources.resources myResources.resx
I comandi riportati di seguito consentono di leggere un file di input basato su XML denominato myResources.resx e scrivere i file di testo denominati rispettivamente myResources.txt e myResources.restext. Tenere presente che, se il file RESX contiene oggetti incorporati, questi ultimi non verranno convertiti correttamente nei file di testo.
resgen myResources.resx myResources.txt
resgen myResources.resx myResources.restext
Il comando riportato di seguito consente di leggere il file di input basato su XML myResources.resx e scrivere un file di risorse binario denominato myResources.resources. Viene inoltre generato un file Visual Basic denominato MyFile.vb con una classe MyClass in cui sono contenute le proprietà fortemente tipizzate corrispondenti alle risorse a cui si fa riferimento nel file di input. La classe MyClass è contenuta nello spazio dei nomi Namespace1.
resgen myResources.resx myResources.resources /str:C#,Namespace1,MyClass,MyFile.cs