使用屬性控制 XML 序列化

屬性可用來控制物件的 XML 序列化或從相同的類別集建立其他的 XML 資料流。 如需建立替代 XML 資料流的詳細資料,請參閱如何:指定 XML 資料流的替代項目名稱

注意

如果產生的 XML 必須符合全球資訊網協會第 5 節, (W3C) 標題為 Simple Object Access Protocol (SOAP) 1.1的檔,請使用 控制編碼 SOAP 序列化的屬性中列出的屬性。

根據預設,XML 項目名稱是由類別或成員名稱決定。 在名為 Book 的簡單類別中,名為 ISBN 的欄位會產生 XML 元素標記 < ISBN > ,如下列範例所示。

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

若想指定項目一個新的名稱,可以變更此預設行為。 下列程式碼顯示一個屬性 (Attribute) 如何透過設定 的 屬性 (Property),達成這個目標。

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

如需屬性的詳細資訊,請參閱屬性。 如需控制 XML 序列化的屬性清單,請參閱可控制 XML 序列化的屬性

控制陣列序列化

XmlArrayAttributeXmlArrayItemAttribute 屬性是針對陣列序列化控制而設計。 使用這些屬性,您可控制項目名稱、命名空間以及 XML 結構描述 (XSD) 資料型別 (如全球資訊網協會 [www.w3.org] 文件<XML Schema Part 2: Datatypes>中所定義)。 您也可以指定陣列能包含的類型。

XmlArrayAttribute 將決定當陣列序列化時,封入 XML 項目的屬性。 例如,依預設,序列化以下的陣列將產生名為 Employees 的 XML 項目。 項目將包含一系列根據陣列類型 命名的項目。

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

序列化的執行個體可能類似於下列項目。

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

套用 XmlArrayAttribute,您可變更 XML 項目的名稱,如下所示。

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

產生的 XML 可能類似下列所示。

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

另一方面,XmlArrayItemAttribute 控制陣列包含的項目如何序列化。 請注意,屬性會套用至傳回陣列的欄位。

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

產生的 XML 可能類似下列所示。

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

序列化衍生類別

XmlArrayItemAttribute 的另一用途,是允許衍生類別的序列化。 例如,另一個衍生自 Manager 名為 Employee 的類別,可加入前面的範例。 若您不套用 XmlArrayItemAttribute,由於無法識別衍生類別型別,程式碼將在執行階段失敗。 若要修正此狀況,請套用屬性兩次,每次都針對每個可接受的型別 (基底與衍生) 設定 Type 屬性。

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

序列化的執行個體可能類似於下列項目。

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

序列化陣列成為項目序列

您也可以套用 XmlElementAttribute 至傳回陣列的欄位 (如下所示),將陣列序列化成為 XML 項目的平面序列。

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

序列化的執行個體可能類似於下列項目。

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

另一種區別這兩種 XML 資料流的方法是使用 XML 結構描述定義工具,從編譯的程式碼中產生 XML 結構描述 (XSD) 文件檔案 (如需使用工具的詳細資訊,請參閱 XML 架構定義工具和 XML 序列化.) 當沒有屬性套用至欄位時,架構會以下列方式描述元素。

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

XmlElementAttribute 套用至欄位時,產生的結構描述說明項目如下。

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

序列化 ArrayList

ArrayList 類別可包含各種不同物件的集合。 因此,您可以盡可能使用 ArrayList 陣列。 不過,若不想建立會傳回型別物件陣列的欄位,可建立傳回單一 的欄位。 不過,與陣列一樣,您必須將 XmlSerializer 包含的物件類型告知 ArrayList。 若要達成這個目的,請指派多個 XmlElementAttribute 執行個體至欄位,如下面的範例所示。

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 與 XmlTypeAttribute 控制類別的序列化

有兩種屬性可套用至類別 (只有一種類別):XmlRootAttributeXmlTypeAttribute。 這些屬性非常類似。 XmlRootAttribute 僅能套用至一類別:在序列化後此類別代表 XML 文件開啟與關閉的項目,換句話說就是根項目。 另一方面,XmlTypeAttribute 可套用至任何類別,包括根類別。

例如,在前述的範例中,Group 類別為根類別,它所有的公用欄位與屬性成為在 XML 文件中發現的 XML 項目。 因此,只能有一個根類別。 藉由套用 ,您可用 控制產生的 XML 資料流。 例如,您可變更項目名稱與命名空間。

XmlTypeAttribute 允許您控制產生之 XML 的結構描述。 當您需要透過 XML Web 服務發怖此結構描述時,此能力就很重要。 下列範例會將 和 套用至相同類別。

<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

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

相反地,若您要序列化類別的執行個體,在 XML 文件中只會發現 NewGroupName

<NewGroupName>
    . . .
</NewGroupName>

避免以 XmlIgnoreAttribute 序列化

也有可能不需將公用屬性或欄位序列化的狀況。 例如,欄位或屬性可用來包含中繼資料。 在這樣的情況下,套用 XmlIgnoreAttribute 至欄位或屬性,且將略過 XmlSerializer

另請參閱