XmlSerializer Class

public static class XmlSerializer

Public NotInheritable Class XmlSerializer

public ref class XmlSerializer abstract sealed

[<AbstractClassAttribute>]
[<SealedAttribute>]
type XmlSerializer = class end

Inheritance

Object    XmlSerializer

XmlSerializer supports serialization of any simple types and complex objects with their public properties and fields as well as several collection types.

Several System.ComponentModel techniques are supported, which also makes possible to use the XmlSerializer for types that can be edited in a property grid, such as components, configurations or any types in a custom designer. The supported component model attributes and techniques:

• DesignerSerializationVisibilityAttribute – Use value Hidden for public field or property to prevent its serialization and use Content value to explicitly express that the property value can be serialized recursively (see also RecursiveSerializationAsFallback) option.
• DefaultValueAttribute – If the value of a public property or field equals to the value specified by this attribute, then its value will not be serialized (see also IgnoreDefaultValueAttribute and AutoGenerateDefaultValuesAsFallback options).
• ShouldSerialize... methods – If the type being serialized has an instance method with no parameters and a Boolean return type (can be private as well) named ShouldSerializeMemberName where MemberName is the name of a property or field, then its return value determines whether the member should be serialized. This technique is used in some designers and property grid controls (see also IgnoreShouldSerialize option).
• TypeConverterAttribute – This attribute is supported both for types and property/field members. If a TypeConverter supports serialization to and from String type, then it will be used for serializing its value (see also the RegisterTypeConverter extension method).

Basically types with default constructors are supported. However, if a field or property value is not after creating its parent object and the type has no parameterless constructor, then the returned instance is tried to be re-used on deserialization.

Options

By specifying the XmlSerializationOptions argument in the Serialize and SerializeContent methods you can override the default behavior of serialization. The None option and the default options parameter value of the serialization methods ensure that only those types are serialized, which are guaranteed to be able to deserialized perfectly. For details see the description of the None option.

If a type cannot be serialized with the currently used options a SerializationException will be thrown.

You can use RecursiveSerializationAsFallback option to enable recursive serialization of every type of objects and collections. A collection type can be serialized if it implements the ICollectionT, IList or IDictionary interfaces, and it can be deserialized if it has a default constructor, or an initializer constructor with a single parameter that can accept an Array or ListT instance (non-dictionaries) or a DictionaryTKey, TValue instance (dictionary collections). Non-collection types must have a parameterless constructor to be able to be deserialized.

If BinarySerializationAsFallback option is enabled, then types without a native support and appropriate TypeConverter will be serialized into a binary stream, which will be stored in the result XML. Though this provides the best compatibility of any type, it hides the whole inner structure of the serialized object. If a root level object without native support is serialized by the Serialize methods using the BinarySerializationAsFallback option, then the whole XML result will be a single node with the binary content. The binary serialization is performed by the BinarySerializationFormatter class. In safe mode deserialization the specified expected types must include the types present in the embedded binary stream(s) by name.

See the XmlSerializationOptions enumeration for further options.

Natively supported types

The names of natively supported types are recognized during deserialization so they are not needed to be declared as expected custom types in safe mode.

When serializing, a wider range of types are supported without specifying any fallback options than the specified lists below. For the specific conditions see the description of the None option.

When deserializing in safe mode, refer to the following couple of lists to see which types are recognized without specifying them as expected custom types.

Natively supported simple types:

• Object
• Boolean
• SByte
• Byte
• Int16
• UInt16
• Int32
• UInt32
• Int64
• UInt64
• Char
• String
• Single
• Double
• Decimal
• DateTime
• TimeSpan
• DateTimeOffset
• IntPtr
• UIntPtr
• Guid, though the serialization/deserialization itself is performed by its type converter
• NullableT types if type parameter is any of the supported types.
• KeyValuePairTKey, TValue if Key and Value are any of the supported types.
• DictionaryEntry
• BigInteger (in .NET Framework 4.0 and above)
• Rune (in .NET Core 3.0 and above)
• Half (in .NET 5.0 and above)
• DateOnly (in .NET 6.0 and above)
• TimeOnly (in .NET 6.0 and above)
• Int128 (in .NET 7.0 and above)
• UInt128 (in .NET 7.0 and above)

Natively supported collections:

• Array
• ListT
• LinkedListT
• CircularListT
• QueueT
• StackT
• HashSetT
• ThreadSafeHashSetT
• ArrayList
• Queue
• Stack
• BitArray
• StringCollection
• DictionaryTKey, TValue
• SortedListTKey, TValue
• SortedDictionaryTKey, TValue
• CircularSortedListTKey, TValue
• ThreadSafeDictionaryTKey, TValue
• StringKeyedDictionaryTValue
• Hashtable
• SortedList
• ListDictionary
• HybridDictionary
• OrderedDictionary
• SortedSetT (in .NET Framework 4.0 and above)
• ConcurrentBagT (in .NET Framework 4.0 and above)
• ConcurrentQueueT (in .NET Framework 4.0 and above)
• ConcurrentStackT (in .NET Framework 4.0 and above)
• ConcurrentDictionaryTKey, TValue (in .NET Framework 4.0 and above)

Comparison with System.Xml.Serialization.XmlSerializer

New features and improvements compared to System.Xml.Serialization.XmlSerializer:

• Strings – If a string contains only white spaces, then system XmlSerializer cannot deserialize it properly. String instances containing invalid UTF-16 code points cannot be serialized either. This XmlSerializer implementation handles them correctly.
• Collections with base element type – If the element type of a collection is a base type or an interface, then the system serializer throws an exception for derived element types suggesting that XmlIncludeAttribute should be defined for all possible derived types. Unfortunately this attribute is applicable only for possible types of properties/fields but not for collection elements. And in many cases it simply cannot be predefined in advance what derived types will be used at run-time.
• Collections with read-only properties – Usually collection properties can be read-only. But to be able to use the system serializer we need to define a setter for such properties; otherwise, serialization may fail. This XmlSerializer does not require setter accessor for a collection property if the property is not after initialization and can be populated by using the usual collection interfaces.
• Objects without default constructors – The system serializer requires that the deserialized types have default constructors. On deserializing fields and properties, this XmlSerializer implementation is able to use the returned value of the members. If they are not after creating their container object, then the returned instances can be reused instead of creating a new instance.

Reference