ResXResourceReader Class

Enumerates XML resource (.resx) files and streams, and reads the sequential resource name and value pairs.

Definition

Namespace: KGySoft.Resources
Assembly: KGySoft.CoreLibraries (in KGySoft.CoreLibraries.dll) Version: 7.0.0-rc.1
C#
public sealed class ResXResourceReader : IResourceReader, 
	IEnumerable, IDisposable
Inheritance
Object    ResXResourceReader
Implements
IEnumerable, IDisposable, IResourceReader

Remarks

You can use the ResXResourceReader class to enumerate resources in .resx files by traversing the dictionary enumerator (IDictionaryEnumerator) that is returned by the GetEnumerator method. You call the methods provided by IDictionaryEnumerator to advance to the next resource and to read the name and value of each resource in the .resx file.

  Note

The ResXResourceReader class provides more enumerators.

If the SafeMode property is , the value of the IDictionaryEnumerator.Value property is a ResXDataNode instance rather than the resource value. This makes possible to check the raw .resx content before deserialization if the .resx file is from an untrusted source. See also the example at ResXDataNode.

If you want to retrieve named resources from a .resx file rather than enumerating its resources, then you can instantiate a ResXResourceSet object and call its GetString/GetObject, GetMetaString/GetMetaObject and GetAliasValue methods. Also ResXResourceSet supports SafeMode.

Example

The following example shows how to enumerate the resources, metadata and aliases of a .resx file and what is the difference between safe and non-safe mode. Please note that SafeMode property can be switched on and off during the enumeration, too. Please also note that the values returned by the GetAliasEnumerator are always strings, regardless of the value of SafeMode property. See also the example of the ResXDataNode class to see how to examine the properties of the ResXDataNode instances in safe mode.
C#
 using System;
 using System.Collections;
 using System.IO;
 using KGySoft.Resources;

 public class Example
 {
     private const string resx = @"<?xml version='1.0' encoding='utf-8'?>
 <root>
   <data name='string'>
     <value>Test string</value>
     <comment>Default data type is string.</comment>
   </data>

   <metadata name='meta string'>
     <value>Meta String</value>
   </metadata>

   <data name='int' type='System.Int32'>
     <value>42</value>
   </data>

   <assembly alias='CustomAlias' name='System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' />

   <data name='color' type='System.Drawing.Color, CustomAlias'>
     <value>Red</value>
     <comment>When this entry is deserialized, System.Drawing assembly will be loaded.</comment>
   </data>

   <data name='bytes' type='System.Byte[]'>
     <value>VGVzdCBieXRlcw==</value>
   </data>

   <data name='dangerous' mimetype='application/x-microsoft.net.object.binary.base64'>
     <value>YmluYXJ5</value>
     <comment>BinaryFormatter will throw an exception for this invalid content.</comment>
   </data>

 </root>";

    public static void Main()
    {
        var reader = new ResXResourceReader(new StringReader(resx));
        Console.WriteLine("____Resources in .resx:____");
        Dump(reader, reader.GetEnumerator);
        Console.WriteLine("____Metadata in .resx:____");
        Dump(reader, reader.GetMetadataEnumerator);
        Console.WriteLine("____Aliases in .resx:____");
        Dump(reader, reader.GetAliasEnumerator);
    }

    private static void Dump(ResXResourceReader reader, Func<IDictionaryEnumerator> getEnumeratorFunction)
    {
        var enumerator = getEnumeratorFunction();
        while (enumerator.MoveNext())
        {
            Console.WriteLine($"Name: {enumerator.Key}");
            reader.SafeMode = true;
            Console.WriteLine($"  Value in SafeMode:     {enumerator.Value} ({enumerator.Value.GetType()})");
            try
            {
                reader.SafeMode = false;
                Console.WriteLine($"  Value in non-SafeMode: {enumerator.Value} ({enumerator.Value.GetType()})");
            }
            catch (Exception e)
            {
                Console.WriteLine($"Getting the deserialized value thrown an exception: {e.Message}");
            }
            Console.WriteLine();
        }
    }
}

 // The example displays the following output:
 // ____Resources in .resx:____
 // Name: string
 // Value in SafeMode:     Test string (KGySoft.Resources.ResXDataNode)
 // Value in non-SafeMode: Test string (System.String)

 // Name: int
 // Value in SafeMode:     42 (KGySoft.Resources.ResXDataNode)
 // Value in non-SafeMode: 42 (System.Int32)

 // Name: color
 // Value in SafeMode:     Red (KGySoft.Resources.ResXDataNode)
 // Value in non-SafeMode: Color[Red] (System.Drawing.Color)

 // Name: bytes
 // Value in SafeMode:     VGVzdCBieXRlcw== (KGySoft.Resources.ResXDataNode)
 // Value in non-SafeMode: System.Byte[] (System.Byte[])

 // Name: dangerous
 // Value in SafeMode:     YmluYXJ5 (KGySoft.Resources.ResXDataNode)
 // Getting the deserialized value thrown an exception: End of Stream encountered before parsing was completed.

 // ____Metadata in .resx:____
 // Name: meta string
 // Value in SafeMode:     Meta String (KGySoft.Resources.ResXDataNode)
 // Value in non-SafeMode: Meta String (System.String)

 // ____Aliases in .resx:____
 // Name: CustomAlias
 // Value in SafeMode:     System.Drawing, Version= 4.0.0.0, Culture= neutral, PublicKeyToken= b03f5f7f11d50a3a (System.String)
 // Value in non-SafeMode: System.Drawing, Version= 4.0.0.0, Culture= neutral, PublicKeyToken= b03f5f7f11d50a3a (System.String)

By default, ResXResourceReader allows duplicated keys with different values (see AllowDuplicatedKeys property). Though such a .resx file is not strictly valid, its complete content can be retrieved. When AllowDuplicatedKeys is , GetEnumerator, GetMetadataEnumerator and GetAliasEnumerator return a lazy enumerator for the first time meaning the .resx file is parsed only during the enumeration. When any of the enumerators are obtained for the second time, a cached enumerator is returned with the whole parsed .resx content. If duplicates are disabled, the lastly defined values will be returned of a redefined name. This behavior is similar to the System.Resources.ResXResourceReader class, which does not allow duplicates.

Example

The following example demonstrates the difference of lazy (allowing duplicates) and greedy (disabling duplicates) reading.
C#
using System;
using System.Collections;
using System.IO;
using KGySoft.Resources;

public class Example
{
    private const string resx = @"<?xml version='1.0' encoding='utf-8'?>
<root>
  <data name='item'>
    <value>Test string</value>
  </data>

  <data name='item'>
    <value>This is a duplicate for key 'item'.</value>
  </data>
</root>";

    public static void Main()
    {
        // Allowing duplicates and lazy reading.
        Console.WriteLine("-------Lazy reading------");
        var reader = new ResXResourceReader(new StringReader(resx)) { AllowDuplicatedKeys = true };
        IDictionaryEnumerator enumerator = reader.GetEnumerator();
        Dump(enumerator); // if resx contains a syntax error, an exception is thrown during the enumeration.

        // Disabling duplicates and lazy reading
        Console.WriteLine("-------Greedy reading------");
        reader = new ResXResourceReader(new StringReader(resx)) { AllowDuplicatedKeys = false };
        enumerator = reader.GetEnumerator(); // if resx contains a syntax error, an exception is thrown here.
        Dump(enumerator);
    }

    private static void Dump(IDictionaryEnumerator enumerator)
    {
        while (enumerator.MoveNext())
        {
            Console.WriteLine($"Key: {enumerator.Key}");
            Console.WriteLine($"Value: {enumerator.Value}");
            Console.WriteLine();
        }
    }
}

// The example displays the following output:
// -------Lazy reading------
// Key: item
// Value: Test string
//
// Key: item
// Value: This is a duplicate for key 'item'.
//
// -------Greedy reading------
// Key: item
// Value: This is a duplicate for key 'item'.

Comparison with System.Resources.ResXResourceReader 

ResXResourceReader can read .resx files produced both by ResXResourceWriter and System.Resources.ResXResourceWriter.

Incompatibility with System.Resources.ResXResourceReader:

New features and improvements compared to System.Resources.ResXResourceReader:

Constructors

ResXResourceReader(Stream, ITypeResolutionService) Initializes a new instance of the ResXResourceReader class for the specified stream.
ResXResourceReader(String, ITypeResolutionService) Initializes a new instance of the ResXResourceReader class for the specified resource file.
ResXResourceReader(TextReader, ITypeResolutionService) Initializes a new instance of the ResXResourceReader class for the specified TextReader.

Properties

AllowDuplicatedKeys Gets or sets whether all entries of same name of the .resx file should be returned.
Default value: .
BasePath Gets or sets the base path for the relative file path specified in a ResXFileRef object.
Default value: .
CheckHeader Gets or sets whether "resheader" entries are checked in the .resx file. When , a NotSupportedException can be thrown during the enumeration when "resheader" entries contain invalid values. When header entries are missing, no exception is thrown.
Default value: .
SafeMode Gets or sets whether ResXDataNode objects are returned when reading the current XML resource file or stream.
Default value: .
UseResXDataNodes Gets or sets whether ResXDataNode objects are returned when reading the current XML resource file or stream.
Default value: .
Obsolete.

Methods

Close Releases all resources used by the ResXResourceReader.
Finalize This member overrides the Finalize method.
(Overrides ObjectFinalize)
FromFileContents Creates a new ResXResourceReader object and initializes it to read a string whose contents are in the form of an XML resource file.
GetAliasEnumerator Provides an IDictionaryEnumerator instance that can retrieve the aliases from the current XML resource file or stream.
GetEnumerator Returns an IDictionaryEnumerator instance for the current ResXResourceReader object that enumerates the resources in the source XML resource file or stream.
GetMetadataEnumerator Returns an IDictionaryEnumerator instance for the current ResXResourceReader object that enumerates the design-time properties (<metadata> elements) in the source XML resource file or stream.

Extension Methods

Convert Converts an Object specified in the obj parameter to the desired targetType.
See the Examples section of the generic ConvertTTarget(Object, CultureInfo) overload for an example.
(Defined by ObjectExtensions)
ConvertTTarget Converts an Object specified in the obj parameter to the desired TTarget.
(Defined by ObjectExtensions)
In Gets whether item is among the elements of set.
See the Examples section of the generic InT(T, T) overload for an example.
(Defined by ObjectExtensions)
IndexOf Searches for an element in the source enumeration where the specified predicate returns .
(Defined by EnumerableExtensions)
IndexOf Searches for an element in the source enumeration.
(Defined by EnumerableExtensions)
IsNullOrEmpty Determines whether the specified source is or empty (has no elements).
(Defined by EnumerableExtensions)
TryAdd Tries to add the specified item to the collection.
(Defined by EnumerableExtensions)
TryAddRange Tries to add the specified collection to the target collection.
(Defined by EnumerableExtensions)
TryClear Tries to remove all elements from the collection.
(Defined by EnumerableExtensions)
TryConvert Tries to convert an Object specified in the obj parameter to the desired targetType.
See the Examples section of the ConvertTTarget(Object, CultureInfo) method for a related example.
(Defined by ObjectExtensions)
TryConvert Tries to convert an Object specified in the obj parameter to the desired targetType.
See the Examples section of the ConvertTTarget(Object, CultureInfo) method for a related example.
(Defined by ObjectExtensions)
TryConvertTTarget Tries to convert an Object specified in the obj parameter to the desired TTarget.
See the Examples section of the ConvertTTarget(Object, CultureInfo) method for a related example.
(Defined by ObjectExtensions)
TryConvertTTarget Tries to convert an Object specified in the obj parameter to the desired TTarget.
See the Examples section of the ConvertTTarget(Object, CultureInfo) method for a related example.
(Defined by ObjectExtensions)
TryGetCount Tries to get the number of elements in the source enumeration without enumerating it.
(Defined by EnumerableExtensions)
TryGetElementAt Tries to get an item at the specified index in the collection.
(Defined by EnumerableExtensions)
TryInsert Tries to insert the specified item at the specified index to the collection.
(Defined by EnumerableExtensions)
TryInsertRange Tries to insert the specified collection into the target collection.
(Defined by EnumerableExtensions)
TryRemove Tries to remove the specified item from to the collection.
(Defined by EnumerableExtensions)
TryRemoveAt Tries to remove an item at the specified index from the collection.
(Defined by EnumerableExtensions)
TryRemoveRange Tries to remove count amount of items from the specified collection at the specified index.
(Defined by EnumerableExtensions)
TryReplaceRange Tries to remove count amount of items from the target at the specified index, and to insert the specified collection at the same position. The number of elements in collection can be different from the amount of removed items.
(Defined by EnumerableExtensions)
TrySetElementAt Tries to set the specified item at the specified index in the collection.
(Defined by EnumerableExtensions)

See Also