使用屬性控制 XML 序列化

發行項
03/12/2024

屬性可用來控制物件的 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。

共用方式為

使用屬性控制 XML 序列化

控制陣列序列化

序列化衍生類別

序列化陣列成為項目序列

序列化 ArrayList

使用 XmlRootAttribute 與 XmlTypeAttribute 控制類別的序列化

避免以 XmlIgnoreAttribute 序列化

另請參閱

其他資源