Share via

XML-serialisatie beheren met behulp van kenmerken

  • Artikel

Kenmerken kunnen worden gebruikt om de XML-serialisatie van een object te beheren of om een alternatieve XML-stroom te maken op basis van dezelfde set klassen. Zie Instructies voor het maken van een alternatieve XML-stroom voor meer informatie over het maken van een alternatieve XML-stroom : Geef een alternatieve elementnaam op voor een XML-stroom.

Notitie

Als de gegenereerde XML moet voldoen aan sectie 5 van het W3C-document (World Wide Web Consortium), getiteld SOAP (Simple Object Access Protocol) 1.1, gebruikt u de kenmerken die worden vermeld in Kenmerken die SOAP-serialisatie beheren.

Standaard wordt een XML-elementnaam bepaald door de klasse- of lidnaam. In een klasse genaamd Bookproduceert een veld met de naam ISBN een XML-elementtag <ISBN>, zoals wordt weergegeven in het volgende voorbeeld:

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>.

Het standaardgedrag kan worden gewijzigd als u het element een nieuwe naam wilt geven. De volgende code laat zien hoe een kenmerk deze functionaliteit inschakelt door de ElementName eigenschap van een XmlElementAttribute:

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class

public class TaxRates {
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Zie Kenmerken voor meer informatie over kenmerken. Zie Kenmerken die XML-serialisatie beheren voor een lijst met kenmerken die XML-serialisatie beheren.

Matrixserialisatie beheren

De XmlArrayAttribute en de XmlArrayItemAttribute kenmerken bepalen de serialisatie van matrices. Met deze kenmerken kunt u het gegevenstype elementnaam, naamruimte en XML-schema (XSD) beheren zoals gedefinieerd in het W3C-document met de titel XML-schema deel 2: Gegevenstypen. U kunt ook de typen opgeven die in een matrix kunnen worden opgenomen.

Hiermee XmlArrayAttribute bepaalt u de eigenschappen van het ingesloten XML-element dat resulteert wanneer een matrix wordt geserialiseerd. Het serialiseren van de onderstaande matrix resulteert bijvoorbeeld standaard in een XML-element met de naam Employees. Het Employees element bevat een reeks elementen die zijn vernoemd naar het matrixtype 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;
}

Een geserialiseerd exemplaar lijkt mogelijk op de volgende code:

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

Door een XmlArrayAttributetoe te passen, kunt u de naam van het XML-element als volgt wijzigen:

Public Class Group
    <XmlArray("TeamMembers")> _
    Public Employees() As Employee
End Class

public class Group {
    [XmlArray("TeamMembers")]
    public Employee[] Employees;
}

De resulterende XML kan lijken op de volgende code:

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

Aan XmlArrayItemAttributede andere kant bepaalt u hoe de items in de matrix worden geserialiseerd.

Notitie

Het kenmerk wordt toegepast op het veld dat de matrix retourneert.

Public Class Group
    <XmlArrayItem("MemberName")> _
    Public Employee() As Employees
End Class

public class Group {
    [XmlArrayItem("MemberName")]
    public Employee[] Employees;
}

De resulterende XML kan lijken op de volgende code:

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

Afgeleide klassen serialiseren

Een ander gebruik van de XmlArrayItemAttribute is om de serialisatie van afgeleide klassen toe te staan. Een andere klasse Manager die is afgeleid van Employee , kan bijvoorbeeld worden toegevoegd aan het vorige voorbeeld. Als u de XmlArrayItemAttributecode niet toepast, mislukt de code tijdens de runtime omdat het afgeleide klassetype niet wordt herkend. Als u dit resultaat wilt verhelpen, past u het kenmerk twee keer toe, telkens wanneer u de Type eigenschap instelt voor elk acceptabel type (basis en afgeleid).

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;
}

Een geserialiseerd exemplaar lijkt mogelijk op de volgende code:

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

Een matrix serialiseren als een reeks elementen

U kunt een matrix ook serialiseren als een platte reeks XML-elementen door een XmlElementAttribute op het veld toe te passen dat de matrix als volgt retourneert:

Public Class Group
    <XmlElement> _
    Public Employees() As Employee
End Class

public class Group {
    [XmlElement]
    public Employee[] Employees;
}

Een geserialiseerd exemplaar lijkt mogelijk op de volgende code:

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

Een andere manier om onderscheid te maken tussen de twee XML-stromen, is door het hulpprogramma XML-schemadefinitie te gebruiken om de XML-schemadocumentbestanden (XSD) te genereren op basis van de gecompileerde code. Zie het hulpprogramma XML-schemadefinitie en XML-serialisatie voor meer informatie over het gebruik van het hulpprogramma. Wanneer er geen kenmerk wordt toegepast op het veld, wordt in het schema het element op de volgende manier beschreven:

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

Wanneer het XmlElementAttribute veld wordt toegepast, beschrijft het resulterende schema het element als volgt:

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

Een matrixlijst serialiseren

De ArrayList klasse kan een verzameling verschillende objecten bevatten. U kunt daarom veel ArrayList gebruiken als u een matrix gebruikt. In plaats van een veld te maken dat een matrix met getypte objecten retourneert, kunt u echter een veld maken dat één ArrayListveld retourneert. Net als bij matrices moet u echter informeren XmlSerializer over de typen objecten die de ArrayList objecten bevatten. Wijs hiervoor meerdere exemplaren van het XmlElementAttribute veld toe, zoals wordt weergegeven in het volgende voorbeeld.

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;
}

Serialisatie van klassen beheren met xmlRootAttribute en XmlTypeAttribute

U kunt twee kenmerken alleen toepassen op een klasse: XmlRootAttribute en XmlTypeAttribute. Deze kenmerken zijn vergelijkbaar. De XmlRootAttribute kan worden toegepast op slechts één klasse: de klasse die, wanneer het wordt geserialiseerd, het openen en sluiten van het XML-document vertegenwoordigt, met andere woorden het hoofdelement. De XmlTypeAttribute, daarentegen, kan worden toegepast op elke klasse, met inbegrip van de hoofdklasse.

In de vorige voorbeelden is de klasse bijvoorbeeld de Group hoofdklasse en worden alle openbare velden en eigenschappen de XML-elementen in het XML-document. Daarom kunt u slechts één hoofdklasse hebben. Door de XmlRootAttributetoe te passen, kunt u de XML-stroom beheren die door de XmlSerializer. U kunt bijvoorbeeld de elementnaam en naamruimte wijzigen.

Hiermee XmlTypeAttribute kunt u het schema van de gegenereerde XML beheren. Deze mogelijkheid is handig wanneer u het schema moet publiceren via een XML-webservice. In het volgende voorbeeld worden zowel de XmlTypeAttribute als de XmlRootAttribute klasse toegepast op dezelfde klasse:

<XmlRoot("NewGroupName"), _
XmlType("NewTypeName")> _
Public Class Group
    Public Employees() As Employee
End Class

[XmlRoot("NewGroupName")]
[XmlType("NewTypeName")]
public class Group {
    public Employee[] Employees;
}

Als deze klasse is gecompileerd en het hulpprogramma XML-schemadefinitie wordt gebruikt om het schema te genereren, vindt u de volgende XML-beschrijving Group:

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

Als u daarentegen een exemplaar van de klasse serialiseert, vindt u alleen NewGroupName in het XML-document:

<NewGroupName>
    . . .
</NewGroupName>

Serialisatie voorkomen met xmlIgnoreAttribute

U kunt een situatie tegenkomen waarin een openbare eigenschap of veld niet hoeft te worden geserialiseerd. Een veld of eigenschap kan bijvoorbeeld worden gebruikt om metagegevens te bevatten. In dergelijke gevallen past u het veld of de XmlIgnoreAttribute eigenschap toe en wordt het XmlSerializer overgeslagen.

Zie ook