Управление сериализацией XML с использованием атрибутовControlling XML Serialization Using Attributes

Атрибуты можно использовать для управления сериализацией XML объекта или для создания альтернативного потока XML из того же набора классов.Attributes can be used to control the XML serialization of an object or to create an alternate XML stream from the same set of classes. Дополнительные сведения о создании альтернативного потока XML см. в разделе как: Указание имени альтернативного элемента для XML Stream.For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

Примечание

Если сгенерированные XML должны удовлетворять раздела 5 документа консорциума World Wide Web (W3C) Simple Object Access Protocol (SOAP) 1.1, используйте атрибуты, указанные в атрибуты, элемент управления в кодировке SOAP Сериализация.If the XML generated must conform to section 5 of the World Wide Web Consortium (W3C) document titled Simple Object Access Protocol (SOAP) 1.1, use the attributes listed in Attributes That Control Encoded SOAP Serialization.

По умолчанию имя элемента XML определяется классом или именем члена.By default, an XML element name is determined by the class or member name. Как показано в следующем примере, в простом классе с именем Book полю с именем ISBN будет присвоен тег элемента XML <ISBN>.In a simple class named Book, a field named ISBN will produce an XML element tag <ISBN>, as shown in the following example.

Public Class Book
    Public ISBN As String
End Class
' When an instance of the Book class is serialized, it might
' produce this XML:
' <ISBN>1234567890</ISBN>.
public class Book
{
    public string ISBN;
}
// When an instance of the Book class is serialized, it might
// produce this XML:
// <ISBN>1234567890</ISBN>.

Поведение по умолчанию можно изменить, если элементу следует присвоить новое имя.This default behavior can be changed if you want to give the element a new name. В следующем примере кода показано, как это можно сделать с помощью атрибута, задав свойство ElementNameXmlElementAttribute.The following code shows how an attribute enables this by setting the ElementName property of a XmlElementAttribute.

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class
public class TaxRates {
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Дополнительные сведения об атрибутах см. в разделе Атрибуты.For more information about attributes, see Attributes. Список атрибутов, которые управляют сериализацией XML, см. в разделе Атрибуты управления сериализацией XML.For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

Управление сериализацией массивовControlling Array Serialization

Атрибуты XmlArrayAttribute и XmlArrayItemAttribute предназначены для управления сериализацией массивов.The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. С помощью этих атрибутов можно управлять именем элемента, пространство имен и тип данных схемы XML (XSD) (как определено в документе консорциума World Wide Web Consortium [www.w3.org] под названием «XML Schema Part 2: Типы данных»).Using these attributes, you can control the element name, namespace, and XML Schema (XSD) data type (as defined in the World Wide Web Consortium [www.w3.org] document titled "XML Schema Part 2: Datatypes"). Также можно указать типы, которые можно включить в массив.You can also specify the types that can be included in an array.

XmlArrayAttribute определяет свойства включающего элемента XML, который создается при сериализации массива.The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. Например, по умолчанию при сериализации массива ниже будет создан элемент XML с именем Employees.For example, by default, serializing the array below will result in an XML element named Employees. Элемент Employees будет содержать серию элементов, названную в соответствии с типом массива Employee.The Employees element will contain a series of elements named after the array type Employee.

Public Class Group
    Public Employees() As Employee
End Class
Public Class Employee
    Public Name As String
End Class
public class Group {
    public Employee[] Employees;
}
public class Employee {
    public string Name;
}

Сериализованный экземпляр может выглядеть следующим образом.A serialized instance might resemble the following.

<Group>
<Employees>
    <Employee>
        <Name>Haley</Name>
    </Employee>
</Employees>
</Group>

Применив XmlArrayAttribute, можно изменить имя элемента XML.By applying a XmlArrayAttribute, you can change the name of the XML element, as follows.

Public Class Group
    <XmlArray("TeamMembers")> _
    Public Employees() As Employee
End Class
public class Group {
    [XmlArray("TeamMembers")]
    public Employee[] Employees;
}

Итоговый XML-код может иметь следующий вид.The resulting XML might resemble the following.

<Group>
<TeamMembers>
    <Employee>
        <Name>Haley</Name>
    </Employee>
</TeamMembers>
</Group>

С другой стороны, атрибут XmlArrayItemAttribute управляет способом сериализации элементов в массиве.The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. Обратите внимание, что атрибут применен к полю, возвращающему массив.Note that the attribute is applied to the field returning the array.

Public Class Group
    <XmlArrayItem("MemberName")> _
    Public Employee() As Employees
End Class
public class Group {
    [XmlArrayItem("MemberName")]
    public Employee[] Employees;
}

Итоговый XML-код может иметь следующий вид.The resulting XML might resemble the following.

<Group>
<Employees>
    <MemberName>Haley</MemberName>
</Employees>
</Group>

Сериализация производных классовSerializing Derived Classes

Другим способом использования XmlArrayItemAttribute является разрешение сериализации производных классов.Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. Например, другой класс с именем Manager, унаследованный от Employee, можно добавить в предыдущий пример.For example, another class named Manager that derives from Employee can be added to the previous example. Если не применять XmlArrayItemAttribute, при выполнении кода возникнет сбой, поскольку тип производного класса не будет распознан.If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. Чтобы это исправить, примените атрибут дважды, при каждой настройке свойства Type для каждого допустимого типа (базового и производного).To remedy this, apply the attribute twice, each time setting the Type property for each acceptable type (base and derived).

Public Class Group
    <XmlArrayItem(Type:=GetType(Employee)), _
    XmlArrayItem(Type:=GetType(Manager))> _
    Public Employees() As Employee
End Class
Public Class Employee
    Public Name As String
End Class
Public Class Manager
Inherits Employee
    Public Level As Integer
End Class
public class Group {
    [XmlArrayItem(Type = typeof(Employee)),
    XmlArrayItem(Type = typeof(Manager))]
    public Employee[] Employees;
}
public class Employee {
    public string Name;
}
public class Manager:Employee {
    public int Level;
}

Сериализованный экземпляр может выглядеть следующим образом.A serialized instance might resemble the following.

<Group>
<Employees>
    <Employee>
        <Name>Haley</Name>
    </Employee>
    <Employee xsi:type = "Manager">
        <Name>Ann</Name>
        <Level>3</Level>
    <Employee>
</Employees>
</Group>

Сериализация массива как последовательности элементовSerializing an Array as a Sequence of Elements

Также предусмотрена возможность сериализации массива как плоской последовательности элементов XML путем применения XmlElementAttribute к полю, возвращающему массив следующим образом.You can also serialize an array as a flat sequence of XML elements by applying a XmlElementAttribute to the field returning the array as follows.

Public Class Group
    <XmlElement> _
    Public Employees() As Employee
End Class
public class Group {
    [XmlElement]
    public Employee[] Employees;
}

Сериализованный экземпляр может выглядеть следующим образом.A serialized instance might resemble the following.

<Group>
<Employees>
    <Name>Haley</Name>
</Employees>
<Employees>
    <Name>Noriko</Name>
</Employees>
<Employees>
    <Name>Marco</Name>
</Employees>
</Group>

Другим способом различения двух потоков XML является использование инструмента определения схемы XML, с помощью которого создаются файлы документов схемы XML (XSD) из скомпилированного кода.Another way to differentiate the two XML streams is to use the XML Schema Definition tool to generate the XML Schema (XSD) document files from the compiled code. (Дополнительные сведения по использованию этого средства см. в разделе Инструмент определения схемы XML и сериализация XML.) Если к полю не применяется никакой атрибут, схема описывает элемент следующим образом.(For more details on using the tool, see The XML Schema Definition Tool and XML Serialization.) When no attribute is applied to the field, the schema describes the element in the following manner.

<xs:element minOccurs="0" maxOccurs ="1" name="Employees" type="ArrayOfEmployee" />

Если к полю применяется XmlElementAttribute, итоговая схема описывает элемент следующим образом.When the XmlElementAttribute is applied to the field, the resulting schema describes the element as follows.

<xs:element minOccurs="0" maxOccurs="unbounded" name="Employees" type="Employee" /> 

Сериализация ArrayListSerializing an ArrayList

Класс ArrayList может содержать коллекцию различных объектов.The ArrayList class can contain a collection of diverse objects. Поэтому ArrayList можно использовать в том же объеме, что и массив.You can therefore use a ArrayList much as you use an array. Однако вместо создания поля, возвращающего массив типизированных объектов, можно создать поле, которое возвращает один ArrayList.Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. Но как и для массивов, XmlSerializer следует указать типы объектов, которые содержит ArrayList.However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. Для этого необходимо назначить для поля несколько экземпляров XmlElementAttribute, как показано в следующем примере.To accomplish this, assign multiple instances of the XmlElementAttribute to the field, as shown in the following example.

Public Class Group
    <XmlElement(Type:=GetType(Employee)), _
    XmlElement(Type:=GetType(Manager))> _
    Public Info As ArrayList
End Class
public class Group {
    [XmlElement(Type = typeof(Employee)), 
    XmlElement(Type = typeof(Manager))]
    public ArrayList Info;
}

Управление сериализацией классов с использованием атрибутов XmlRootAttribute и XmlTypeAttributeControlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

К классу (и только к одному классу) можно применить два атрибута: XmlRootAttribute и XmlTypeAttribute.There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. Эти атрибуты в значительной степени схожи.These attributes are very similar. Атрибут XmlRootAttribute можно применить только к одному классу, классу, который при сериализации представляет открывающий и закрывающий элемент документа XML, другими словами, корневой элемент.The XmlRootAttribute can be applied to only one class: the class that, when serialized, represents the XML document's opening and closing element—in other words, the root element. С другой стороны, атрибут XmlTypeAttribute можно применить к любому классу, включая корневой.The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

В предыдущих примерах класс Group является корневым, и все его открытые поля и свойства становятся элементами XML, находящимися в документе XML.For example, in the previous examples, the Group class is the root class, and all its public fields and properties become the XML elements found in the XML document. Поэтому может существовать только один корневой класс.Therefore, there can be only one root class. Применяя XmlRootAttribute, можно управлять потоком XML, созданным с помощью XmlSerializer.By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. Например, можно изменить имя элемента и пространство имен.For example, you can change the element name and namespace.

Атрибут XmlTypeAttribute обеспечивает управление схемой созданного XML.The XmlTypeAttribute allows you to control the schema of the generated XML. Такая возможность полезна, когда необходимо опубликовать схему через XML-веб-службу.This capability is useful when you need to publish the schema through an XML Web service. В следующем примере применяются XmlTypeAttribute и XmlRootAttribute к одному и тому же классу.The following example applies both the XmlTypeAttribute and the XmlRootAttribute to the same class.

<XmlRoot("NewGroupName"), _
XmlType("NewTypeName")> _
Public Class Group
    Public Employees() As Employee
End Class
[XmlRoot("NewGroupName")]
[XmlType("NewTypeName")]
public class Group {
    public Employee[] Employees;
}

При компилировании этого класса и использовании инструмента определения схемы XML для создания этой схемы следующий XML будет описывать Group.If this class is compiled, and the XML Schema Definition tool is used to generate its schema, you would find the following XML describing Group.

<xs:element name="NewGroupName" type="NewTypeName">

В противоположность этому, если бы выполнялась сериализация экземпляра класса, в документе XML хранилось бы только NewGroupName.In contrast, if you were to serialize an instance of the class, only NewGroupName would be found in the XML document.

<NewGroupName>
    . . .
</NewGroupName>

Предотвращение сериализации с атрибутом XmlIgnoreAttributePreventing Serialization with the XmlIgnoreAttribute

Возможны ситуации, в которых не требуется сериализация открытого свойства или поля.There might be situations when a public property or field does not need to be serialized. Например, поле или свойство могут использоваться для хранения метаданных.For example, a field or property could be used to contain metadata. В таких случаях примените к полю или свойству XmlIgnoreAttribute, и XmlSerializer его пропустит.In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

См. такжеSee also