Remarks

Important

Calling methods from this class with untrusted data is a security risk. Call the methods from this class only with trusted data. For more information, see Data Validation.

The ResourceReader class provides a standard implementation of the IResourceReader interface. A ResourceReader instance represents either a standalone .resources file or a .resources file that is embedded in an assembly. It is used to enumerate the resources in a .resources file and retrieve its name/value pairs. It differs from the ResourceManager class, which is used to retrieve specified named resources from a .resources file that is embedded in an assembly. The ResourceManager class is used to retrieve resources whose names are known in advance, whereas the ResourceReader class is useful for retrieving resources whose number or precise names are not known at compile time. For example, an application may use a resources file to store configuration information that is organized into sections and items in a section, where the number of sections or items in a section is not known in advance. Resources can then be named generically (such as Section1, Section1Item1, Section1Item2, and so on) and retrieved by using a ResourceReader object.

Important

This type implements the IDisposable interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its Dispose method in a try/catch block. To dispose of it indirectly, use a language construct such as using (in C#) or Using (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the IDisposable interface topic.

For more information about using the ResourceReader class, see the following sections:

Instantiating a ResourceReader Object

A .resources file is a binary file that has been compiled from either a text file or an XML .resx file by Resgen.exe (Resource File Generator). A ResourceReader object can represent either a standalone .resources file or a .resources file that has been embedded in an assembly.

To instantiate a ResourceReader object that reads from a standalone .resources file, use the ResourceReader class constructor with either an input stream or a string that contains the .resources file name. The following example illustrates both approaches. The first instantiates a ResourceReader object that represents a .resources file named Resources1.resources by using its file name. The second instantiates a ResourceReader object that represents a .resources file named Resources2.resources by using a stream created from the file.

' Instantiate a standalone .resources file from its filename.
Dim rr1 As New System.Resources.ResourceReader("Resources1.resources")
' Instantiate a standalone .resources file from a stream.
Dim fs As New System.IO.FileStream(".\Resources2.resources",
System.IO.FileMode.Open)
Dim rr2 As New System.Resources.ResourceReader(fs)

Enumerating a ResourceReader Object's Resources

To enumerate the resources in a .resources file, you call the GetEnumerator method, which returns an System.Collections.IDictionaryEnumerator object. You call the IDictionaryEnumerator.MoveNext method to move from one resource to the next. The method returns false when all the resources in the .resources file have been enumerated.

You can retrieve the name of each resource when you iterate the System.Collections.IDictionaryEnumerator collection and call the GetResourceData method to retrieve the resource's data. We recommend this approach when you do not know the data type of each resource or if the previous approach throws exceptions.

Retrieving Resources by Using IDictionaryEnumerator Properties

The first method of enumerating the resources in a .resources file involves directly retrieving each resource's name/value pair. After you call the IDictionaryEnumerator.MoveNext method to move to each resource in the collection, you can retrieve the resource name from the IDictionaryEnumerator.Key property and the resource data from the IDictionaryEnumerator.Value property.

The following example shows how to retrieve the name and value of each resource in a .resources file by using the IDictionaryEnumerator.Key and IDictionaryEnumerator.Value properties. To run the example, create the following text file named ApplicationResources.txt to define string resources.

Typically, these exceptions are thrown if the .resources file has been modified manually, if the assembly in which a type is defined has either not been included with an application or has been inadvertently deleted, or if the assembly is an older version that predates a type. If one of these exceptions is thrown, you can retrieve resources by enumerating each resource and calling the GetResourceData method, as the following section shows. This approach provides you with some information about the data type that the IDictionaryEnumerator.Value property attempted to return.

Retrieving Resources by Name with GetResourceData

The second approach to enumerating resources in a .resources file also involves navigating through the resources in the file by calling the IDictionaryEnumerator.MoveNext method. For each resource, you retrieve the resource's name from the IDictionaryEnumerator.Key property, which is then passed to the GetResourceData(String, String, Byte[]) method to retrieve the resource's data. This is returned as a byte array in the resourceData argument.

This approach is more awkward than retrieving the resource name and value from the IDictionaryEnumerator.Key and IDictionaryEnumerator.Value properties, because it returns the actual bytes that form the resource value. However, if the attempt to retrieve the resource throws an exception, the GetResourceData method can help identify the source of the exception by supplying information about the resource's data type. For more information about the string that indicates the resource's data type, see GetResourceData.

The following example illustrates how to use this approach to retrieve resources and to handle any exceptions that are thrown. It programmatically creates a binary .resources file that contains four strings, one Boolean, one integer, one bitmap, and one custom DateTimeTZI object. To run the example, do the following:

Create an assembly named Library.dll that contains the DateTimeTZI structure. The following is the source code for the assembly.

After modifying the source code (for example, by deliberately throwing a FormatException at the end of the try block) or renaming the Library.dll assembly so that it is unavailable at runtime, you can run the example to see how calls to GetResourceData enable you to retrieve or recreate some resource information.