System.Xml.Serialization.XmlAnyElementAttribute Class

Assembly: System.Xml.dll
Namespace: System.Xml.Serialization
Summary
Specifies that the member (a field that returns an array of XmlElement or XmlNode objects) can contain objects that represent any XML element that has no corresponding member in the object being serialized or deserialized.
C# Syntax:
[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.ReturnValue)]
public class XmlAnyElementAttribute : Attribute
Remarks
Use the XmlAnyElementAttribute to contain arbitrary data (as XML elements) that might be sent as part of an XML document, such as, metadata sent as part of the document.

Apply the XmlAnyElementAttribute to a field that returns an array of XmlElement or XmlNode objects. Such a field can be used in two ways, depending on whether an object is being serialized or deserialized. When serialized, the object will be generated as XML elements or nodes, even though they have no corresponding member (or members) in the object being serialized. If you specify a XmlAnyElementAttribute.Name property value when applying the attribute, all XmlElement or XmlNode objects inserted into the array must have the same element name and default namespace, or an exception will be thrown. If you set the XmlAnyElementAttribute.Namespace property value, you must set the XmlAnyElementAttribute.Name property as well, and the XmlElement or XmlNode objects must also have the same name and namespace values. If no XmlAnyElementAttribute.Name value is specified, the XmlElement or XmlNode objects can have any element name.

When you call the XmlSerializer.Deserialize method of the XmlSerializer class, all attributes that do not have a corresponding member in the object being deserialized will be collected in the array. After deserialization, iterate through the collection of XmlElement items to process the data. If you specify a XmlAnyElementAttribute.Name value, the array will contain only XML elements with that name. If you do not specify a XmlAnyElementAttribute.Name value, the array will contain all elements that have no corresponding member in the class. If a class contains more than one field to which the attribute is applied, you should use the XmlAnyElementAttribute.Name, or XmlAnyElementAttribute.Name and XmlAnyElementAttribute.Namespace properties to differentiate between the contents of the arrays. If such a class (with multiple fields) also contains one field that has no differentiating property values set (in other words, XmlAnyElementAttribute.Name and XmlAnyElementAttribute.Namespace), during deserialization, this array will contain any unknown XML elements that are not already contained in the other arrays. If a class contains more than one field that doesn't have a differentiating XmlAnyElementAttribute.Name, or XmlAnyElementAttribute.Name and XmlAnyElementAttribute.Namespace value set, the behavior during deserialization is unspecified.

You can also apply the XmlAnyElementAttribute to a field that returns a single XmlElement object. If you do so, you will have to use the properties and methods of the XmlElement class to recursively iterate through the unknown elements.

You can apply multiple instances of the XmlAnyElementAttribute to a class member, but each instance must have a distinct XmlAnyElementAttribute.Name property value. Or, if the same XmlAnyElementAttribute.Name property is set for each instance, a distinct XmlAnyElementAttribute.Namespace property value must be set for each instance.

The XmlSerializer.UnknownNode and XmlSerializer.UnknownAttribute events of the XmlSerializer will not occur if you apply the XmlAnyElementAttribute to a member of a class.



Note In your code, you can use the word XmlAnyElement instead of the longer XmlAnyElementAttribute.

For more information about using attributes, see the conceptual topic at MSDN: extendingmetadatausingattributes.

Example
The following example applies the XmlAnyElementAttribute to a field named AllElements that returns an array of XmlElement objects.
public class XClass
{
   /* Apply the XmlAnyElementAttribute to a field returning an array
   of XmlElement objects. */
   [XmlAnyElement]
   public XmlElement[] AllElements;
}

public class Test
{
   public static void Main()
   {
      Test t = new Test();
      t.DeserializeObject("XFile.xml");
   }

   private void DeserializeObject(string filename)
   {
      // Create an XmlSerializer.
      XmlSerializer mySerializer = new XmlSerializer(typeof(XClass));

      // To read a file, a FileStream is needed.
      FileStream fs = new FileStream(filename, FileMode.Open);

      // Deserialize the class.
      XClass x = (XClass) mySerializer.Deserialize(fs);

      // Read the element names and values.
      foreach(XmlElement xel in x.AllElements)
         Console.WriteLine(xel.LocalName + ": " + xel.Value);
   }
}
See also:
System.Xml.Serialization Namespace | XmlAnyAttributeAttribute | MSDN: introducingxmlserialization

System.Xml.Serialization.XmlAnyElementAttribute 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 XmlAnyElementAttribute class.
ctor #2 Overloaded:
.ctor(string name)

 Initializes a new instance of the XmlAnyElementAttribute class; specifies the XML element name generated in the XML document.
ctor #3 Overloaded:
.ctor(string name, string ns)

 Initializes a new instance of the XmlAnyElementAttribute class; specifies the XML element name generated in the XML document and its XML namespace.
Public Properties
Name Read-write

Gets or sets the XML element name.
Namespace Read-write

Gets or sets the XML namespace generated in the XML document.
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.XmlAnyElementAttribute Member Details

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

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
C# Syntax:
public XmlAnyElementAttribute();
Remarks
Use the XmlAnyElementAttribute constructor when you are overriding the serialization of a field. For more details about overriding serialization, see the XmlAttributeOverrides class.

Return to top

Overloaded ctor #2
Summary
Initializes a new instance of the XmlAnyElementAttribute class; specifies the XML element name generated in the XML document.
C# Syntax:
public XmlAnyElementAttribute(
   string name
);
Parameters:

name

The name of the XML element that the XmlSerializer generates.

Remarks
Use the XmlAnyElementAttribute constructor when you are overriding the serialization of a field. For more details about overriding serialization, see the XmlAttributeOverrides class.

Return to top

Overloaded ctor #3
Summary
Initializes a new instance of the XmlAnyElementAttribute class; specifies the XML element name generated in the XML document and its XML namespace.
C# Syntax:
public XmlAnyElementAttribute(
   string name,
   string ns
);
Parameters:

name

The name of the XML element that the XmlSerializer generates.

ns

The XML namespace of the XML element.

Remarks
Use the XmlAnyElementAttribute constructor when you are overriding the serialization of a field. For more details about overriding serialization, see the XmlAttributeOverrides class.

Return to top

Property: Name (read-write)
Summary
Gets or sets the XML element name.
C# Syntax:
public string Name {get; set;}
Exceptions
Exception Type Condition
InvalidOperationException The element name of an array member does not match the element name specified by the XmlAnyElementAttribute.Name property.
Remarks
If you specify a XmlAnyElementAttribute.Name property value when applying the attribute, all XmlElement or XmlNode objects inserted into the array must have the same element name and default namespace, or an exception will be thrown. If you set the XmlAnyElementAttribute.Namespace property value, you must set the XmlAnyElementAttribute.Name property as well, and the XmlElement or XmlNode objects must also have the same name and namespace values. If no XmlAnyElementAttribute.Name value is specified, the XmlElement or XmlNode objects can have any element name.

When you call the XmlSerializer.Deserialize method of the XmlSerializer class, all attributes that do not have a corresponding member in the object being deserialized will be collected in the array. If you specify a XmlAnyElementAttribute.Name value, the array will contain only XML elements with that name. If you do not specify a XmlAnyElementAttribute.Name value, the array will contain all elements that have no corresponding member in the class. If a class contains more than one field that to which the attribute is applied, you should use the XmlAnyElementAttribute.Name and XmlAnyElementAttribute.Namespace properties to differentiate between the contents of the arrays. If such a class (with multiple fields) also contains one field that has no differentiating property values set (that is, XmlAnyElementAttribute.Name and XmlAnyElementAttribute.Namespace) during deserialization, the array will contain any XML elements that are not already contained in the other arrays. If you add more than one field that doesn't have a differentiating XmlAnyElementAttribute.Name or XmlAnyElementAttribute.Namespace value set, the last field in the class will contain all unknown elements that are not already contained in the other arrays, and any other fields will be set to null.

You can apply multiple instances of the XmlAnyElementAttribute to a class member, but each instance must have a distinct XmlAnyElementAttribute.Name property value. Or, if the same XmlAnyElementAttribute.Name property is set for each instance, a distinct XmlAnyElementAttribute.Namespace property value must be set for each instance.

Example
using System;
using System.Text;
using System.IO;
using System.Xml.Serialization;
using System.Xml;
using System.Xml.Schema;


[XmlRoot(Namespace = "http://www.cohowinery.com")]
public class Group{
   public string GroupName;

   // This is for serializing Employee elements.
   [XmlAnyElement(Name = "Employee")]
   public XmlElement[] UnknownEmployees;

   // This is for serializing City elements.   
   [XmlAnyElement
   (Name = "City", 
   Namespace = "http://www.cpandl.com")]
   public XmlElement[] UnknownCity;

    // This one is for all other unknown elements.
   [XmlAnyElement]
   public XmlElement[] UnknownElements;
}

public class Test{
   static void Main(){
      Test t = new Test();
      t.SerializeObject("AnyElementArray.xml");
      t.DeserializeObject("AnyElementArray.xml");
      Console.WriteLine("Done");
   }

   private void SerializeObject(string filename){
      XmlSerializer ser = new XmlSerializer(typeof(Group));
      // Create an XmlNamespaces to use.
      XmlSerializerNamespaces namespaces =
      new XmlSerializerNamespaces();
      namespaces.Add("c", "http://www.cohowinery.com");
      namespaces.Add("i", "http://www.cpandl.com");
      Group myGroup = new Group();
      // Create arrays of arbitrary XmlElement objects.
      // First create an XmlDocument, used to create the 
      // XmlElement objects.
      XmlDocument xDoc = new XmlDocument();

      // Create an array of Employee XmlElement objects.
      XmlElement El1 = xDoc.CreateElement("Employee", "http://www.cohowinery.com");
      El1.InnerText = "John";
      XmlElement El2 = xDoc.CreateElement("Employee", "http://www.cohowinery.com");
      El2.InnerText = "Joan";
      XmlElement El3 = xDoc.CreateElement("Employee", "http://www.cohowinery.com");
      El3.InnerText = "Jim";
      myGroup.UnknownEmployees= new XmlElement[]{El1, El2, El3};     
    
      // Create an array of City XmlElement objects.
      XmlElement inf1 = xDoc.CreateElement("City", "http://www.cpandl.com");
      inf1.InnerText = "Tokyo";
      XmlElement inf2 = xDoc.CreateElement("City", "http://www.cpandl.com");     
      inf2.InnerText = "New York";
      XmlElement inf3 = xDoc.CreateElement("City", "http://www.cpandl.com");     
      inf3.InnerText = "Rome";

      myGroup.UnknownCity = new XmlElement[]{inf1, inf2, inf3};

      XmlElement xEl1 = xDoc.CreateElement("bld");
      xEl1.InnerText = "42";
      XmlElement xEl2 = xDoc.CreateElement("Region");
      xEl2.InnerText = "West";
      XmlElement xEl3 = xDoc.CreateElement("type");
      xEl3.InnerText = "Technical";
      myGroup.UnknownElements = 
      	new XmlElement[]{xEl1,xEl2,xEl3};
      // Serialize the class, and close the TextWriter.
      TextWriter writer = new StreamWriter(filename);
      ser.Serialize(writer, myGroup, namespaces);
      writer.Close();

   }

   private void DeserializeObject(string filename){
      XmlSerializer ser = new XmlSerializer(typeof(Group));
      FileStream fs = new FileStream(filename, FileMode.Open);
      Group myGroup;
      myGroup = (Group)ser.Deserialize(fs);
      fs.Close();
      foreach(XmlElement xEmp in myGroup.UnknownEmployees){
         Console.WriteLine(xEmp.LocalName + ": " + xEmp.InnerText);}
      foreach(XmlElement xCity in myGroup.UnknownCity){
         Console.WriteLine(xCity.LocalName + ": " + xCity.InnerText);}
      foreach(XmlElement xEl in myGroup.UnknownElements){
         Console.WriteLine(xEl.LocalName + ": " + xEl.InnerText);}
   }
 }

Return to top

Property: Namespace (read-write)
Summary
Gets or sets the XML namespace generated in the XML document.
C# Syntax:
public string Namespace {get; set;}
Remarks
The XmlAnyElementAttribute.Namespace property allows you to set a unique name for the XML attribute. The XmlAnyElementAttribute.Namespace property conforms to the rules for creating an XML namespace as found in the World Wide Web Consortium (www.w3.org) document, "Namespaces in XML."

To set the XmlAnyElementAttribute.Namespace property to a prefixed name, create an XmlSerializerNamespaces that contains the namespaces and prefixes used in the XML document. Set the XmlAnyElementAttribute.Namespace property to one of the namespaces in the XmlSerializerNamespaces. When the XML is generated, the attribute name will be correctly prefixed with the prefix associated with the specified namespace.

Example
using System;
using System.Text;
using System.IO;
using System.Xml.Serialization;
using System.Xml;
using System.Xml.Schema;


[XmlRoot(Namespace = "http://www.cohowinery.com")]
public class Group{
   public string GroupName;

   // This is for serializing Employee elements.
   [XmlAnyElement(Name = "Employee")]
   public XmlElement[] UnknownEmployees;

   // This is for serializing City elements.   
   [XmlAnyElement
   (Name = "City", 
   Namespace = "http://www.cpandl.com")]
   public XmlElement[] UnknownCity;

    // This one is for all other unknown elements.
   [XmlAnyElement]
   public XmlElement[] UnknownElements;
}

public class Test{
   static void Main(){
      Test t = new Test();
      t.SerializeObject("AnyElementArray.xml");
      t.DeserializeObject("AnyElementArray.xml");
      Console.WriteLine("Done");
   }

   private void SerializeObject(string filename){
      XmlSerializer ser = new XmlSerializer(typeof(Group));
      // Create an XmlNamespaces to use.
      XmlSerializerNamespaces namespaces =
      new XmlSerializerNamespaces();
      namespaces.Add("c", "http://www.cohowinery.com");
      namespaces.Add("i", "http://www.cpandl.com");
      Group myGroup = new Group();
      // Create arrays of arbitrary XmlElement objects.
      // First create an XmlDocument, used to create the 
      // XmlElement objects.
      XmlDocument xDoc = new XmlDocument();

      // Create an array of Employee XmlElement objects.
      XmlElement El1 = xDoc.CreateElement("Employee", "http://www.cohowinery.com");
      El1.InnerText = "John";
      XmlElement El2 = xDoc.CreateElement("Employee", "http://www.cohowinery.com");
      El2.InnerText = "Joan";
      XmlElement El3 = xDoc.CreateElement("Employee", "http://www.cohowinery.com");
      El3.InnerText = "Jim";
      myGroup.UnknownEmployees= new XmlElement[]{El1, El2, El3};     
    
      // Create an array of City XmlElement objects.
      XmlElement inf1 = xDoc.CreateElement("City", "http://www.cpandl.com");
      inf1.InnerText = "Tokyo";
      XmlElement inf2 = xDoc.CreateElement("City", "http://www.cpandl.com");     
      inf2.InnerText = "New York";
      XmlElement inf3 = xDoc.CreateElement("City", "http://www.cpandl.com");     
      inf3.InnerText = "Rome";

      myGroup.UnknownCity = new XmlElement[]{inf1, inf2, inf3};

      XmlElement xEl1 = xDoc.CreateElement("bld");
      xEl1.InnerText = "42";
      XmlElement xEl2 = xDoc.CreateElement("Region");
      xEl2.InnerText = "West";
      XmlElement xEl3 = xDoc.CreateElement("type");
      xEl3.InnerText = "Technical";
      myGroup.UnknownElements = 
      	new XmlElement[]{xEl1,xEl2,xEl3};
      // Serialize the class, and close the TextWriter.
      TextWriter writer = new StreamWriter(filename);
      ser.Serialize(writer, myGroup, namespaces);
      writer.Close();

   }

   private void DeserializeObject(string filename){
      XmlSerializer ser = new XmlSerializer(typeof(Group));
      FileStream fs = new FileStream(filename, FileMode.Open);
      Group myGroup;
      myGroup = (Group)ser.Deserialize(fs);
      fs.Close();
      foreach(XmlElement xEmp in myGroup.UnknownEmployees){
         Console.WriteLine(xEmp.LocalName + ": " + xEmp.InnerText);}
      foreach(XmlElement xCity in myGroup.UnknownCity){
         Console.WriteLine(xCity.LocalName + ": " + xCity.InnerText);}
      foreach(XmlElement xEl in myGroup.UnknownElements){
         Console.WriteLine(xEl.LocalName + ": " + xEl.InnerText);}
   }
 }

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:
~XmlAnyElementAttribute();

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.