Kontrolowanie serializacji XML przy użyciu atrybutów

  • Artykuł

Atrybuty można kontrolować serializacji XML obiektu lub utworzyć alternatywny strumień XML z tego samego zestawu klas. Aby uzyskać więcej informacji na temat tworzenia alternatywnego strumienia XML, zobacz How to: Specify an Alternate Element Name for an XML Stream (Instrukcje: określanie alternatywnej nazwy elementu dla strumienia XML).

Uwaga

Jeśli wygenerowany kod XML musi być zgodny z sekcją 5 dokumentu World Wide Web Consortium (W3C) zatytułowanym Simple Object Access Protocol (SOAP) 1.1, użyj atrybutów wymienionych w temacie Attributes That Control Encoded SOAP Serialization (Attributes That Control Encoded SOAP Serialization).

Domyślnie nazwa elementu XML jest określana przez nazwę klasy lub składowej. W klasie o nazwie pole o nazwie BookISBN spowoduje wygenerowanie tagu <ISBN>elementu XML, jak pokazano w poniższym przykładzie:

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

Domyślne zachowanie można zmienić, jeśli chcesz nadać elementowi nową nazwę. Poniższy kod pokazuje, jak atrybut włącza tę funkcję, ustawiając ElementName właściwość elementu XmlElementAttribute:

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

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

Aby uzyskać więcej informacji na temat atrybutów, zobacz Atrybuty. Aby uzyskać listę atrybutów kontrolujących serializacji XML, zobacz Atrybuty kontrolujące serializacji XML.

Kontrolowanie serializacji tablicy

Atrybuty XmlArrayAttribute i XmlArrayItemAttribute kontrolują serializacji tablic. Korzystając z tych atrybutów, można kontrolować nazwę elementu, przestrzeń nazw i typ danych schematu XML (XSD) zgodnie z definicją w dokumencie W3C zatytułowanym Schemat XML Część 2: Typy danych. Można również określić typy, które mogły zostać uwzględnione w tablicy.

XmlArrayAttribute Ustali właściwości otaczającego element XML, który powstaje wtedy, gdy jest serializowana tablicy. Na przykład domyślnie serializowanie poniższej tablicy spowoduje powstanie elementu XML o nazwie Employees. Employees Element będzie zawierać szereg elementów o nazwie po typ tablicy 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;
}

Serializowane wystąpienie może przypominać następujący kod:

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

Stosując element XmlArrayAttribute, można zmienić nazwę elementu XML w następujący sposób:

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

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

Wynikowy kod XML może przypominać następujący kod:

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

XmlArrayItemAttribute, Z drugiej strony, określa, jak są serializacji elementów znajdujących się w tablicy.

Uwaga

Atrybut jest stosowany do pola zwracającego tablicę.

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

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

Wynikowy kod XML może przypominać następujący kod:

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

Klasy pochodne serializacji

Używanie innego XmlArrayItemAttribute jest umożliwienie serializacji w klasach pochodnych. Na przykład do poprzedniego przykładu można dodać inną klasę o nazwie Manager , która pochodzi z Employee klasy . Jeśli nie zastosujesz XmlArrayItemAttributeklasy , kod zakończy się niepowodzeniem w czasie wykonywania, ponieważ typ klasy pochodnej nie zostanie rozpoznany. Aby rozwiązać ten wynik, zastosuj atrybut dwa razy, za każdym razem ustawiając Type właściwość dla każdego dopuszczalnego typu (podstawowego i pochodnego).

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

Serializowane wystąpienie może przypominać następujący kod:

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

Szeregowanie tablicę jako sekwencję elementów

Można również serializować tablicę jako płaską sekwencję elementów XML, stosując element do XmlElementAttribute pola zwracającego tablicę w następujący sposób:

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

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

Serializowane wystąpienie może przypominać następujący kod:

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

W inny sposób do odróżniania dwóch strumieni XML jest do generowania PLików dokumentów schematu XML (XSD) z skompilowany kod za pomocą narzędzia definicji schematu XML. Aby uzyskać więcej informacji na temat korzystania z narzędzia, zobacz Narzędzie definicji schematu XML i serializacja XML. Jeśli do pola nie zastosowano żadnego atrybutu, schemat opisuje element w następujący sposób:

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

XmlElementAttribute Po zastosowaniu elementu do pola wynikowy schemat opisuje element w następujący sposób:

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

Serializacji ArrayList

ArrayList Klasy może zawierać kolekcji różnych obiektów. W związku z tym można użyć ArrayList tablicy. Używaj pola, która zwraca tablicę obiektów określonego typu, jednak można utworzyć pole, które zwraca pojedynczą ArrayList. Jednak, podobnie jak w przypadku tablic, musi powiadomić XmlSerializer typów obiektów ArrayList zawiera. Aby to osiągnąć, przypisz wiele wystąpień XmlElementAttribute obiektu do pola, jak pokazano w poniższym przykładzie.

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

Kontrolowanie serializacji klas przy użyciu XmlRootAttribute i XmlTypeAttribute

Do klasy można zastosować tylko dwa atrybuty: XmlRootAttribute i XmlTypeAttribute. Te atrybuty są podobne. Można XmlRootAttribute go zastosować tylko do jednej klasy: klasy, która po serializacji reprezentuje element otwierający i zamykający dokumentu XML — innymi słowy, element główny. Z XmlTypeAttributedrugiej strony element można zastosować do dowolnej klasy, w tym klasy głównej.

Na przykład w poprzednich przykładach Group klasa jest klasą główną, a wszystkie jej pola publiczne i właściwości stają się elementami XML znajdującymi się w dokumencie XML. W związku z tym można mieć tylko jedną klasę główną. Stosując element XmlRootAttribute, można kontrolować strumień XML wygenerowany przez element XmlSerializer. Można na przykład zmienić nazwę elementu i przestrzeń nazw.

XmlTypeAttribute Umożliwia sterowanie schemat wygenerowanego kodu XML. Ta funkcja jest przydatne, gdy należy opublikować schematu za pomocą usługi sieci Web XML. Poniższy przykład dotyczy zarówno klasy , jak XmlTypeAttribute i XmlRootAttribute do tej samej klasy:

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

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

Jeśli ta klasa jest kompilowana, a narzędzie definicji schematu XML jest używane do generowania jego schematu, można znaleźć następujący kod XML opisujący Group:

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

Natomiast w przypadku serializacji wystąpienia klasy można znaleźć tylko NewGroupName w dokumencie XML:

<NewGroupName>
    . . .
</NewGroupName>

Zapobieganie serializacji z XmlIgnoreAttribute

Może wystąpić sytuacja, w której właściwość publiczna lub pole nie musi być serializowane. Na przykład można użyć pola lub właściwości do przechowywania metadanych. W takich przypadkach zastosuj element XmlIgnoreAttribute do pola lub właściwości, a właściwość zostanie pominięta XmlSerializer .

Zobacz też