All types|All members

Legend

Class
Struct
Enum
Interface
Delegate
Constructor
Method
Property
Event
Field

Static class: RT.Serialization.Classify

Summary

Provides static methods to represent objects of (almost) arbitrary classes in various formats (such as XML or JSON) and to restore such objects again. See the remarks section for features and limitations.

Remarks

By default, when serializing a custom class, Classify persists the value of all instance fields, including private, inherited and compiler-generated ones. It does not persist static members or the result of property getters. Each field is persisted under a name that is the field’s name minus any leading underscores. Compiler-generated fields for automatically-implemented properties are instead named after the automatically-implemented property’s name minus any leading underscores.

Classify can also generate representations of basic types such as string, int, bool, etc.

Features:

  • Classify fully supports all the built-in types which are keywords in C# except object and dynamic. It also supports DateTime, all enum types, Tuple<...> and KeyValuePair<TKey, TValue>.
  • Classify fully supports classes and structs that contain only fields of the above types as well as fields whose type is itself such a class or struct.
  • Classify has special handling for classes that implement IDictionary<TKey, TValue>, where TKey and TValue must be type also supported by Classify. If a field containing a dictionary is of a concrete type, that type is maintained, but its extra fields are not persisted. If the field is of the interface type IDictionary<TKey, TValue> itself, the type Dictionary<TKey, TValue> is used to reconstruct the object.
  • Classify has special handling for classes that implement ICollection<T>, where T must be a type also supported by Classify. If the field is of a concrete type, that type is maintained, but its extra fields are not persisted. If the field is of the interface type ICollection<T> or IList<T>, the type List<T> is used to reconstruct the object. If the type also implements IDictionary<TKey, TValue>, the special handling for that takes precedence.
  • Classify also specially handles Stack<T> and Queue<T> because they do not implement ICollection<T>. Types derived from these are not supported (but are serialized as if they weren’t a derived type).
  • Classify supports fields of declared type object just as long as the value stored in it is of a supported type.
  • Classify handles values of the type of the serialized form specially. For example, if you are serializing to XML using XElement, serializing an actual XElement object generates the XML directly; if you are classifying to JSON, the same goes for JSON value objects, etc.
  • For classes that don’t implement any of the above-mentioned collection interfaces, Classify supports polymorphism. The actual type of an instance is persisted if it is different from the declared type.
  • Classify supports auto-implemented properties. It uses the name of the property rather than the hidden auto-generated field, although the field’s value is persisted. All other properties are ignored.
  • Classify ignores the order of fields in a class. For example, XML tags or JSON dictionary keys are mapped to fields by their names; their order is considered immaterial.
  • Classify silently discards unrecognized XML tags/JSON dictionary keys instead of throwing errors. This is by design because it enables the programmer to remove a field from a class without invalidating objects previously persisted.
  • Classify silently ignores missing elements. A field whose element is missing retains the value assigned to it by the parameterless constructor. This is by design because it enables the programmer to add a new field to a class (and to specify a default initialization value for it) without invalidating objects previously persisted.
  • The following custom attributes can be used to alter Classify’s behavior. See the custom attribute class’s documentation for more information: ClassifyIgnoreAttribute, ClassifyIgnoreIfAttribute, ClassifyIgnoreIfDefaultAttribute, ClassifyIgnoreIfEmptyAttribute. Any attribute that can be used on a field, can equally well be used on an auto-implemented property, but not on any other properties.
  • Classify maintains object identity and correctly handles cycles in the object graph. Only strings are exempt from this.
  • Classify can make use of type substitutions. See IClassifySubstitute<TTrue, TSubstitute> for more information.
  • Classify allows you to pre-/post-process the serialized form and/or the serialized objects. See IClassifyObjectProcessor, IClassifyObjectProcessor<TElement>, IClassifyTypeProcessor and IClassifyTypeProcessor<TElement> for more information.

Limitations:

  • Classify requires that every type involved have a parameterless constructor, although it can be private. This parameterless constructor is executed with all its side-effects before each object is reconstructed. An exception is made when a field in an object already has a non-null instance assigned to it by the constructor; in such cases, the object is reused.
  • If a field is of type ICollection<T>, IList<T>, IDictionary<TKey, TValue>, or any class that implements either of these, polymorphism is not supported, and nor is any information stored in those classes. In particular, this means that the comparer used by a SortedDictionary<T1, T2> is not persisted. However, if the containing class’s constructor assigned a SortedDictionary<T1, T2> with a comparer, that instance, and hence its comparer, is reused.
  • Classify is not at all optimized for speed or memory efficiency.

Static methods

object
Deserialize<TElement>(Type type, TElement elem, IClassifyFormat<TElement> format, ClassifyOptions options = null)
 Reconstructs an object of the specified type from the specified serialized form.
T
Deserialize<TElement, T>(TElement elem, IClassifyFormat<TElement> format, ClassifyOptions options = null)
object
DeserializeFile<TElement>(Type type, string filename, IClassifyFormat<TElement> format, ClassifyOptions options = null)
 Reconstructs an object of the specified type from the specified file.
T
DeserializeFile<TElement, T>(string filename, IClassifyFormat<TElement> format, ClassifyOptions options = null)
void
DeserializeFileIntoObject<TElement>(string filename, object intoObject, IClassifyFormat<TElement> format, ClassifyOptions options = null)
 Reconstructs an object from the specified file by applying the values to an existing instance of the desired type. The type of object is inferred from the object passed in.
void
DeserializeIntoObject<TElement, T>(TElement element, T intoObject, IClassifyFormat<TElement> format, ClassifyOptions options = null)
 Reconstructs an object of the specified type from the specified serialized form by applying the values to an existing instance of the type.
void
PostBuildStep(Type type, IPostBuildReporter rep)
 Performs safety checks to ensure that a specific type doesn't cause Classify exceptions. Run this method as a post-build step to ensure reliability of execution. For an example of use, see PostBuildChecker.RunPostBuildChecks(string, params Assembly[]).
void
PostBuildStep<T>(IPostBuildReporter rep)
TElement
Serialize<TElement>(Type saveType, object saveObject, IClassifyFormat<TElement> format, ClassifyOptions options = null)
 Converts the specified object into a serialized form.
TElement
Serialize<TElement, T>(T saveObject, IClassifyFormat<TElement> format, ClassifyOptions options = null)
void
SerializeToFile<TElement>(Type saveType, object saveObject, string filename, IClassifyFormat<TElement> format, ClassifyOptions options = null)
 Stores the specified object in a file with the given path and filename.
void
SerializeToFile<TElement, T>(T saveObject, string filename, IClassifyFormat<TElement> format, ClassifyOptions options = null)

Static fields

ClassifyOptions
DefaultOptions
 Options used when null is passed to methods that take options. Make sure not to modify this instance if any thread in the application might be in the middle of using Classify; ideally the options shoud be set once during startup and never changed after that.