結構描述匯入和匯出

發行項
03/13/2024

Windows Communication Foundation (WCF) 包含新的序列化引擎 DataContractSerializer。 DataContractSerializer 可在 .NET Framework 物件與 XML 之間雙向轉譯。除了序列化程式本身，WCF 還包含關聯的結構描述匯入與結構描述匯出機制。「結構描述」是序列化程式所產生或還原序列化程式可存取之 XML 形式的正式、精確且可供電腦讀取的描述。 WCF 使用「全球資訊網協會」(W3C) XML 結構描述定義 (XSD) 語言做為其結構描述表示，該語言可廣泛地在許多協力廠商平台互通。

結構描述匯入元件 XsdDataContractImporter 會接受 XSD 結構描述文件，並產生 .NET Framework 類別 (通常是資料合約類別)，讓序列化的表單對應至指定的結構描述。

例如，下列結構描述片段：

XsdDataContractImporter importer = new XsdDataContractImporter();
importer.Options.Namespaces.Add(new KeyValuePair<string, string>("http://schemas.contoso.com/carSchema", "Contoso.Cars"));

Dim importer As New XsdDataContractImporter
importer.Options.Namespaces.Add(New KeyValuePair(Of String, String)("http://schemas.contoso.com/carSchema", "Contoso.Cars"))

會產生下列型別 (已因應提高可讀性而稍微簡化)。

[DataContract]
public partial class Vehicle : IExtensibleDataObject
{
    private int yearField;
    private string colorField;

    [DataMember]
    public int year
    {
        get { return this.yearField; }
        set { this.yearField = value; }
    }
    [DataMember]
    public string color
    {
        get { return this.colorField; }
        set { this.colorField = value; }
    }

    private ExtensionDataObject extensionDataField;
    public ExtensionDataObject ExtensionData
    {
        get { return this.extensionDataField; }
        set { this.extensionDataField = value; }
    }
}

Partial Class Vehicle
    Implements IExtensibleDataObject

    Private yearField As Integer
    Private colorField As String

    <DataMember()> _
    Public Property year() As Integer
        Get
            Return Me.yearField
        End Get
        Set
            Me.yearField = value
        End Set
    End Property

    <DataMember()> _
    Public Property color() As String
        Get
            Return Me.colorField
        End Get
        Set
            Me.colorField = value
        End Set
    End Property
    Private extensionDataField As ExtensionDataObject

    Public Property ExtensionData() As ExtensionDataObject _
        Implements IExtensibleDataObject.ExtensionData
        Get
            Return Me.extensionDataField
        End Get
        Set(ByVal value As ExtensionDataObject)
            Me.extensionDataField = value
        End Set
    End Property
End Class

請注意，產生的型別會遵循數種資料合約最佳做法 (可在最佳做法：資料合約版本設定中找到)：

此型別會實作 IExtensibleDataObject 介面。如需詳細資訊，請參閱向前相容資料合約。
資料成員會實作為包裝私用欄位的公用屬性。
此類別是部份類別，而且透過不需要修改產生之程式碼來新增項目。

XsdDataContractExporter 讓您能夠進行相反的動作，也就是接受可使用 DataContractSerializer 序列化的型別，並產生 XSD 結構描述文件。

不保證精確度

這個類別不保證結構描述或型別在來回行程中絕對保有完整的精確度 (來回行程表示匯入結構描述以建立一組類別，並將該結果匯出以再度建立結構描述)。不一定會傳回相同的結構描述。反向進行此程序時也不能保證維持精確度 (匯出型別以產生其結構描述，然後再將該型別匯入回來。不太可能會傳回相同的型別)。

支援的型別

資料合約模型只支援有限的 WC3 結構描述子集。不符合這個子集的任何結構描述，都會在匯入程序進行時造成例外狀況。例如，沒有任何方式能夠指定資料合約的成員應該要序列化為 XML 屬性。這樣一來，因為不可能以正確的 XML 規劃來產生資料合約，所以就不會支援需要使用 XML 屬性的結構描述，進而會在匯入期間造成例外狀況。

例如，下列結構描述片段無法使用預設的匯入設定來進行匯入。

<xs:complexType name="Vehicle">
  <xs:sequence>
    <xs:element name="year" type="xs:int" />
    <xs:element name="color" type="xs:string" />
  </xs:sequence>
  <xs:attribute name="engineHorsePower" type="xs:int" />
</xs:complexType>

如需詳細資訊，請參閱資料合約結構描述參考。如果結構描述不符合資料合約規則，請使用不同的序列化引擎。例如，XmlSerializer 會使用自己的個別結構描述匯入機制。另外，還有一種可用來擴充受支援結構描述之範圍的特殊匯入模式。如需詳細資訊，請參閱匯入結構描述以產生類別中關於產生 IXmlSerializable 型別的章節。

XsdDataContractExporter 會支援可用 DataContractSerializer 序列化的任何 .NET Framework 型別。如需詳細資訊，請參閱資料合約序列化程式支援的型別。請注意，使用 XsdDataContractExporter 產生的型別，通常是 XsdDataContractImporter 可使用的有效資料 (除非 XmlSchemaProviderAttribute 是用於自訂結構描述)。

如需使用 XsdDataContractImporter 的詳細資訊，請參閱匯入結構描述以產生類別。

如需使用 XsdDataContractExporter 的詳細資訊，請參閱從類別匯出結構描述。

結構描述匯入和匯出

不保證精確度

支援的型別

另請參閱

其他資源