ResourceReader Class
Updated: June 2011
Enumerates the resources in a binary resources (.resources) file by reading sequential resource name/value pairs.
Assembly: mscorlib (in mscorlib.dll)
The ResourceReader type exposes the following members.
| Name | Description | |
|---|---|---|
![]() ![]() | ResourceReader(Stream) | Initializes a new instance of the ResourceReader class for the specified stream. |
![]() ![]() | ResourceReader(String) | Initializes a new instance of the ResourceReader class for the specified named resource file. |
| Name | Description | |
|---|---|---|
![]() ![]() | Close | Releases all operating system resources associated with this ResourceReader object. |
![]() | Dispose | Releases all resources used by the current instance of the ResourceReader class. |
![]() ![]() | Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
![]() ![]() | Finalize | Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.) |
![]() ![]() | GetEnumerator | Returns an enumerator for this ResourceReader object. |
![]() ![]() | GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
![]() | GetResourceData | Retrieves the type name and data of a named resource from an open resource file or stream. |
![]() ![]() | GetType | Gets the Type of the current instance. (Inherited from Object.) |
![]() ![]() | MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
![]() ![]() | ToString | Returns a string that represents the current object. (Inherited from Object.) |
| Name | Description | |
|---|---|---|
![]() | AsParallel | Enables parallelization of a query. (Defined by ParallelEnumerable.) |
![]() | AsQueryable | Converts an IEnumerable to an IQueryable. (Defined by Queryable.) |
![]() ![]() | Cast(Of TResult) | Casts the elements of an IEnumerable to the specified type. (Defined by Enumerable.) |
![]() ![]() | OfType(Of TResult) | Filters the elements of an IEnumerable based on a specified type. (Defined by Enumerable.) |
| Name | Description | |
|---|---|---|
![]() ![]() ![]() | IDisposable.Dispose | Releases all resources used by the ResourceReader. |
![]() ![]() ![]() | IEnumerable.GetEnumerator | Returns an enumerator for this ResourceReader object. |
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.
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)
To create a ResourceReader object that represents an embedded .resources file, instantiate an Assembly object from the assembly in which the .resources file is embedded. Its Assembly.GetManifestResourceStream method returns a Stream object that can be passed to the ResourceReader constructor. The following example instantiates a ResourceReader object that represents an embedded .resources file.
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.
Note |
|---|
Although the ResourceReader class implements the IEnumerable interface and the IEnumerable.GetEnumerator method, the ResourceReader.GetEnumerator method does not provide the IEnumerable.GetEnumerator implementation. Instead, the ResourceReader.GetEnumerator method returns an IDictionaryEnumerator interface object that provides access to each resource's name/value pair. |
You can retrieve the individual resources in the collection in two ways:
You can iterate each resource in the System.Collections.IDictionaryEnumerator collection and use System.Collections.IDictionaryEnumerator properties to retrieve the resource name and value. We recommend this technique when all the resources are of the same type, or you know the data type of each resource.
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.
Title="Contact Information" Label1="First Name:" Label2="Middle Name:" Label3="Last Name:" Label4="SSN:" Label5="Street Address:" Label6="City:" Label7="State:" Label8="Zip Code:" Label9="Home Phone:" Label10="Business Phone:" Label11="Mobile Phone:" Label12="Other Phone:" Label13="Fax:" Label14="Email Address:" Label15="Alternate Email Address:"
You can then convert the text resource file to a binary file named ApplicationResources.resources by using the following command:
resgen ApplicationResources.txt
The following example then uses the ResourceReader class to enumerate each resource in the standalone binary .resources file and to display its key name and corresponding value.
Imports System.Collections Imports System.Resources Module Example Public Sub Main() Console.WriteLine("Resources in ApplicationResources.resources:") Dim res As New ResourceReader(".\ApplicationResources.resources") Dim dict As IDictionaryEnumerator = res.GetEnumerator() Do While dict.MoveNext() Console.WriteLine(" {0}: '{1}' (Type {2})", dict.Key, dict.Value, dict.Value.GetType().Name) Loop res.Close() End Sub End Module ' The example displays output like the following: ' Resources in ApplicationResources.resources: ' Label3: '"Last Name:"' (Type String) ' Label2: '"Middle Name:"' (Type String) ' Label1: '"First Name:"' (Type String) ' Label7: '"State:"' (Type String) ' Label6: '"City:"' (Type String) ' Label5: '"Street Address:"' (Type String) ' Label4: '"SSN:"' (Type String) ' Label9: '"Home Phone:"' (Type String) ' Label8: '"Zip Code:"' (Type String) ' Title: '"Contact Information"' (Type String) ' Label12: '"Other Phone:"' (Type String) ' Label13: '"Fax:"' (Type String) ' Label10: '"Business Phone:"' (Type String) ' Label11: '"Mobile Phone:"' (Type String) ' Label14: '"Email Address:"' (Type String) ' Label15: '"Alternate Email Address:"' (Type String)
The attempt to retrieve resource data from the IDictionaryEnumerator.Value property can throw the following exceptions:
A FormatException if the data is not in the expected format.
A FileNotFoundException if the assembly that contains the type to which the data belongs cannot be found.
A TypeLoadException if the type to which the data belongs cannot be cannot be found.
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 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.
<Serializable> Public Structure DateTimeTZI Dim [Date] As DateTime Dim TimeZone As TimeZoneInfo Public Sub New([date] As DateTime, tz As TimeZoneInfo) Me.[Date] = [date] Me.TimeZone = tz End Sub Public Overrides Function ToString() As String Return String.Format("{0:dd/MM/yyyy hh:mm:ss tt} {1}", [Date], TimeZone.StandardName) End Function End Structure
Compile the source code in C# by using the following command:
csc /t:library library.cs
Or, you can compile it in Visual Basic by using the following command:
vbc library.vb /t:library
Compile and execute the following source code, which creates a .resources file named ContactResources.resources.
Imports System.Drawing Imports System.IO Imports System.Resources Imports System.Runtime.Serialization.Formatters.Binary Imports System.Text Module Example Public Sub Main() ' Bitmap as stream. Dim bitmapStream As New MemoryStream() Dim bmp As New Bitmap(".\ContactsIcon.jpg") bmp.Save(bitmapStream, Imaging.ImageFormat.jpeg) ' Define resources to be written. Using rw As New ResourceWriter(".\ContactResources.resources") rw.AddResource("Title", "Contact List") rw.AddResource("NColumns", 5) rw.AddResource("Icon", bitmapStream) rw.AddResource("Header1", "Name") rw.AddResource("Header2", "City") rw.AddResource("Header3", "State") rw.AddResource("VersionDate", New DateTimeTZI(#05/18/2012#, TimeZoneInfo.Local)) rw.AddResource("ClientVersion", True) rw.Generate() End Using End Sub End Module
The source code file is named CreateResources.cs. You can compile it in C# by using the following command:
csc CreateResources.cs /r:library.dll
Or, you can compile it in Visual Basic by using the following command:
vbc CreateResources.vb /r:library.dll
Compile and run the following code to enumerate the resources in the ContactResources.resources file.
Imports System.Collections Imports System.Drawing Imports System.IO Imports System.Resources Imports System.Runtime.Serialization.Formatters.Binary Module Example Public Sub Main() Dim rdr As New ResourceReader(".\ContactResources.resources") Dim dict As IDictionaryEnumerator = rdr.GetEnumerator() Do While dict.MoveNext() Console.WriteLine("Resource Name: {0}", dict.Key) Try Console.WriteLine(" Value: {0}", dict.Value) Catch e As FileNotFoundException Console.WriteLine(" Exception: A file cannot be found.") DisplayResourceInfo(rdr, CStr(dict.Key), False) Catch e As FormatException Console.WriteLine(" Exception: Corrupted data.") DisplayResourceInfo(rdr, CStr(dict.Key), True) Catch e As TypeLoadException Console.WriteLine(" Exception: Cannot load the data type.") DisplayResourceInfo(rdr, CStr(dict.Key), False) End Try Loop End Sub Private Sub DisplayResourceInfo(rr As ResourceReader, key As String, loaded As Boolean) Dim dataType As String = Nothing Dim data() As Byte = Nothing rr.GetResourceData(key, dataType, data) ' Display the data type. Console.WriteLine(" Data Type: {0}", dataType) ' Display the bytes that form the available data. Console.Write(" Data: ") Dim lines As Integer = 0 For Each dataItem In data lines += 1 Console.Write("{0:X2} ", dataItem) If lines Mod 25 = 0 Then Console.Write("{0} ", vbCrLf) Next Console.WriteLine() ' Try to recreate current state of data. ' Do: Bitmap, DateTimeTZI Select Case dataType ' Handle internally serialized string data (ResourceTypeCode members). Case "ResourceTypeCode.String" Dim reader As New BinaryReader(New MemoryStream(data)) Dim binData As String = reader.ReadString() Console.WriteLine(" Recreated Value: {0}", binData) Case "ResourceTypeCode.Int32" Console.WriteLine(" Recreated Value: {0}", BitConverter.ToInt32(data, 0)) Case "ResourceTypeCode.Boolean" Console.WriteLine(" Recreated Value: {0}", BitConverter.ToBoolean(data, 0)) ' .jpeg image stored as a stream. Case "ResourceTypeCode.Stream" Const OFFSET As Integer = 4 Dim size As Integer = BitConverter.ToInt32(data, 0) Dim value As New Bitmap(New MemoryStream(data, OFFSET, size)) Console.WriteLine(" Recreated Value: {0}", value) ' Our only other type is DateTimeTZI. Case Else ' No point in deserializing data if the type is unavailable. If dataType.Contains("DateTimeTZI") And loaded Then Dim binFmt As New BinaryFormatter() Dim value As Object = binFmt.Deserialize(New MemoryStream(data)) Console.WriteLine(" Recreated Value: {0}", value) End If End Select Console.WriteLine() End Sub End Module
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.
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.






Note