Outil Resource File Generator Tool (Resgen.exe)
Mise à jour : novembre 2007
L'outil Resource File Generator Tool (Générateur de fichiers de ressources) convertit les fichiers texte (.txt ou .restext) et les fichiers de format de ressource XML (.resx) en fichiers binaires Common Language Runtime (.resources) pouvant être incorporés dans un exécutable binaire runtime ou compilés en assemblys satellites. Pour plus d'informations sur le déploiement et la récupération des fichiers .resources, consultez Ressources dans les applications.
Resgen.exe effectue les conversions suivantes :
il convertit les fichiers .txt ou .restext en fichiers .resources ou .resx.
.gif "Remarque")
Remarque :L'extension .restext a été introduite dans .NET Framework version 2.0. Le format des fichiers .restext est identique à celui des fichiers .txt. Toutefois, l'extension .restext vous aide à identifier plus facilement les fichiers texte qui contiennent des définitions de ressource.
il convertit les fichiers .resources en fichiers .txt ou .resx ;
il convertit les fichiers .resx en fichiers .txt ou .resources.
resgen [parameters] [/compile]filename.extension [outputFilename.extension] [/str:lang[,namespace[,class[,file]]]]
Paramètres
Argument |
Description |
|---|---|
filename.extension |
Nom du fichier d'entrée à convertir. L'extension doit être l'une des suivantes :
|
outputFilename.extension |
Le nom du fichier de ressources à créer. Cet argument est facultatif lors de la conversion d'un fichier .txt, .restext ou .resx. Vous pouvez spécifier l'extension .resources lors de la conversion d'un fichier .txt ou .resx en fichier .resources. Si vous ne spécifiez pas de valeur pour outputFilenameResgen.exe ajoute une extension .resources à l'argument filename d'entrée et écrit le fichier dans le répertoire qui contient filename. L'argument outputFilename est obligatoire lors d'une conversion à partir d'un fichier .resources. Spécifiez l'extension .resx lors de la conversion d'un fichier .resources en fichier de ressources XML. Spécifiez l'extension .txt ou .restext lors de la conversion d'un fichier .resources en fichier texte. Vous devez uniquement convertir un fichier .resources en fichier .txt lorsque le fichier .resources ne comporte que des valeurs de chaînes. |
Option |
Description |
||
|---|---|---|---|
/compile |
Permet de spécifier plusieurs fichiers .resx ou texte à convertir en plusieurs fichiers .resources en une seule opération globale. Si vous omettez cette option, vous ne pouvez spécifier qu'un seul argument de fichier d'entrée. Cette option ne peut pas être utilisée avec l'option /str:. |
||
/publicClass |
Crée un type de ressources fortement typé comme classe public. Cette option est ignorée si l'option /str: n'est pas utilisée. |
||
/r:assembly |
Spécifie que les types doivent être chargés à partir d'un assembly. Si vous spécifiez cette option, un fichier .resx avec une version antérieure d'un type utilisera le type dans un assembly. |
||
/str:language[,namespace[,classname[,filename]]] |
Crée un fichier de classe de ressources fortement typé dans le langage de programmation (cs ou C# pour C#, vb ou visualbasic pour Visual Basic) spécifié dans l'option language. Vous pouvez utiliser l'option namespace pour spécifier l'espace de noms par défaut du projet, l'option classname pour spécifier le nom de la classe générée et l'option filename pour spécifier le nom du fichier de classe.
Un seul fichier d'entrée est autorisé lorsque l'option /str: est utilisée, afin qu'il ne puisse pas être utilisé avec l'option /compile. Si namespace est spécifié mais que classname ne l'est pas, le nom de classe est dérivé du nom de fichier de sortie (par exemple, les traits de soulignement sont substitués pour les périodes). Les ressources fortement typées peuvent ne pas fonctionner correctement en conséquence. Pour éviter ce problème, spécifiez à la fois le nom de classe et le nom du fichier de sortie. |
||
/usesourcepath |
Précise que le répertoire actif du fichier d'entrée sera utilisé pour résoudre des chemins d'accès de fichier relatif. |
Notes
Resgen.exe convertit les fichiers en encapsulant les méthodes implémentées par les quatre classes suivantes :
La classe ResourceReader lit un fichier .resources.
La classe ResourceWriter crée un fichier .resources à partir de ressources spécifiées.
La classe ResXResourceReader lit un fichier .resx.
La classe ResXResourceWriter crée un fichier .resx à partir de ressources spécifiées.
Notez qu'un fichier .resx créé par la classe ResXResourceWriter ne peut pas être directement utilisé par une application .NET Framework. Avant d'ajouter ce fichier à votre application, exécutez-le via Resgen.exe pour le convertir en fichier .resources. Pour plus d'informations sur l'implémentation de ces classes dans votre code, consultez leurs rubriques de référence respectives.
Pour que Resgen.exe puisse analyser votre entrée, il est primordial que vos fichiers texte et .resx suivent le format correct.
Les fichiers texte (.txt ou .restext) ne peuvent contenir que des ressources chaîne. Les ressources de type chaîne s'avèrent utiles lorsque vous écrivez une application dont les chaînes doivent être traduites en plusieurs langues. Vous pouvez, par exemple, régionaliser les chaînes de menus à l'aide de la ressource de type chaîne appropriée. Resgen.exe lit les fichiers texte comportant les paires nom/valeur, où le nom est une chaîne décrivant la ressource et la valeur la chaîne de ressource elle-même. Vous devez spécifier chaque paire nom/valeur sur une ligne distincte, de la façon suivante :
name=value
Notez que les chaînes vides sont autorisées dans les fichiers texte. Par exemple :
EmptyString=
Un fichier texte doit être enregistré avec le codage UTF-8 ou Unicode, à moins qu'il ne contienne uniquement des caractères de l'alphabet romain ordinaire, sans signe diacritique tels que la cédille, le tréma et le tilde. Par exemple, Resgen.exe supprime les caractères ANSI étendus lorsqu'il traite un fichier texte qui n'a pas de codage UTF-8 ou Unicode.
Resgen.exe recherche d'éventuels doublons de noms de ressources dans le fichier texte. Si le fichier texte contient des noms de ressources en double, Resgen.exe émet un avertissement et ignore les noms en double. Pour plus d'informations sur le format de fichier texte, consultez Ressources dans un fichier au format texte.
Les fichiers de ressources au format .resx contiennent des entrées XML. Vous pouvez spécifier des ressources de chaîne dans ces entrées XML, comme dans les fichiers texte. Le principal avantage des fichiers .resx par rapport aux fichiers texte est que vous pouvez aussi spécifier ou incorporer des objets. Lorsque vous affichez un fichier .resx, vous pouvez en fait consulter la forme binaire d'un objet incorporé (une image, par exemple) si ces informations binaires sont intégrées au manifeste des ressources. Vous pouvez ouvrir un fichier .resx comme un fichier texte avec un éditeur de texte (tel que le Bloc-notes ou Microsoft Word) et écrire, analyser et manipuler son contenu. Notez que pour y parvenir, une bonne connaissance des balises XML et de la structure des fichiers .resx s'avère nécessaire. Pour plus d'informations sur le format de fichier .resx, consultez Ressources dans un fichier au format .Resx.
Pour créer un fichier .resources comportant des objets sans chaînes incorporés, vous devez utiliser Resgen.exe pour convertir un fichier .resx contenant des objets ou pour ajouter les ressources des objets à votre fichier directement à partir du code, à l'aide des méthodes fournies par la classe ResourceWriter Si vous utilisez Resgen.exe pour convertir un fichier .resources contenant des objets en fichier texte, toutes les ressources de type chaîne seront converties correctement, mais les types de données des objets sans chaînes seront également écrits dans le fichier sous forme de chaînes. Vous perdrez alors les objets incorporés au cours de la conversion et Resgen.exe signalera qu'une erreur s'est produite lors de la récupération des ressources.
La version 2.0 du .NET Framework prend en charge des ressources fortement typées. La prise en charge de ressources fortement typées encapsule l'accès aux ressources en créant des classes qui contiennent un jeu de propriétés en lecture seule (get) statiques, proposant ainsi un moyen de consommer des ressources autres que l'utilisation directe des méthodes de la classe ResourceManager. Les fonctionnalités de base sont fournies par l'option de ligne de commande /str dans Resgen.exe, qui encapsule les fonctionnalités de la classe StronglyTypedResourceBuilder. Lorsque vous spécifiez l'option /str, la sortie de Resgen.exe est une classe qui contient des propriétés fortement typées qui correspondent aux ressources qui sont référencées dans le paramètre d'entrée. Cette classe propose un accès en lecture seule fortement typé aux ressources qui sont disponibles dans le fichier traité.
L'Outil Resource File Generator Tool (Resgen.exe) vous permet de créer des fichiers .resources ainsi que des wrappers fortement typés pour accéder à ces fichiers .resources. Lorsque vous créez un wrapper fortement typé, le nom de votre fichier .resources doit correspondre à l'espace de noms et au nom de classe (par exemple, MyNamespace.MyClass.resources) du code généré. Toutefois, l'Outil Resource File Generator Tool (Resgen.exe) vous permet de spécifier des options qui produisent un fichier .resources avec un nom incompatible. Pour contourner ce problème, renommez les fichiers de sortie nommés de manière incompatible après que l'Outil Resource File Generator Tool (Resgen.exe) les a générés.
Une fois la création des fichiers .resources à l'aide de Resgen.exe terminée, utilisez l'outil Assembly Linker (Al.exe) soit pour incorporer les ressources à un exécutable binaire runtime, soit pour les compiler dans des assemblys satellites.
| Remarque : |
|---|
Si Resgen.exe échoue pour une raison quelconque, la valeur de retour est -1. |
| Remarque : |
|---|
Resgen.exe n'accepte pas un nom de fichier .resx qui contient des espaces lors de la génération d'une classe de ressource fortement typée. Il remplace tous les caractères non valides par un trait de soulignement (« _ »). Pour plus d'informations, consultez VerifyResourceName. |
Exemples
La commande suivante affiche, sans aucune option spécifiée, la syntaxe de commande et les options de Resgen.exe.
resgen
La commande suivante lit les paires nom/valeur dans myResources.txt et crée un fichier de ressources binaire nommé myResources.resources. . Le nom du fichier de sortie n'étant pas spécifié explicitement, il reçoit par défaut le même nom que le fichier d'entrée.
resgen myResources.txt
La commande suivante lit les paires nom/valeur contenues dans myResources.restext et crée un fichier de ressources binaire nommé yourResources.resources.
resgen myResources.restext yourResources.resources
La commande suivante lit un fichier d'entrée XML appelé myResources.resx et crée un fichier de ressources binaire nommé myResources.resources.
resgen myResources.resx myResources.resources
La commande suivante lit le fichier de ressources binaire myResources.resources et écrit un fichier de sortie XML nommé myResources.resx.
resgen myResources.resources myResources.resx
Les commandes suivantes lisent un fichier d'entrée XML nommé myResources.resx et écrivent des fichiers texte nommés myResources.txt et myResources.restext, respectivement. Notez que si le fichier .resx comporte des objets incorporés, ceux-ci ne seront pas correctement convertis dans les fichiers texte.
resgen myResources.resx myResources.txt
resgen myResources.resx myResources.restext
La commande suivante lit un fichier d'entrée XML appelé myResources.resx et crée un fichier de ressources binaire nommé myResources.resources. Elle génère également un fichier Visual Basic nommé MyFile.vb avec une classe nommée MyClass qui contient des propriétés fortement typées qui correspondent aux ressources référencées dans le fichier d'entrée. La classe MyClass est contenue dans un espace de noms nommé Namespace1.
resgen myResources.resx myResources.resources /str:C#,Namespace1,MyClass,MyFile.cs
Voir aussi
Concepts
Ressources dans les applications
Référence
Invite de commandes du Kit de développement SDK