Resource File Generator (Resgen.exe)
The Resource File Generator converts text (.txt or .restext) files and XML-based resource format (.resx) files to common language runtime binary (.resources) files that can be embedded in a runtime binary executable or compiled into satellite assemblies. For information about deploying and retrieving .resources files, see Resources in Applications.
Resgen.exe performs the following conversions:
Converts .txt or .restext files to .resources or .resx files.
Note
The .restext extension was introduced in the .NET Framework version 2.0. The format of .restext files is identical to the format of .txt files. However, the .restext extension helps you identify text files that contain resource definitions more easily.
Converts .resources files to text or .resx files.
Converts .resx files to text or .resources files.
resgen [parameters] [/compile]filename.extension [outputFilename.extension] [/str:lang[,namespace[,class[,file]]]]
Parameters
Argument |
Description |
|---|---|
filename.extension |
The name of the input file to convert. The extension must be one of the following:
|
outputFilename.extension |
The name of the resource file to create. This argument is optional when converting from a .txt, .restext, or .resx file. You can specify the .resources extension when converting a text or .resx file to a .resources file. If you do not specify an outputFilename, Resgen.exe appends a .resources extension to the input filenameargument and writes the file to the directory that contains filename. The outputFilename argument is mandatory when converting from a .resources file. Specify the .resx extension when converting a .resources file to an XML-based resource file. Specify the .txt or .restext extension when converting a .resources file to a text file. You should only convert a .resources file to a .txt file when the .resources file contains only string values. |
Option |
Description |
|---|---|
/compile |
Allows you to specify multiple .resx or text files to convert to multiple .resources files in a single bulk operation. If you do not specify this option, you can specify only one input file argument. This option cannot be used with the /str: option. |
/publicClass |
Creates a strongly typed resource class as a public class. This option is ignored if the /str: option is not used. |
/r:assembly |
Specifies that types are to be loaded from assembly. If you specify this option, a .resx file with a previous version of a type will use the type in assembly. |
/str:language[,namespace[,classname[,filename]]] |
Creates a strongly typed resource class file in the programming language (cs or C# for C#, vb or visualbasic for Visual Basic) specified in the language option. You can use the namespace option to specify the project's default namespace, the classname option to specify the name of the generated class, and the filename option to specify the name of the class file. Note In the .NET Framework version 2.0, classname and filename are ignored if namespace is not specified. Only one input file is allowed when the /str: option is used, so it cannot be used with the /compile option. If namespace is specified but classname is not, the class name is derived from the output file name (for example, underscores are substituted for periods). The strongly typed resources might not work correctly as a result. To avoid this, specify both class name and output file name. |
/usesourcepath |
Specifies that the input file's current directory is to be used for resolving relative file paths. |
Remarks
Resgen.exe converts files by wrapping the methods implemented by the following four classes:
ResourceReader Class Reads a .resources file.
ResourceWriter Class Creates a .resources file from specified resources.
ResXResourceReader Class Reads a .resx file.
ResXResourceWriter Class Creates a .resx file from specified resources.
Note that a .resx file created by the ResXResourceWriter class cannot be used directly by a .NET Framework application. Before adding this file to your application, run it through Resgen.exe to convert it to a .resources file. For more information about implementing these classes in your code, see their respective reference topics.
In order for Resgen.exe to be able to parse your input, it is critical that your text and .resx files follow the correct format.
Text (.txt or .restext) files can only contain string resources. String resources are useful if you are writing an application that must have strings translated into several languages. For example, you can easily regionalize menu strings by using the appropriate string resource. Resgen.exe reads text files containing name/value pairs, where the name is a string that describes the resource and the value is the resource string itself. You must specify each name/value pair on a separate line as follows:
name=value
Note that empty strings are permitted in text files. For example:
EmptyString=
A text file must be saved with UTF-8 or Unicode encoding unless it contains only characters in the plain Roman alphabet, without diacritical marks such as the cedilla, umlaut, and tilde. For example, Resgen.exe removes extended ANSI characters when it processes a text file that does not have UTF-8 or Unicode encoding.
Resgen.exe checks the text file for duplicate resource names. If the text file contains duplicate resource names, Resgen.exe will emit a warning and ignore the duplicate names. For more details on the text file format, see Resources in Text File Format.
The .resx resource file format consists of XML entries. You can specify string resources within these XML entries, as you would in text files. A primary advantage of .resx files over text files is that you can also specify or embed objects. When you view a .resx file, you can actually see the binary form of an embedded object (a picture for example) when this binary information is a part of the resource manifest. Just as with text files, you can open a .resx file with a text editor (such as Notepad or Microsoft Word) and write, parse, and manipulate the contents. Note that in order to do this, a good knowledge of XML tags and the .resx file structure is required. For more details on the .resx file format, see Resources in .Resx File Format.
In order to create a .resources file containing embedded nonstring objects, you must either use Resgen.exe to convert a .resx file containing objects or add the object resources to your file directly from code, using the methods provided by the ResourceWriter Class. If you use Resgen.exe to convert a .resources file containing objects to a text file, all the string resources will be converted correctly, but the data types of the nonstring objects will also be written to the file as strings. You will lose the embedded objects in the conversion and Resgen.exe will report that an error occurred in retrieving the resources.
The .NET Framework version 2.0 supports strongly typed resources. Strongly typed resource support encapsulates access to resources by creating classes that contain a set of static read-only (get) properties, thus providing an alternative way to consume resources, rather than using the methods of the ResourceManager class directly. The basic functionality is provided by the /str command line option in Resgen.exe, which wraps the functionality of the StronglyTypedResourceBuilder class. When you specify the /str option, the output of Resgen.exe is a class that contains strongly-typed properties that match the resources that are referenced in the input parameter. This class provides strongly-typed read-only access to the resources that are available in the file processed.
The Resource File Generator (Resgen.exe) tool allows you to create .resources files as well as strongly typed wrappers to access those .resources files. When you create a strongly typed wrapper, the name of your .resources file must match the namespace and class name (for example, MyNamespace.MyClass.resources) of the generated code. However, the Resource File Generator (Resgen.exe) tool allows you to specify options that produce a .resources file with an incompatible name. To work around this behavior, rename incompatibly named output files after the Resource File Generator (Resgen.exe) tool generates them.
When you are finished creating .resources files with Resgen.exe, use the Assembly Linker (Al.exe) to either embed the resources in a runtime binary executable or compile them into satellite assemblies.
Note
If Resgen.exe fails for any reason, the return value will be –1.
Note
Resgen.exe does not accept a .resx file name that contains spaces when generating a strongly-typed resource class. It replaces all invalid characters with an underscore ("_"). For more information, see VerifyResourceName.
Examples
The following command, with no options specified, displays the command syntax and options for Resgen.exe.
resgen
The following command reads the name/value pairs in myResources.txt and writes a binary resources file named myResources.resources. Because the output file name is not specified explicitly, it receives the same name as the input file by default.
resgen myResources.txt
The following command reads the name/value pairs in myResources.restext and writes a binary resources file named yourResources.resources.
resgen myResources.restext yourResources.resources
The following command reads an XML-based input file myResources.resx and writes a binary resources file named myResources.resources.
resgen myResources.resx myResources.resources
The following command reads a binary resources file myResources.resources and writes an XML-based output file named myResources.resx.
resgen myResources.resources myResources.resx
The following commands read an XML-based input file named myResources.resx and write text files named myResources.txt and myResources.restext, respectively. Note that if the .resx file contains any embedded objects, they will not be accurately converted into the text files.
resgen myResources.resx myResources.txt
resgen myResources.resx myResources.restext
The following command reads an XML-based input file myResources.resx and writes a binary resources file named myResources.resources. It also generates a C# file named MyFile.cs with a class named MyClass that contains strongly-typed properties that match the resources that are referenced in the input file. The MyClass class is contained within a namespace named Namespace1.
resgen myResources.resx myResources.resources /str:C#,Namespace1,MyClass,MyFile.cs