KGy SOFT

KGySoft.Resources Namespace

KGy SOFT Core Libraries Help
Contains classes for resource management, which support read-write access directly to .resx files (ResXResourceManager) or even combined access to compiled and .resx resources (HybridResourceManager, DynamicResourceManager).
See the Remarks section to see when to use the difference classes of this namespace.
Classes

  ClassDescription
Public classAutoSaveErrorEventArgs
Provides data for the AutoSaveError event.
Public classDynamicResourceManager
Represents a resource manager that provides convenient access to culture-specific resources at run time. As it is derived from HybridResourceManager, it can handle both compiled resources from .dll and .exe files, and XML resources from .resx files at the same time. Based on the selected strategies when a resource is not found in a language it can automatically add the missing resource from a base culture or even create completely new resource sets and save them into .resx files. For text entries the untranslated elements will be marked so they can be found easily for translation.
See the Remarks section for examples and for the differences compared to HybridResourceManager class.
Public classHybridResourceManager
Represents a resource manager that provides convenient access to culture-specific resources at run time. It can handle both compiled resources from .dll and .exe files, and .resx files at the same time. New elements can be added as well, which can be saved into .resx files.
See the Remarks section for an example and for the differences compared to ResourceManager class.
Public classResXDataNode
Represents a resource or metadata element in an XML resource (.resx) file.
See the Remarks section for an example and for the differences compared to System.Resources.ResXDataNode class.
Public classResXFileRef
Represents a link to an external resource.
See the Remarks section for the differences compared to System.Resources.ResXFileRef class.
Public classResXResourceManager
Represents a resource manager that provides convenient access to culture-specific XML resources (.resx files) at run time. New elements can be added as well, which can be saved into the .resx files.
See the Remarks section for examples and for the differences compared to ResourceManager class.
Public classResXResourceReader
Enumerates XML resource (.resx) files and streams, and reads the sequential resource name and value pairs.
See the Remarks section for examples and for the differences compared to System.Resources.ResXResourceReader class.
Public classResXResourceSet
Represents the complete content of an XML resource (.resx) file including resources, metadata and aliases.
See the Remarks section for examples and for the differences compared to System.Resources.ResXResourceSet class.
Public classResXResourceWriter
Writes resources in an XML resource (.resx) file or an output stream.
See the Remarks section for an example and for the differences compared to System.Resources.ResXResourceWriter class.
Interfaces

  InterfaceDescription
Public interfaceIExpandoResourceManager
Represents a ResourceManager with write capabilities.
Public interfaceIExpandoResourceSet
Represents a ResourceSet class that can hold replaceable resources.
Enumerations

  EnumerationDescription
Public enumerationAutoAppendOptions
Represents the resource auto append options of a DynamicResourceManager instance. These options are ignored if Source is CompiledOnly.
Public enumerationAutoSaveOptions
Represents the auto saving options of a DynamicResourceManager instance.
Public enumerationResourceManagerSources
Represents the possible sources of HybridResourceManager and DynamicResourceManager classes.
Public enumerationResourceSetRetrieval
Represents the retrieval behavior of an IExpandoResourceSet in IExpandoResourceManager.GetExpandoResourceSet method.
Remarks

The KGySoft.Resources namespace contains several classes, which can handle resources from XML sources (.resx files). The table below can help you to choose the best one for your needs.
ClassWhen to choose this one; added functionality compared to previous levels.
ResXResourceReaderUsing ResXResourceReader is the most low-level option to read the content of a .resx file. It provides enumerators to retrieve the resources, metadata and aliases of a .resx content. In most cases you can use the more specialized classes, such as ResXResourceSet but there are some cases when you need to use ResXResourceReader:
  • The ResXResourceReader is able to read the .resx content in a lazy manner if ResXResourceReader.AllowDuplicatedKeys is . That means the .resx content is read on demand as you enumerate the contents (the contents are cached so if you retrieve an enumerator for the second time it will not process the .resx file again). It can be useful if you are looking for one specific key, after which you break the enumeration or if you want to process an incomplete or corrupted .resx file up to the point it can be parsed correctly.
  • A .resx file may contain a key more than once (though it is somewhat incorrect). If ResXResourceReader.AllowDuplicatedKeys is , you can retrieve all of the redefined values.
  • ResXResourceReader allows you to handle type names in a customized way (how names are mapped to a Type). To use custom name resolution pass an ITypeResolutionService instance to one of the constructors.
ResXResourceWriterUsing ResXResourceWriter is the most low-level option to write the content of a .resx file. Use this if at least one of the following points are applicable for you:
  • You want to have full control over the order of the dumped resources, metadata and aliases or you want to re-use a key or redefine an alias during the dump (though it is not recommended).
  • You want to dump the full .resx header including the comments dumped also by Visual Studio when you create a resource file (see ResXResourceWriter.OmitHeader property).
  • You want to use customized type names when non-string resources are added. You can achieve this by passing a Func<Type, string> delegate to one of the constructors.
ResXResourceSetThe ResXResourceSet class represents the full content of a single .resx file in memory. It provides both enumerators and dictionary-like direct key access to the resources, metadata and aliases. It uses ResXResourceReader and ResXResourceWriter internally to load/save .resx content. As an IExpandoResourceSet implementation it is able to add/replace/remove entries and save the content. Use this class in the following cases:
  • You want to access the resources/metadata/aliases of a single .resx file directly by name just like in a dictionary.
  • You want to load the .resx content not just from a file but also a Stream/TextReader or to save it to a Stream/TextWriter.
Specialization compared to ResXResourceReader/ResXResourceWriter:
  • Default type name handling and type resolution is used.
  • When loading a .resx file, duplications are not allowed. For redefined names the last value will be stored.
  • When saving a .resx file, header comment is always omitted. If content is saved in non-compatible format, the .resx schema header is omitted, too.
  • When saving a .resx file, assembly aliases are auto generated for assemblies, which are not explicitly defined.
ResXResourceManagerThe ResXResourceManager handles resources in the same manner as ResourceManager does but instead of working with binary compiled resources it uses XML resources (.resx files) directly. It takes the culture hierarchy into account so querying a resource by a specific CultureInfo may end up loading multiple resource files. It stores ResXResourceSet instances internally to store the resources of the different cultures. As an IExpandoResourceManager implementation it is able to add/replace/remove entries in the resource sets belonging to specified cultures and it can save the changed contents.
Specialization compared to ResXResourceSet:
HybridResourceManagerThe HybridResourceManager combines the functionality of the regular ResourceManager and the ResXResourceManager classes. The source of the resources can be chosen by the Source property (see ResourceManagerSources enumeration). Enabling both binary and .resx resources makes possible to expand or override the resources originally come from binary resources. Just like the ResXResourceManager it is an IExpandoResourceManager implementation. The replacement and newly added content is saved into .resx files.
DynamicResourceManagerThe DynamicResourceManager is derived from HybridResourceManager and adds the functionality of automatically appending the resources with the non-translated and/or unknown entries as well as auto-saving the changes. This makes possible to automatically create the .resx files if the language of the application is changed to a language, which has no translation yet. See also the static LanguageSettings class. The strategy of auto appending and saving can be chosen by the AutoAppend and AutoSave properties (see AutoAppendOptions and AutoSaveOptions enumerations).