使用屬性控制 XML 序列化

  • 發行項

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

注意

如果產生的 XML 必須符合全球資訊網協會 (W3C) 文件簡易物件存取通訊協定 (SOAP) 1.1 的第 5 節，請使用可控制編碼 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) 如何透過設定XmlElementAttribute的ElementName屬性 (Property) 來啟用此功能。

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

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

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

控制陣列序列化

XmlArrayAttribute 與 XmlArrayItemAttribute 屬性可控制陣列序列化。 使用這些屬性，您可控制項目名稱、命名空間以及 XML 結構描述 (XSD) 資料型別 (如 W3C 文件 XML Schema Part 2: Datatypes 中所定義)。 您也可以指定陣列能包含的類型。

XmlArrayAttribute 將決定當陣列序列化時，封入 XML 項目的屬性。 例如，依預設，序列化以下的陣列將產生名為 Employees 的 XML 項目。 Employees 項目將包含一系列根據陣列類型 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;
}

將執行個體序列化，可能類似於下列程式碼：

<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。 不過，若不想建立會傳回型別物件陣列的欄位，可建立傳回單一 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 控制類別的序列化

您只能將兩個屬性套用至類別：XmlRootAttribute和XmlTypeAttribute。 這些屬性類似。 XmlRootAttribute 僅能套用至一類別：在序列化後此類別代表 XML 文件開啟與關閉的項目，換句話說就是根項目。 另一方面，XmlTypeAttribute 可套用至任何類別，包括根類別。

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

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

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

另請參閱