System.Xml.Serialization.XmlEnumAttribute Class

Assembly: System.Xml.dll
Namespace: System.Xml.Serialization
Summary
Controls how the XmlSerializer serializes an enumeration member.
C# Syntax:
[AttributeUsage(AttributeTargets.Field)]
public class XmlEnumAttribute : Attribute
Remarks
The XmlEnumAttribute belongs to a family of attributes that controls how the XmlSerializer serializes, or deserializes, an object. For a complete list of similar attributes, see the conceptual topic at MSDN: attributesthatcontrolserialization.

Use the XmlEnumAttribute to change the enumeration that the XmlSerializer generates or recognizes (when it serializes or deserializes a class, respectively). For example, if an enumeration contains a member named One, but you prefer that the XML output be named Single, apply the XmlEnumAttribute to the enumeration member and set the XmlEnumAttribute.Name property to "Single".

You can override the XmlEnumAttribute.Name property value of an XmlEnumAttribute by creating an instance of the XmlEnumAttribute class, and assigning it to the XmlAttributes.XmlEnum property of an XmlAttributes object. For details, see the XmlAttributeOverrides class.



Note In your code you can use the word XmlEnum instead of the longer XmlEnumAttribute.
Example
The following example applies the XmlEnumAttribute to the members of an enumeration. When the XmlSerializer generates XML data for this enumeration, the data will conform to the values of the XmlEnumAttribute.Name properties.
public enum EmployeeStatus
{
   [XmlEnum(Name = "Single")]
   One,
   [XmlEnum(Name = "Double")]
   Two,
   [XmlEnum(Name = "Triple")]
   Three
}
   

    


Note In your code, you can use the word XmlEnum instead of the longer XmlEnumAttribute.
See also:
System.Xml.Serialization Namespace | XmlSerializer.Serialize | XmlSerializer.Deserialize | XmlSerializer | XmlAttributes.XmlEnum | XmlAttributeOverrides | XmlAttributes | MSDN: introducingxmlserialization | MSDN: overridingserializationofclasseswithxmlattributeoverridesclass | XmlAttributes | MSDN: controllingserializationbyxmlserializerwithattributes | MSDN: anexampleofxmlserializationwithxmlserializer

System.Xml.Serialization.XmlEnumAttribute Member List:

Public Constructors
ctor #1 Overloaded:
.ctor()

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
Initializes a new instance of the XmlEnumAttribute class.
ctor #2 Overloaded:
.ctor(string name)

Initializes a new instance of the XmlEnumAttribute class, and specifies the XML value that the XmlSerializer generates or recognizes (when it serializes or deserializes the enumeration, respectively).
Public Properties
Name Read-write

Gets or sets the value generated in an XML-document instance when the XmlSerializer serializes an enumeration, or the value recognized when it deserializes the enumeration member.
TypeId
(inherited from System.Attribute)
Read-only

See base class member description: System.Attribute.TypeId


When implemented in a derived class, gets a unique identifier for this Attribute.
Public Methods
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
GetHashCode
(inherited from System.Attribute)
See base class member description: System.Attribute.GetHashCode


Returns the hash code for this instance.
GetType
(inherited from System.Object)
See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
IsDefaultAttribute
(inherited from System.Attribute)
See base class member description: System.Attribute.IsDefaultAttribute


When overridden in a derived class, returns an indication whether the value of this instance is the default value for the derived class.
Match
(inherited from System.Attribute)
See base class member description: System.Attribute.Match


When overridden in a derived class, returns a value indicating whether this instance equals a specified object.
ToString
(inherited from System.Object)
See base class member description: System.Object.ToString

Derived from System.Object, the primary base class for all objects.
Protected Methods
Finalize
(inherited from System.Object)
See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)
See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:


System.Xml.Serialization.XmlEnumAttribute Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the XmlEnumAttribute class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
C# Syntax:
public XmlEnumAttribute();
Remarks
You can use the XmlEnumAttribute.#ctor to override an existing enumeration.

Note In your code you can use the word XmlEnum instead of the longer XmlEnumAttribute.
Example
The following example serializes two classes named Food and FoodType. The FoodType class contains two enumerations that are overridden and, for each enumeration, the example creates an XmlEnumAttribute object which it assigns to the XmlAttributes.XmlEnum property of an XmlAttributes object. The example then adds the XmlAttributes object to an XmlAttributeOverrides object, which is used to create an XmlSerializer.
using System;
using System.IO;
using System.Xml;
using System.Xml.Serialization;

// This is the class that will be serialized.
public class Food
{
   public FoodType Type;
}

public enum FoodType
{
   // Subsequent code overrides these enumerations.
   Low,
   High
}


 
public class Run
{
   public static void Main()
   {
      Run test = new Run();
      test.SerializeObject("OverrideEnum.xml");
      test.DeserializeObject("OverrideEnum.xml");
   }

   // Return an XmlSerializer used for overriding. 
   public XmlSerializer CreateOverrider()
   {
      // Create the XmlOverrides and XmlAttributes objects.
      XmlAttributeOverrides xOver = new XmlAttributeOverrides();
      XmlAttributes xAttrs = new XmlAttributes();

      // Add an XmlEnumAttribute for the FoodType.Low enumeration.
      XmlEnumAttribute xEnum = new XmlEnumAttribute();
      xEnum.Name = "Cold";
      xAttrs.XmlEnum = xEnum;
      xOver.Add(typeof(FoodType), "Low", xAttrs);

      // Add an XmlEnumAttribute for the FoodType.High enumeration.
      xAttrs = new XmlAttributes();
      xEnum = new XmlEnumAttribute();
      xEnum.Name = "Hot";
      xAttrs.XmlEnum = xEnum;
      xOver.Add(typeof(FoodType), "High", xAttrs);

      // Create the XmlSerializer, and return it.
      return new XmlSerializer(typeof(Food), xOver);
   }
   
 
   public void SerializeObject(string filename)
   {
      // Create an instance of the XmlSerializer class.
      XmlSerializer mySerializer =  CreateOverrider();
      // Writing the file requires a TextWriter.
      TextWriter writer = new StreamWriter(filename);

      // Create an instance of the class that will be serialized.
      Food myFood = new Food();

      // Set the object properties.
      myFood.Type = FoodType.High;

      // Serialize the class, and close the TextWriter.
      mySerializer.Serialize(writer, myFood);
      writer.Close();
   }

   public void DeserializeObject(string filename)
   {
      XmlSerializer mySerializer = CreateOverrider();
      FileStream fs = new FileStream(filename, FileMode.Open);
      Food myFood = (Food) 
      mySerializer.Deserialize(fs);

      Console.WriteLine(myFood.Type);
   }
}


    
See also:
XmlSerializer.Serialize | XmlSerializer.Deserialize | XmlSerializer

Return to top


Overloaded ctor #2
Summary
Initializes a new instance of the XmlEnumAttribute class, and specifies the XML value that the XmlSerializer generates or recognizes (when it serializes or deserializes the enumeration, respectively).
C# Syntax:
public XmlEnumAttribute(
   string name
);
Parameters:

name

The overriding name of the enumeration member.

Remarks


Note In your code you can use the word XmlEnum instead of the longer XmlEnumAttribute.
Example
The following example applies the XmlEnumAttribute to the members of an enumeration. When the XmlSerializer generates XML data for this enumeration, the data will conform to the values of the XmlEnumAttribute.Name properties.
public enum EmployeeStatus
{
   [XmlEnum("Single")]
   One,
   [XmlEnum("Double")]
   Two,
   [XmlEnum("Triple")]
   Three
}
   

    
See also:
XmlSerializer.Serialize | XmlSerializer.Deserialize | XmlSerializer

Return to top


Property: Name (read-write)
Summary
Gets or sets the value generated in an XML-document instance when the XmlSerializer serializes an enumeration, or the value recognized when it deserializes the enumeration member.
C# Syntax:
public string Name {get; set;}
Remarks
Specify the XmlEnumAttribute.Name when you want the generated XML data to differ from the enumeration identifier.

Note In your code you can use the word XmlEnum instead of the longer XmlEnumAttribute.
Example
The following example applies the XmlEnumAttribute attribute to members of an enumeration. The generated XML data will conform to the values set for the XmlEnumAttribute.Name property.
public enum EmployeeStatus
{
   [XmlEnum("Single")]
   One,
   [XmlEnum("Double")]
   Two,
   [XmlEnum("Triple")]
   Three
}
   

    
See also:
XmlSerializer.Serialize | XmlSerializer.Deserialize | XmlSerializer

Return to top


Property: TypeId (read-only)
Inherited
See base class member description: System.Attribute.TypeId

Summary
When implemented in a derived class, gets a unique identifier for this Attribute.
C# Syntax:
public virtual object TypeId {get;}
Remarks
As implemented, this identifier is merely the Type of the attribute. However, it is intended that the unique identifier be used to identify two attributes of the same type.

Return to top


Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top


Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~XmlEnumAttribute();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetHashCode()
Inherited
See base class member description: System.Attribute.GetHashCode

Summary
Returns the hash code for this instance.
C# Syntax:
public override int GetHashCode();
Return Value:
A 32-bit signed integer hash code.

Return to top


Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: IsDefaultAttribute()
Inherited
See base class member description: System.Attribute.IsDefaultAttribute

Summary
When overridden in a derived class, returns an indication whether the value of this instance is the default value for the derived class.
C# Syntax:
public virtual bool IsDefaultAttribute();
Return Value:
true if this instance is the default attribute for the class; otherwise, false.
Remarks
The default implementation of this class returns false, and must be implemented in the derived class to be useful to that class.

The implementation of this method in a derived class compares the value of this instance to a standard, default value obtained by some means, then returns a Boolean value that indicates whether the value of this instance is equal to the standard. The standard value is typically coded as a constant in the implementation, or stored programmatically in a field used by the implementation.

Return to top


Method: Match(
   object obj
)
Inherited
See base class member description: System.Attribute.Match

Summary
When overridden in a derived class, returns a value indicating whether this instance equals a specified object.
C# Syntax:
public virtual bool Match(
   object obj
);
Parameters:

obj

An Object to compare with this instance of Attribute.

Return Value:
true if this instance equals obj; otherwise, false.
Remarks
This method determines if one Attribute equals another. Its default implementation is the same as Attribute.Equals, which performs a value and reference comparison. Override this method to implement support for attribute values, such as flags or bitfields, that consist of components that are meaningful in themselves. For example, consider an attribute whose value is a binary field divided into a bitfield of flags. Two instances of this attribute have one flag in set in common while all the other flags differ. The Equal method cannot determine that the two instances have the same flag set, but the Match method can.

Return to top


Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: ToString()
Inherited
See base class member description: System.Object.ToString
C# Syntax:
public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.