BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

XML
.NET 1.1+

Controlling XML Serialization of Enumerations

When properties containing enumeration values are serialized to XML, the text value of the constant is added to an XML element by default. The XmlEnum attribute allows different values to be substituted for each item in the enumeration.

Serializing Enumerations

When you serialize an object to XML using default options, each public property and field is added to the generated document as an XML element containing a single value or further elements. If a property is defined as an enumerated type, a simple value is included in the element. This value contains the textual representation of the enumeration constant.

We can demonstrate the standard behaviour by creating an enumeration and a class that uses it. We can then create an instance of the class, serialize it and review the resultant XML. To do so, create the following enumeration, which defines several possible statuses for a printer.

public enum PrinterStatus
{
    OK = 0,
    OffLine = 1,
    PaperTrayEmpty = 2,
    TonerExhausted = 4,
    PaperJam = 8
}

We can now create a class that represents a printer with a name and a status. The class below using C#3.0 automatically implemented properties. If you are using an earlier version of the .NET framework, expand these to properties that include a backing store.

public class Printer
{
    public string Name { get; set; }
    public PrinterStatus Status { get; set; }
}

Finally, execute the code below to create a Printer object and serialize it to an XML file. You may wish to change the path of the generated file.

Printer printer = new Printer();
printer.Name = "IT";
printer.Status = PrinterStatus.PaperJam;

XmlSerializer serializer = new XmlSerializer(printer.GetType());
using (StreamWriter writer = new StreamWriter(@"c:\Test\test.xml"))
{
    serializer.Serialize(writer, printer);
}

The resultant XML is similar to that shown below. For simplicity I have removed the "xml" tag and the default namespaces. Note that the Status property has been stored using the name from the enumeration, "PaperJam".

<Printer>
    <Name>IT</Name> 
    <Status>PaperJam</Status> 
</Printer>

XmlEnum

In some situations you may wish to use a different value in an XML element instead of the text of the appropriate enumeration constant. To do so you can use the XmlEnum attribute. The attribute is applied to each constant in the enumeration individually, providing the new name to the sole string parameter.

To demonstrate, update the enumeration to apply the XmlEnum attribute to each value, as follows:

public enum PrinterStatus
{
    [XmlEnum("On-line")]
    OK = 0,

    [XmlEnum("Off-line")]
    OffLine = 1,

    [XmlEnum("Paper Tray Empty")]
    PaperTrayEmpty = 2,

    [XmlEnum("No Toner")]
    TonerExhausted = 4,

    [XmlEnum("Jammed")]
    PaperJam = 8
}

When you serialize the printer object, the Status element contains the name from the attribute instead of the name of the constant:

<Printer>
    <Name>IT</Name> 
    <Status>On-line</Status> 
</Printer>
15 February 2011