Steuern der XML-Serialisierung mit AttributenControlling XML Serialization Using Attributes

Attribute können verwendet werden, um die XML-Serialisierung eines Objekts zu steuern oder um einen alternativen XML-Stream aus derselben Reihe von Klassen zu erstellen.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. Weitere Informationen zum Erstellen eines alternativen XML-Streams finden Sie unter Vorgehensweise: Angeben ein alternativen Elementnamens für einen XML-Stream.For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

Hinweis

Wenn der generierte XML-Abschnitt 5 des World Wide Web Consortium (W3C) Dokuments entsprechen soll einfache Object Access Protocol (SOAP) 1.1, verwenden Sie die Attribute aufgeführt, die Attribute, Steuerelement codierten SOAP Serialisierung.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.

Standardmäßig wird der Name eines XML-Elements durch den Klassen- oder Membernamen festgelegt.By default, an XML element name is determined by the class or member name. In einer einfachen Klasse namens Book wird, wie in folgendem Beispiel gezeigt, durch ein Feld mit der Bezeichnung ISBN ein XML-Elementtag <ISBN> erstellt.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>.

Sie können dieses Standardverhalten ändern, wenn Sie das Element umbenennen möchten.This default behavior can be changed if you want to give the element a new name. Der folgende Code veranschaulicht, wie ein Attribut die Änderung durch das Festlegen der ElementName-Eigenschaft von XmlElementAttribute ermöglicht.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;
}

Weitere Informationen zu Attributen finden Sie unter Attribute.For more information about attributes, see Attributes. Eine Liste mit Attributen zur Steuerung der XML-Serialisierung finden Sie unter Attribute zur Steuerung der XML-Serialisierung.For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

Steuern der Serialisierung von ArraysControlling Array Serialization

Die Attribute XmlArrayAttribute und XmlArrayItemAttribute dienen zum Steuern der Serialisierung von Arrays.The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. Mit diesen Attributen können Sie den Namen, Namespace und Datentyp für die XML-Schema (XSD) steuern (gemäß der World Wide Web Consortium [www.w3.org]-Dokument mit dem Titel "XML Schema Part 2: Datatypes").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"). Sie können auch die Typen angeben, die in einem Array enthalten sein können.You can also specify the types that can be included in an array.

Durch XmlArrayAttribute werden die Eigenschaften des einschließenden XML-Elements bestimmt, das aus der Serialisierung eines Arrays hervorgeht.The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. So wird beispielsweise durch das Serialisieren des unten aufgeführten Arrays standardmäßig ein XML-Element mit der Bezeichnung Employees erzeugt.For example, by default, serializing the array below will result in an XML element named Employees. Das Employees-Element enthält eine Reihe von Elementen, die nach dem Arraytyp Employee benannt sind.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;
}

Eine serialisierte Instanz könnte etwa wie folgt aussehen.A serialized instance might resemble the following.

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

Sie können den Namen des XML-Elements wie folgt ändern, indem Sie XmlArrayAttribute anwenden.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;
}

Der resultierende XML-Stream könnte wie folgt aussehen.The resulting XML might resemble the following.

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

Andererseits steuert XmlArrayItemAttribute, wie die im Array enthaltenen Elemente serialisiert werden.The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. Beachten Sie, dass das Attribut auf das Feld angewendet wird, das vom Array zurückgegeben wird.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;
}

Der resultierende XML-Stream könnte wie folgt aussehen.The resulting XML might resemble the following.

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

Serialisieren von abgeleiteten KlassenSerializing Derived Classes

Außerdem ermöglicht XmlArrayItemAttribute die Serialisierung abgeleiteter Klassen.Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. Zum Beispiel kann eine weitere Klasse mit der Bezeichnung Manager, die von Employee abgeleitet wird, dem vorigen Beispiel hinzugefügt werden.For example, another class named Manager that derives from Employee can be added to the previous example. Wenn Sie XmlArrayItemAttribute nicht anwenden, schlägt der Code zur Laufzeit fehl, weil der abgeleitete Klassentyp nicht erkannt wird.If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. Um dieses Problem zu beheben, wenden Sie das Attribut zweimal an, und legen Sie jedes Mal die Type-Eigenschaft für jeden zulässigen Typ (Basisklasse und abgeleitete Klasse) fest.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;
}

Eine serialisierte Instanz könnte etwa wie folgt aussehen.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>

Serialisieren eines Arrays als Abfolge von ElementenSerializing an Array as a Sequence of Elements

Sie können ein Array auch als eine flache Abfolge von XML-Elementen serialisieren, indem Sie XmlElementAttribute auf das Feld anwenden, sodass das Array wie folgt zurückgegeben wird.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;
}

Eine serialisierte Instanz könnte etwa wie folgt aussehen.A serialized instance might resemble the following.

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

Eine weitere Möglichkeit, die beiden XML-Streams zu unterscheiden, besteht in der Verwendung des Tools für die XML-Schemadefinition zur Generierung der XML-Schemadokumentdateien (XSD) aus dem kompilierten Code.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. (Nähere Informationen zur Verwendung dieses Tools finden Sie unter Das XML Schema Definition-Tool und die XML-Serialisierung.) Wenn keine Attribute auf das Feld angewendet werden, wird das Element auf die folgende Weise durch das Schema beschrieben.(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" />

Wird XmlElementAttribute auf das Feld angewendet, wird das Element durch das resultierende Schema auf folgende Weise beschrieben.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" /> 

Serialisieren einer ArrayList-KlasseSerializing an ArrayList

Die ArrayList-Klasse kann eine Auflistung verschiedenartiger Objekte enthalten.The ArrayList class can contain a collection of diverse objects. Daher können Sie eine ArrayList-Klasse wie ein Array verwenden.You can therefore use a ArrayList much as you use an array. Statt ein Feld zu erstellen, das ein Array von Objekten mit Typbindung zurückgibt, können Sie auch ein Feld erstellen, das ein einzelnes ArrayList-Objekt zurückgibt.Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. Ebenso wie mit Arrays müssen Sie die XmlSerializer-Klasse jedoch über die Typen der in der ArrayList-Klasse enthaltenen Objekte informieren.However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. Hierzu müssen Sie dem Feld mehrere Instanzen von XmlElementAttribute zuweisen, wie im folgenden Beispiel gezeigt wird.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;
}

Kontrollieren von Serialisierung von Klassen mit den Attributen XmlRootAttribute und XmlTypeAttributeControlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

Es gibt zwei Attribute, die (ausschließlich) auf Klassen angewendet werden können: XmlRootAttribute und XmlTypeAttribute.There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. Diese Attribute sind sich sehr ähnlich.These attributes are very similar. XmlRootAttribute kann nur auf eine einzige Klasse angewendet werden: auf die Klasse, die bei Serialisierung das öffnende und schließende Element, d.&amp;#160;h. das Stammelement, darstellt.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 kann dagegen auf beliebige Klassen einschließlich der Stammklasse angewendet werden.The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

So ist beispielsweise im vorigen Beispiel die Group-Klasse die Stammklasse, und alle ihre öffentlichen Felder und Eigenschaften werden zu XML-Elementen, die im XML-Dokument enthalten sind.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. Es kann daher nur eine Stammklasse geben.Therefore, there can be only one root class. Durch die Anwendung von XmlRootAttribute können Sie den von XmlSerializer generierten XML-Stream steuern.By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. Beispielsweise können Sie den Elementnamen und den Namespace ändern.For example, you can change the element name and namespace.

XmlTypeAttribute ermöglicht es Ihnen, das Schema des generierten XML-Streams zu steuern.The XmlTypeAttribute allows you to control the schema of the generated XML. Diese Fähigkeit ist hilfreich, wenn Sie das Schema über einen XML-Webdienst veröffentlichen müssen.This capability is useful when you need to publish the schema through an XML Web service. Im folgenden Beispiel werden das XmlTypeAttribute-Attribut und das XmlRootAttribute-Attribut auf dieselbe Klasse angewendet.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;
}

Wenn diese Klasse kompiliert wird und ihr Schema mit dem XML Schema Definition-Tool generiert wurde, erhalten Sie als Beschreibung von Group den folgenden XML-Stream.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">

Wenn Sie dagegen eine Instanz der Klasse serialisieren würden, würde das XML-Dokument lediglich NewGroupName enthalten.In contrast, if you were to serialize an instance of the class, only NewGroupName would be found in the XML document.

<NewGroupName>
    . . .
</NewGroupName>

Verhindern der Serialisierung mit dem Attribut XmlIgnoreAttributePreventing Serialization with the XmlIgnoreAttribute

Es kann vorkommen, dass eine öffentliche Eigenschaft oder ein öffentliches Feld nicht serialisiert werden muss.There might be situations when a public property or field does not need to be serialized. Zum Beispiel konnte ein Feld oder eine Eigenschaft zum Speichern von Metadaten verwendet werden.For example, a field or property could be used to contain metadata. Wenden Sie in diesen Fällen XmlIgnoreAttribute auf das Feld oder die Eigenschaft an. XmlSerializer überspringt dann das Feld bzw. die Eigenschaft.In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

Siehe auchSee also