TConverter class can be used as a base class for writing custom value converters. Converters acts as custom serialization and de-serialization handlers of values of some type.

Writing custom converter implies sub-classing TConverter base class, and overriding its abstract methods. Custom converter should be associated with a type using NG.Serialization.ConverterAttribute; after that, converter will be used by serialization engine to write and read values of the type.

Custom converter instances are created and destroyed automatically by serialization engine.

Custom Converters and Polymorphism

Custom converters are not restricted in the way, of how to serialize data value. The most common example of this aspect is when collection value, which is essentially an object, is serialized as an array. So, because of such requirement, built-in polymorphism is not supported for custom converted object values.

Thus, its not correct to serialize (as well as de-serialize) custom converted collection like this: S.Value<TObject>(MyColl), because the engine will select TObject handler, which, of course, supports polymorphism and will be able to serialize any TObject descendant, but only as an object. So, this way MyColl will be serialized as an object; that is, all its public field and properties will be serialized; and no custom converter methods will be called.

The same can be said about property or array element types. Its not correct to have a property of TObject type, which returns a  value of custom converted collection type.

Note:
Unlike some built-in type handlers, custom converters is able to work in a single read-mode only. Look at NG.Serialization.TConverter.GetReadMode method description for more information.

Reference

• NG.Serialization.ConverterAttribute
• NG.Serialization.TReadMode
• NG.Serialization.FillReadAttribute
• TSerializer
• TDeserializer
• NG.Serialization Namespace