Resgen.exe (générateur de fichiers de ressources)

Le générateur de fichiers de ressources (Resgen.exe) convertit des fichiers texte (.txt ou .restext) et des fichiers au format de ressource XML (.resx) en fichiers binaires common language runtime (.resources) qui peuvent être incorporés dans un exécutable binaire runtime ou un assembly satellite. Pour plus d’informations, consultez Créer des fichiers de ressources.

Resgen.exe est un utilitaire de conversion de ressources à usage général qui effectue les tâches suivantes :

• Convertit les fichiers .txt ou .restext en fichiers .resources ou .resx. (Le format des fichiers .restext est identique au format des fichiers .txt. Toutefois, l’extension .restext vous permet d’identifier plus facilement les fichiers texte qui contiennent des définitions de ressources.)

• Convertit les fichiers .resources en fichiers texte ou .resx.

• Convertit les fichiers .resx en fichiers texte ou .resources.

• Extrait les ressources de chaîne d’un assembly dans un fichier .resw adapté à une utilisation dans une application Windows 8.x Store.

• Crée une classe fortement typée qui fournit l’accès aux ressources nommées individuelles et à l’instance ResourceManager .

Si Resgen.exe échoue pour une raison quelconque, la valeur de retour est -1.

Pour obtenir de l’aide sur Resgen.exe, vous pouvez utiliser la commande suivante, sans options spécifiées, pour afficher la syntaxe et les options de commande pour Resgen.exe:

resgen

Vous pouvez également utiliser le /? commutateur :

resgen /?

Si vous utilisez Resgen.exe pour générer des fichiers .resources binaires, vous pouvez utiliser un compilateur de langage pour incorporer les fichiers binaires dans des assemblys exécutables, ou utiliser l’Assembly Linker (Al.exe) pour les compiler dans des assemblys satellites.

Cet outil est installé automatiquement avec Visual Studio. Pour exécuter l’outil, utilisez l’invite de commandes développeur Visual Studio ou Visual Studio Developer PowerShell.

À l’invite de commandes, tapez ce qui suit :

Syntaxe

resgen  [-define:symbol1[,symbol2,...]] [/useSourcePath] filename.extension  | /compile filename.extension... [outputFilename.extension] [/r:assembly] [/str:lang[,namespace[,class[,file]]] [/publicclass]]

resgen filename.extension [outputDirectory]

Paramètres

Resgen.exe et types de fichiers de ressources

Pour que Resgen.exe convertir correctement des ressources, du texte et des fichiers .resx doivent suivre le format approprié.

Fichiers text (.txt et .restext)

Les fichiers text (.txt ou .restext) peuvent contenir uniquement des ressources de chaîne. Les ressources de chaîne sont utiles si vous écrivez une application qui doit avoir des chaînes traduites en plusieurs langues. Par exemple, vous pouvez facilement régionaliser les chaînes de menu à l’aide de la ressource de chaîne appropriée. Resgen.exe lit les fichiers texte qui contiennent des paires nom/valeur, où le nom est une chaîne qui décrit la ressource et la valeur est la chaîne de ressource elle-même.

Un fichier texte qui contient des ressources doit être enregistré avec l’encodage UTF-8 ou Unicode (UTF-16), sauf s’il contient uniquement des caractères dans la plage latine de base (vers U+007F). Resgen.exe supprime les caractères ANSI étendus lorsqu’il traite un fichier texte enregistré à l’aide de l’encodage ANSI.

Resgen.exe vérifie le fichier texte pour les noms de ressources en double. Si le fichier texte contient des noms de ressources en double, Resgen.exe émet un avertissement et ignore la deuxième valeur.

Fichiers .resx

Le format de fichier de ressources .resx se compose d’entrées XML. Vous pouvez spécifier des ressources de chaîne dans ces entrées XML, comme vous le feriez dans les fichiers texte. L’un des principaux avantages des fichiers .resx par rapport aux fichiers texte est que vous pouvez également spécifier ou incorporer des objets. Lorsque vous affichez un fichier .resx, vous pouvez voir la forme binaire d’un objet incorporé (par exemple, une image) lorsque ces informations binaires font partie du manifeste de ressource. Comme pour les fichiers texte, vous pouvez ouvrir un fichier .resx avec un éditeur de texte (tel que le Bloc-notes ou Microsoft Word) et écrire, analyser et manipuler son contenu. Notez que cela nécessite une bonne connaissance des balises XML et de la structure de fichiers .resx. Pour plus d’informations sur le format de fichier .resx, consultez la section « Ressources dans les fichiers .resx » de Créer des fichiers de ressources.

Pour créer un fichier .resources qui contient des objets non chaînes incorporés, vous devez utiliser Resgen.exe pour convertir un fichier .resx contenant des objets ou ajouter les ressources d’objet à votre fichier directement à partir du code en appelant les méthodes fournies par la ResourceWriter classe.

Si votre fichier .resx ou .resources contient des objets et que vous utilisez Resgen.exe pour le convertir en fichier texte, toutes les ressources de chaîne sont converties correctement, mais les types de données des objets non chaînes sont également écrits dans le fichier sous forme de chaînes. Vous perdrez les objets incorporés dans la conversion et Resgen.exe signalera qu’une erreur s’est produite lors de la récupération des ressources.

Conversion entre les types de fichiers de ressources

Lorsque vous effectuez une conversion entre différents types de fichiers de ressources, Resgen.exe peut ne pas être en mesure d’effectuer la conversion ou de perdre des informations sur des ressources spécifiques, en fonction des types de fichiers source et cible. Le tableau suivant spécifie les types de conversions qui réussissent lors de la conversion d’un type de fichier de ressources vers un autre.

*Dans les applications du Windows 8.x Store, vous utilisez des fichiers .resw pour créer des ressources. Malgré la différence d’extension de fichier, le format de fichier .resw est identique au format de fichier .resx, sauf que les fichiers .resw peuvent contenir uniquement des chaînes et des chemins d’accès de fichier. Vous pouvez convertir des fichiers .resx qui contiennent uniquement des chaînes et des chemins d’accès de fichier en fichiers .resw en modifiant simplement l’extension de fichier.

Exécution de tâches Resgen.exe spécifiques

Vous pouvez utiliser Resgen.exe de différentes façons : pour compiler un fichier de ressources basé sur du texte ou XML en fichier binaire, pour convertir entre les formats de fichier de ressources et générer une classe qui encapsule les ResourceManager fonctionnalités et fournit l’accès aux ressources. Cette section fournit des informations détaillées sur chaque tâche :

• Compilation de ressources dans un fichier binaire

• Conversion entre les types de fichiers de ressources

• Compilation ou conversion de plusieurs fichiers

• Exportation de ressources vers un fichier .resw

• Compilation conditionnelle des ressources

• Génération d’une classe de ressources fortement typée

Compilation de ressources dans un fichier binaire

L’utilisation la plus courante de Resgen.exe consiste à compiler un fichier de ressources textuel (un fichier .txt ou .restext) ou un fichier de ressources XML (un fichier .resx) dans un fichier .resources binaire. Le fichier de sortie peut ensuite être incorporé dans un assembly principal par un compilateur de langage ou dans un assembly satellite par Assembly Linker (AL.exe).

La syntaxe de compilation d’un fichier de ressources est la suivante :

resgen inputFilename [outputFilename]

où sont les paramètres :

inputFilename Nom du fichier, y compris l’extension, du fichier de ressources à compiler. Resgen.exe compile uniquement les fichiers avec des extensions de .txt, .restext ou .resx.

outputFilename Nom du fichier de sortie. Si vous omettez outputFilename, Resgen.exe crée un fichier .resources avec le nom de fichier racine du inputFilename même répertoire que inputFilename. Si outputFilename elle inclut un chemin d’accès au répertoire, le répertoire doit exister.

Vous fournissez un espace de noms complet pour le fichier .resources en le spécifiant dans le nom de fichier et en le séparant du nom de fichier racine par un point. Par exemple, si outputFilename c’est MyCompany.Libraries.Strings.resourcesle cas, l’espace de noms est MyCompany.Libraries.

La commande suivante lit les paires nom/valeur dans Resources.txt et écrit un fichier .resources binaire nommé Resources.resources. Étant donné que le nom du fichier de sortie n’est pas spécifié explicitement, il reçoit le même nom que le fichier d’entrée par défaut.

resgen Resources.txt

La commande suivante lit les paires nom/valeur dans Resources.restext et écrit un fichier de ressources binaires nommé StringResources.resources.

resgen Resources.restext StringResources.resources

La commande suivante lit un fichier d’entrée XML nommé Resources.resx et écrit un fichier .resources binaire nommé Resources.resources.

resgen Resources.resx Resources.resources

Conversion entre les types de fichiers de ressources

En plus de compiler des fichiers de ressources basés sur du texte ou XML en fichiers .resources binaires, Resgen.exe pouvez convertir n’importe quel type de fichier pris en charge en tout autre type de fichier pris en charge. Cela signifie qu’il peut effectuer les conversions suivantes :

• .txt et les fichiers .restext aux fichiers .resx.

• Fichiers .resx à .txt et .restext.

• Fichiers .resources pour .txt et les fichiers .restext.

• Fichiers .resources dans les fichiers .resx.

La syntaxe est la même que celle indiquée dans la section précédente.

En outre, vous pouvez utiliser Resgen.exe pour convertir des ressources incorporées dans un assembly .NET Framework en fichier .resw pour les applications du Windows 8.x Store.

La commande suivante lit un fichier de ressources binaires Resources.resources et écrit un fichier de sortie XML nommé Resources.resx.

resgen Resources.resources Resources.resx

La commande suivante lit un fichier de ressources textuels nommé StringResources.txt et écrit un fichier de ressources XML nommé LibraryResources.resx. En plus de contenir des ressources de chaîne, le fichier .resx peut également être utilisé pour stocker des ressources autres que des chaînes.

resgen StringResources.txt LibraryResources.resx

Les deux commandes suivantes lisent un fichier de ressources XML nommé Resources.resx et écrivent des fichiers texte nommés Resources.txt et Resources.restext. Notez que si le fichier .resx contient des objets incorporés, ils ne seront pas convertis avec précision dans les fichiers texte.

resgen Resources.resx Resources.txt
resgen Resources.resx Resources.restext

Compilation ou conversion de plusieurs fichiers

Vous pouvez utiliser le /compile commutateur pour convertir une liste de fichiers de ressources d’un format à un autre dans une seule opération. La syntaxe est la suivante :

resgen /compile filename.extension [filename.extension...]

La commande suivante compile trois fichiers, StringResources.txt, TableResources.resw et ImageResources.resw, en fichiers .resources distincts nommés StringResources.resources, TableResources.resources et ImageResources.resources.

resgen /compile StringResources.txt TableResources.resx ImageResources.resx

Exportation de ressources vers un fichier .resw

Si vous développez une application Windows 8.x Store, vous pouvez utiliser des ressources à partir d’une application de bureau existante. Toutefois, les deux types d’applications prennent en charge différents formats de fichiers. Dans les applications de bureau, les ressources en texte (.txt ou .restext) ou les fichiers .resx sont compilées en fichiers .resources binaires. Dans les applications du Windows 8.x Store, les fichiers .resw sont compilés en fichiers d’index de ressource de package binaire (PRI). Vous pouvez utiliser Resgen.exe pour combler cet écart en extrayant des ressources à partir d’un exécutable ou d’un assembly satellite et en les écrivant dans un ou plusieurs fichiers .resw qui peuvent être utilisés lors du développement d’une application Windows 8.x Store.

La syntaxe permettant de générer des fichiers .resw à partir d’un assembly est la suivante :

resgen filename.extension  [outputDirectory]

où sont les paramètres :

filename.extension Nom d’un assembly .NET Framework (exécutable ou .DLL). Si le fichier ne contient aucune ressource, Resgen.exe ne crée aucun fichier.

outputDirectory Répertoire existant dans lequel écrire les fichiers .resw. S’il outputDirectory est omis, les fichiers .resw sont écrits dans le répertoire actif. Resgen.exe crée un fichier .resw pour chaque fichier .resources dans l’assembly. Le nom de fichier racine du fichier .resw est identique au nom racine du fichier .resources.

La commande suivante crée un fichier .resw dans le répertoire Win8Resources pour chaque fichier .resources incorporé dans MyApp.exe:

resgen MyApp.exe Win8Resources

Compilation conditionnelle des ressources

À compter de .NET Framework 4.5, Resgen.exe prend en charge la compilation conditionnelle des ressources de chaîne dans des fichiers texte (.txt et .restext). Cela vous permet d’utiliser un seul fichier de ressources textuel dans plusieurs configurations de build.

Dans un fichier .txt ou .restext, vous utilisez le #ifdef... #endif construire pour inclure une ressource dans le fichier .resources binaire si un symbole est défini et que vous utilisez la #if !construction ... #endif pour inclure une ressource si un symbole n’est pas défini. Au moment de la compilation, vous définissez ensuite des symboles à l’aide de l’option /define: suivie d’une liste délimitée par des virgules de symboles. La comparaison respecte la casse. Le cas des symboles définis par /define doit correspondre à la casse des symboles dans les fichiers texte à compiler.

Par exemple, le fichier suivant nommé UIResources.text inclut une ressource de chaîne nommée AppTitle qui peut prendre l’une des trois valeurs, selon que les symboles nommés PRODUCTION, CONSULTou RETAIL sont définis.

#ifdef PRODUCTION
AppTitle=My Software Company Project Manager
#endif
#ifdef CONSULT
AppTitle=My Consulting Company Project Manager
#endif
#ifdef RETAIL
AppTitle=My Retail Store Project Manager
#endif
FileMenuName=File

Le fichier peut ensuite être compilé dans un fichier .resources binaire avec la commande suivante :

resgen /define:CONSULT UIResources.restext

Cela produit un fichier .resources qui contient deux ressources de chaîne. La valeur de la AppTitle ressource est « My Consulting Company Project Manager ».

Génération d’une classe de ressources fortement typée

Resgen.exe prend en charge les ressources fortement typées, qui encapsule l’accès aux ressources en créant des classes qui contiennent un ensemble de propriétés statiques en lecture seule. Cela offre une alternative à l’appel des méthodes de la ResourceManager classe directement pour récupérer des ressources. Vous pouvez activer la prise en charge des ressources fortement typées à l’aide de l’option /str de Resgen.exe, qui encapsule les fonctionnalités de la StronglyTypedResourceBuilder classe. 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 référencées dans le paramètre d’entrée. Cette classe fournit un accès en lecture seule fortement typé aux ressources disponibles dans le fichier traité.

La syntaxe permettant de créer une ressource fortement typée est la suivante :

resgen inputFilename [outputFilename] /str:language[,namespace,[classname[,filename]]] [/publicClass]

Les paramètres et les commutateurs sont les suivants :

inputFilename Nom de fichier, y compris l’extension, du fichier de ressources pour lequel générer une classe de ressource fortement typée. Le fichier peut être un fichier .resources binaire, basé sur du texte, XML ; il peut avoir une extension de .txt, .restext, .resw ou .resources.

outputFilename Nom du fichier de sortie. Si outputFilename elle inclut un chemin d’accès au répertoire, le répertoire doit exister. Si vous omettez outputFilename, Resgen.exe crée un fichier .resources avec le nom de fichier racine du inputFilename même répertoire que inputFilename.

outputFilename peut être un fichier .resources binaire, basé sur du texte, XML. Si l’extension de fichier est outputFilename différente de l’extension de fichier de inputFilename, Resgen.exe effectue la conversion de fichier.

S’il inputFilename s’agit d’un fichier .resources, Resgen.exe copie le fichier .resources s’il outputFilename s’agit également d’un fichier .resources. Si outputFilename elle est omise, Resgen.exe remplace par inputFilename un fichier .resources identique.

Langue Langage dans lequel générer du code source pour la classe de ressources fortement typée. Les valeurs possibles sont, et pour le code C#, vb et visualbasic pour le code Visual Basic, vbs et vbscript pour le code VBScript, et cppmcc++pour le code C++.csharpC#cs

Namespace Espace de noms qui contient la classe de ressources fortement typée. Le fichier .resources et la classe de ressources doivent avoir le même espace de noms. Pour plus d’informations sur la spécification de l’espace de noms dans le outputFilenamefichier binaire, consultez Compilation de ressources dans un fichier binaire. Si l’espace de noms est omis, la classe de ressource n’est pas contenue dans un espace de noms.

classname Nom de la classe de ressources fortement typée. Cela doit correspondre au nom racine du fichier .resources. Par exemple, si Resgen.exe génère un fichier .resources nommé MyCompany.Libraries.Strings.resources, le nom de la classe de ressources fortement typée est Strings. Si classname est omis, la classe générée est dérivée du nom racine de outputFilename. Si outputFilename elle est omise, la classe générée est dérivée du nom racine de inputFilename.

classname ne peut pas contenir de caractères non valides tels que des espaces incorporés. Si classname contient des espaces incorporés ou si classname est généré par défaut à partir d’inputFilename, et inputFilename contient des espaces incorporés, Resgen.exe remplace tous les caractères non valides par un trait de soulignement (_).

Fichier Nom du fichier de classe.

/publicclass Rend la classe de ressources fortement typée publique plutôt que internal (en C#) ou Friend (en Visual Basic). Cela permet aux ressources d’être accessibles à partir de l’extérieur de l’assembly dans lequel elles sont incorporées.

La classe de ressources fortement typée comporte les membres suivants :

• Constructeur sans paramètre, qui peut être utilisé pour instancier la classe de ressources fortement typée.

• Une static propriété (C#) ou Shared (Visual Basic) et en lecture seule ResourceManager , qui retourne l’instance ResourceManager qui gère la ressource fortement typée.

• Propriété statique Culture , qui vous permet de définir la culture utilisée pour la récupération des ressources. Par défaut, sa valeur est null, ce qui signifie que la culture actuelle de l’interface utilisateur est utilisée.

• Une static (C#) ou Shared (Visual Basic) et une propriété en lecture seule pour chaque ressource dans le fichier .resources. Le nom de la propriété est le nom de la ressource.-

Par exemple, la commande suivante compile un fichier de ressources nommé StringResources.txt dans StringResources.resources et génère une classe nommée StringResources dans un fichier de code source Visual Basic nommé StringResources.vb qui peut être utilisé pour accéder à Resource Manager.

resgen StringResources.txt /str:vb,,StringResources

Voir aussi

• Outils
• Les ressources dans les applications .NET
• Créer des fichiers de ressources
• Al.exe (Assembly Linker)
• Shells en ligne de commande développeur