.NET 1.1+

Controlling XML Serialization of the Root Element

by Richard Carr, published at http://www.blackwasp.co.uk/XMLRoot.aspx

Every XML document includes a root element that contains all of the other information held. When serializing objects to XML the root element's construction is linked to the name of the class or structure unless modified with the XmlRoot attribute.

XML Root Element

All XML documents include a single root element or document element. It is the ultimate parent container for all other elements in the document, with the exception of special items such as XML declarations. When you serialize an object to XML, the root element takes the name of the object's class by default. However, you can modify the name of the root element and further change its serialization using the XmlRoot attribute. This may be applied to classes, structures, interfaces and enumerations.

XmlRoot

We will demonstrate the use of XmlRoot by serializing a simple object to XML and applying various versions of the attribute. To begin, create the following class. You may recognise this as being a simplified version of the class used in the "Ignoring Members During XML Serialization" article. Review that article for the code for performing serialization.

NB: The example class uses automatically implemented properties. If you are using an early version of .NET you should expand these to full declarations.

public class LoggedOperation
{
    public string Description { get; set; }
    public DateTime Started { get; set; }
}

When an example LoggedOperation object is serialized the results are similar to that shown below:

<?xml version="1.0" encoding="utf-8" ?> 
<LoggedOperation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Description>Backup</Description> 
    <Started>2010-12-07T00:00:00</Started> 
</LoggedOperation>

In this article we are only interested in the root element, shown in isolation below:

<LoggedOperation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

As you can see, the root element has taken the name of the class. It includes two attributes that define two XML namespaces for the document, which are added automatically by the serialization engine.

Changing the Root Element Name

A common requirement is to change the name of the root element when serialized. To do so you can define the XmlRoot attribute for the class, providing the preferred name as the only parameter. The following code specifies that the root element should be named "Log".

[XmlRoot("Log")]
public class LoggedOperation
{
    public string Description { get; set; }
    public DateTime Started { get; set; }
}

When the example object is serialized, the root element uses the new name:

<Log xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

The XmlRoot attribute is more flexible when used with named parameters. We can rewrite the above attribute declaration using the ElementName parameter for the same results, as follows:

[XmlRoot(ElementName="Log")]

Setting a Namespace

When using named parameters we can further control serialization behaviour. One option is to specify a namespace for the root element. This is achieved with the Namespace parameter. In the following definition the namespace is set to http://www.blackwasp.co.uk.

[XmlRoot(ElementName="Log", Namespace="http://www.blackwasp.co.uk")]

When serialized, the namespace is added to the root element:

<Log xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.blackwasp.co.uk">

Setting a Data Type

It is possible to specify a data type for the root element using the DataType named parameter. This does not directly affect the outputted XML but changes the schema for the element. The data type must be a valid W3C data type for use in XML schemas.

[XmlRoot(ElementName="Log", DataType="string")]

Using the xsi:nil Attribute

The final named parameter is IsNullable. When this Boolean value is set to true and the object that is serialized is null, the root element includes the xsi:nil attribute with a value of true. When the object being serialized is not null the outputted XML is unaffected. This parameter is useful when you wish to explicitly state that an element is missing.

[XmlRoot(ElementName="Log", IsNullable=true)]

Serializing the previous example object shows no difference in the final XML. However, if you serialize a null reference the root element is formatted with the xsi:nil attribute as follows:

<Log xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:nil="true">