System.Xml.Serialization.XmlIncludeAttribute Class

Assembly: System.Xml.dll
Namespace: System.Xml.Serialization
Summary
Allows the XmlSerializer to recognize a type when it serializes or deserializes an object.
C# Syntax:
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Method)]
public class XmlIncludeAttribute : Attribute
Remarks
Use the XmlIncludeAttribute when you call the XmlSerializer.Serialize or XmlSerializer.Deserialize method of the XmlSerializer class.

When applying the XmlIncludeAttribute, specify the Type of the derived class. When the XmlSerializer serializes objects that include both the base and the derived class, it can then recognize both object types.

You can use the XmlIncludeAttribute to include derived classes in service description documents that are written in the Web Services Description Language (WSDL). For example, if a method returns an Object, apply the XmlIncludeAttribute to the method and specify the actual types that should be returned.

For more information on the WSDL, see "Web Services Description Language (WSDL) 1.1" at www.w3.org .

Example
The following example show three classes, two of which inherit from the third. The example applies the XmlIncludeAttribute to a method that returns an instance of one of the derived classes.
<%@ WebService Language="C#" Class="Test" %>
 
using System;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Web.Services.Description;
using System.Xml;
using System.Xml.Schema;
using System.Xml.Serialization;
using System.Data;
 
public class Test : WebService {
   [WebMethod()]
   [return:XmlElement("MyTime", DataType="time")]
   public DateTime EchoString([XmlElement(DataType="string")] 
   string strval) {
        return DateTime.Now;
   }
 
   [WebMethod()]
   [XmlInclude(typeof(Car)), XmlInclude(typeof(Bike))]
   public Vehicle Vehicle(string licenseNumber) {
      if (licenseNumber == "0") {
         Vehicle v = new Car();
         v.licenseNumber = licenseNumber;
         return v;
      }
      else if (licenseNumber == "1") {
          Vehicle v = new Bike();
          v.licenseNumber = licenseNumber;
          return v;
      }
      else {
         return null;
      }
   }
}
[XmlRoot("NewVehicle")] 
public abstract class Vehicle {
    public string licenseNumber;
    public DateTime make;
}
 
public class Car : Vehicle {
}
 
public class Bike : Vehicle {
}
   

    
See also:
System.Xml.Serialization Namespace | XmlSerializer | MSDN: introducingxmlserialization | MSDN: overridingserializationofclasseswithxmlattributeoverridesclass | XmlAttributes | MSDN: controllingserializationbyxmlserializerwithattributes | MSDN: anexampleofxmlserializationwithxmlserializer

System.Xml.Serialization.XmlIncludeAttribute Member List:

Public Constructors
ctor #1 Initializes a new instance of the XmlIncludeAttribute class.
Public Properties
Type Read-write

Gets or sets the type of the object to include.
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.XmlIncludeAttribute Member Details

ctor #1
Summary
Initializes a new instance of the XmlIncludeAttribute class.
C# Syntax:
public XmlIncludeAttribute(
   Type type
);
Parameters:

type

The Type of the object to include.

Example
The following example show three classes, two of which inherit from the third. The example applies the XmlIncludeAttribute to a method that returns an instance of one of the two derived classes. The example sets the XmlIncludeAttribute.Type property to the type of the returned object.
public class Vehicle{}
 
public class Car:Vehicle{}
 
public class Truck:Vehicle{}
 
public class Sample
{
[WebMethodAttribute]
[XmlInclude(typeof(Car))]
[XmlInclude(typeof(Truck))]
public Vehicle ReturnVehicle(int i){
   if(i == 0)
      return new Car();
   else
      return new Truck();
   }
}   

    

Return to top


Property: Type (read-write)
Summary
Gets or sets the type of the object to include.
C# Syntax:
public Type Type {get; set;}
Example
The following example defines a class named Group, which contains a field named Employees that retuns an array of Employee objects. The example derives the Manager class from the Employee class, and applies the XmlIncludeAttribute to the Employee class. When the example creates a Group object, it inserts a Manager object into the Employee array. Lastly, the example serializes the Group object.
using System;
using System.IO;
using System.Xml.Serialization;

public class Group
{   
   public Employee[] Employees;
}   

// Instruct the XmlSerializer to accept Manager types as well.
[XmlInclude(typeof(Manager))]
public class Employee
{
   public string Name;
}

public class Manager:Employee
{
   public int Level;
}


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


   public void SerializeObject(string filename)
   {
      XmlSerializer s = new XmlSerializer(typeof(Group));
      TextWriter writer = new StreamWriter(filename);
      Group group = new Group();
      
      Manager manager = new Manager();
      Employee emp1 = new Employee();
      Employee emp2 = new Employee();

      manager.Name = "Zeus";
      manager.Level = 2;

      emp1.Name = "Ares";

      emp2.Name = "Artemis";

      Employee [] emps = new Employee[3]{manager, emp1, emp2};
      group.Employees = emps;

      s.Serialize(writer, group);
      writer.Close();
   }

   public void DeserializeObject(string filename)
   {
      FileStream fs = new FileStream(filename, FileMode.Open);
      XmlSerializer x = new XmlSerializer(typeof(Group));
      Group g = (Group) x.Deserialize(fs);
      Console.Write("Members:");
      
      foreach(Employee e in g.Employees) 
      {
         Console.WriteLine("\t" + e.Name);
      }
   }
}


    

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

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.