Attributes

XML Attributes in MapXML

MapXML provides a set of attributes to facilitate the mapping of XML data to .NET objects. These attributes allow developers to define how XML elements, attributes, and text content are serialized and deserialized.

Most of these attributes can be used to annotate CLR Fields, Properties and Methods, and share the following properties:

• CanSerialize : Whether the target member should be included during Serialization; this value is irrelevant when the attribute is applied to Methods, that can never be involved in a Serialization process. Default is true;
• CanDeserialize : Whether the target member should be included during Deserialization. Default is true;
• SerializationOrder : During a Serialization process, it is used as a sorting value to output Attributes and Groups of children nodes in the desired order; Higher values go last. Default is 255.

Below is an overview of the available XML attributes with a brief description of each one.

1. XMLAttribute

This attribute maps an XML node attribute to a CLR property, field or Method.

Usage:

[XMLAttribute("AttributeName")]
public string PropertyName { get; set; }

Parameters:

• xmlAttributeName (optional): The name of the XML attribute. Defaults to the property or field name.
• policy (optional): Specifies the deserialization policy. Default is DeserializationPolicy.Create.

---

2. XMLChild

This attribute maps an XML child element to a CLR property, field, or method.

Usage:

[XMLChild("ChildElementName")]
public ChildType PropertyName { get; set; }

Parameters:

• xmlAttributeName (optional): The name of the XML child element. Defaults to the property or field name.
• policy (optional): Specifies the deserialization policy. Default is DeserializationPolicy.Create.

---

3. XMLTextContent

This attribute maps the text content of an XML element to a property or field in a .NET class.

Usage:

[XMLTextContent]
public string TextContent { get; set; }

Parameters:

• xmlAttributeName (optional): The name of the XML element. Defaults to the property or field name.
• policy (optional): Specifies the deserialization policy. Default is DeserializationPolicy.Create.

Note: MapXML does NOT support mixed content, Text Content is only supported once inside each node, or none at all.

<?xml version="1.0" encoding="utf-8" ?>
<MixedContent>
  This is <f>Not</f>Allowed
</MixedContent>

Trying to deserialize the above would result in a XMLMixedContentException.

---

4. XMLMap

This attribute maps XML content into a dictionary (IDictionary<>) typed member, specifically as the dictionary values.

Usage:

[XMLMap("ChildElementName", XMLSourceType.Child, XMLMapAttribute.KeySourceTypes.NodeAttribute, "KeyAttributeName")]
public IDictionary<KeyType, ValueType> PropertyName { get; set; }

Parameters:

• xmlAttributeName: The name of the XML element.
• type: Specifies the source type (e.g., XMLSourceType.Child).
• KeySourceType: Defines the source of the dictionary key (e.g., ObjectMember, ParentMember, NodeAttribute).
• KeySourceName: The name of the key source.
• ValueSourceName (optional): The name of the value source.

---

5. XMLNonSerialized

This attribute prevents a property or field from being serialized or deserialized. It is only relevant when the "AllowImplicitFields" option is enabled, and is otherwise ignored.

Usage:

[XMLNonSerialized]
public string PropertyName { get; set; }

Note that it is also possible to use the standard System.NonSerializedAttribute for the same purpose.

[NonSerialized]
public string PropertyName { get; set; }

---

6. XMLFunction

This attribute marks a method as an XML function, which can be used for custom serialization or deserialization logic.

Usage:

[XMLFunction]
public ReturnType MethodName([XMLParameter("ParameterName")] ParameterType parameter) { ... }

---

7. XMLParameter

This attribute is used to define parameters for methods marked with XMLFunctionAttribute.

Usage:

[XMLFunction]
public ReturnType MethodName([XMLParameter("ParameterName")] ParameterType parameter) { ... }

Parameters:

• attributeName: The name of the XML attribute.
• conversionFunction (optional): The name of a static function for converting from string.
• conversionBackFunction (optional): The name of a static function for converting back to string.

---

8. XMLOmit

This is a base class for attributes that control whether a property or field should be omitted during serialization. The intended use is to avoid cluttering serialized nodes with empty attributes for properties that are frequently left with default values.

Irrelevant during Deserialization.

Concrete Classes:

• XMLOmitWhenNull: Omits the property or field if its value is null or an empty string.
• XMLOmitWhenDefault: Omits the property or field if its value is the default for its type.
• XMLOmitWhen: Omits the property or field if its value matches a specified value.

Usage:

[XMLOmitWhenNull]
public string PropertyName { get; set; }