資料合約結構描述參考

本主題說明 DataContractSerializer 用來描述 XML 序列化之 Common Language Runtime (CLR) 型別的 XML 結構描述 (XSD) 子集。

DataContractSerializer 對應

當您使用中繼資料端點或 ServiceModel Metadata Utility Tool (Svcutil.exe)，從 Windows Communication Foundation (WCF) 服務匯出中繼資料時，DataContractSerializer 就會將 CLR 型別對應至 XSD。如需詳細資訊，請參閱 資料合約序列化程式。

當您使用 Svcutil.exe 來存取 Web 服務描述語言 (WSDL) 或 XSD 文件並產生服務或用戶端的資料合約時，DataContractSerializer 也會將 XSD 對應至 CLR 型別。

只有符合本文件所述之需求的 XML 結構描述執行個體可以使用 DataContractSerializer 對應至 CLR 型別。

支援層級

DataContractSerializer 針對特定 XML 結構描述功能提供下列支援層級：

• 支援：使用 DataContractSerializer 從這項功能明確對應至 CLR 型別或屬性 (或兩者)。
• 忽略：此功能可用在 DataContractSerializer 所匯入的結構描述中，但是不會對產生程式碼有任何影響。
• 禁止：DataContractSerializer 不支援使用此功能來支援匯入結構描述。例如，當使用結構描述 (運用此類功能) 來存取 WSDL 時，Svcutil.exe 就會改回使用 XmlSerializer。這是預設的結果。

一般資訊

• XML 結構描述 (本頁面可能為英文) 將說明結構描述命名空間。本文使用 "xs" 前置詞。
• 任何包含非結構描述命名空間的屬性都會被忽略。
• 任何附註 (除了本文中所述的以外) 都會被忽略。

<xs:schema>：屬性

<xs:schema>：內容

複雜型別 – <xs:complexType>

一般資訊

每個複雜型別 <xs:complexType> 都對應至資料合約。

<xs:complexType>：屬性

<xs:complexType>：內容

複雜型別中的 <xs:sequence>：屬性

複雜型別中的 <xs:sequence>：內容

項目 – <xs:element>

一般資訊

<xs:element> 可能在下列情況發生：

• 它會發生在用來描述一般 (非集合) 資料合約之資料成員的 <xs:sequence> 中。在此情況下，maxOccurs 屬性必須為 1 (不允許出現 0 的值)。
• 它會發生在用來描述集合資料合約之資料成員的 <xs:sequence> 中。在此情況下，maxOccurs 屬性必須為大於 1 或 "unbounded"。
• 它會發生在 <xs:schema> 中，做為全域項目宣告 (GED)。

在 <xs:sequence> (資料成員) 中，maxOccurs=1 的 <xs:element>

在 <xs:sequence> (集合) 中，maxOccurs>1 的 <xs:element>

• 對應至 CollectionDataContractAttribute。
• 在集合型別中，xs:sequence 只允許使用一個 xs:element。

集合可以是下列任何型別：

• 一般集合 (例如，陣列)。
• 字典集合 (將某值對應至另一個值；例如，Hashtable)。

• 字典與金鑰/值組型別的陣列之間的唯一差異，就在於產生的程式設計模型。您可採用一種結構描述附註機制，將特定型別指定為字典集合。

ref、block、default、fixed、form 和 id 屬性的規則與非集合案例的規則是一樣的。下表包含其他各項屬性。

<xs:element>，位於 <xs:schema> 全域項目宣告中

• 與結構描述中的型別具有相同名稱與命名空間的全域項目宣告 (GED)，或是可在本身內部定義匿名型別的項目，稱為與型別關聯。
• 結構描述匯出：每個產生的型別，不管是簡單還是複雜型別，都會產生關聯的 GED。
• 還原序列化/序列化：關聯的 GED 可做為型別的根項目來使用。
• 結構描述匯入：如果關聯的 GED 遵循下列規則 (除非它們定義了型別)，則這些 GED 為非必要而且會被忽略。

<xs:element>：內容

* 如果匿名型別與非匿名型別的 simpleType 和 complexType 對應之使用方式一樣 (除了不存在匿名資料合約之外)，會建立具名資料合約，並產生衍生自項目名稱的名稱。下表為匿名型別的規則：

• WCF 實作詳細資料：如果 xs:element 名稱不包含句點，則匿名型別會對應至外部資料合約型別的內部型別。如果名稱包含句點，則結果的資料合約型別是獨立的 (不是內部型別)。
• 產生之內部型別的資料合約名稱為外部型別的資料合約名稱，後面並跟著句點、項目名稱，以及字串 "Type"。
• 如果此名稱的資料合約已經存在，則名稱後面會加上 "1"、"2"、"3" 等，直到將其建立為唯一的名稱。

簡單型別 - <xs:simpleType>

<xs:simpleType>：屬性

<xs:simpleType>：內容

<xs:restriction>

• base="xs:anyType" 僅支援複雜型別限制。
• 只包含 xs:enumeration 限制 Facet 的 xs:string 簡單型別限制會對應至列舉資料合約。
• 其他所有簡單型別限制則會對應至所限制的型別上。例如，xs:int 的限制會對應至整數，就像 xs:int 所做的一樣。如需 基本型別對應的詳細資訊，請參閱「型別/基本對應」。

<xs:restriction>：屬性

<xs:restriction> (適用其他所有情況)：內容

列舉

<xs:restriction> (適用列舉)：屬性

<xs:restriction> (適用列舉)：內容

下列程式碼將示範 C# 列舉類別。

public enum MyEnum
{
   first = 3,
   second = 4,
   third =5

}

此類別會透過 DataContractSerializer 對應至下列結構描述。如果列舉值從 1 開始，則不會產生 xs:annotation 區塊。

<xs:simpleType name="MyEnum">
<xs:restriction base="xs:string">
 <xs:enumeration value="first">
  <xs:annotation>
   <xs:appinfo>
    <EnumerationValue 
     xmlns="https://schemas.microsoft.com/2003/10/Serialization/">
     3
    </EnumerationValue>
   </xs:appinfo>
  </xs:annotation>
 </xs:enumeration>
 <xs:enumeration value="second">
  <xs:annotation>
   <xs:appinfo>
    <EnumerationValue 
     xmlns="https://schemas.microsoft.com/2003/10/Serialization/">
     4
    </EnumerationValue>
   </xs:appinfo>
  </xs:annotation>
 </xs:enumeration> 
</xs:restriction>
</xs:simpleType>

<xs:list>

DataContractSerializer 會將標示為 System.FlagsAttribute 的列舉型別對應至衍生自 xs:string 的 xs:list。不支援其他任何 xs:list 變化。

<xs:list>：屬性

<xs:list>：內容

如果列舉值並未遵循 2 次方的級數 (旗標的預設值)，則會將值儲存在 xs:annotation/xs:appInfo/ser:EnumerationValue 項目中。

例如，下列程式碼會為列舉型別加上旗標。

[Flags]
public enum AuthFlags
{  
  AuthAnonymous = 1,
  AuthBasic = 2,
  AuthNTLM = 4,
  AuthMD5 = 16,
  AuthPassport = 64,
}

此型別會對應至下列結構描述。

<xs:simpleType name="AuthFlags">
    <xs:list>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="AuthAnonymous" />
          <xs:enumeration value="AuthBasic" />
          <xs:enumeration value="AuthNTLM" />
          <xs:enumeration value="AuthMD5">
            <xs:annotation>
              <xs:appinfo>
                <EnumerationValue xmlns="https://schemas.microsoft.com/2003/10/Se
rialization/">16</EnumerationValue>
              </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="AuthPassport">
            <xs:annotation>
              <xs:appinfo>
                <EnumerationValue xmlns="https://schemas.microsoft.com/2003/10/Se
rialization/">64</EnumerationValue>
              </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
        </xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>

繼承

一般規則

資料合約可以繼承自其他資料合約。此類資料合約會對應至基底型別，而且會使用 <xs:extension> XML 結構描述建構並由延伸型別衍生。

資料合約無法繼承自集合資料合約。

例如，下列程式碼為資料合約。

[DataContract]
public class Person
{
  [DataMember]
  public string Name;
}
[DataContract]
public class Employee : Person 
{    
  [DataMember]
  public int ID;
}

此資料合約會對應至下列 XML 結構描述型別宣告。

<xs:complexType name="Employee">
 <xs:complexContent mixed="false">
  <xs:extension base="tns:Person">
   <xs:sequence>
    <xs:element minOccurs="0" name="ID" type="xs:int"/>
   </xs:sequence>
  </xs:extension>
 </xs:complexContent>
</xs:complexType>
<xs:complexType name="Person">
 <xs:sequence>
  <xs:element minOccurs="0" name="Name" 
    nillable="true" type="xs:string"/>
 </xs:sequence>
</xs:complexType>

<xs:complexContent>：屬性

<xs:complexContent>：內容

<xs:extension>，內含於 <xs:complexContent>：屬性

<xs:extension>，內含於 <xs:complexContent>：內容

其規則與 <xs:complexType> 內容的規則一樣。

如果提供了 <xs:sequence>，則其成員項目會對應至額外資料成員 (存在衍生的資料合約中)。

如果衍生型別內含的項目與基底型別中的項目擁有相同的名稱，則重複的項目宣告會對應至已產生唯一名稱的資料成員。正整數會新增至資料成員名稱 ("member1"、"member2" 等等)，直到找到唯一名稱為止。相反地：

• 如果衍生資料合約的資料成員與基底資料合約中的資料成員具有相同的名稱與型別，則 DataContractSerializer 會在衍生型別中產生這個對應的項目。
• 如果衍生資料合約的資料成員與基底資料合約中的資料成員具有相同的名稱 (但型別不同)，則 DataContractSerializer 會將包含型別 xs:anyType 之項目的結構描述匯入基底型別與衍生型別宣告中。原始型別名稱會保留在 xs:annotations/xs:appInfo/ser:ActualType/@Name 中。

兩種變化視各自的資料成員的順序而定，都可能會導致結構描述內含模糊的內容模型。

型別/基本對應

DataContractSerializer 針對 XML 結構描述基本型別使用下列對應。

ISerializable 型別對應

在 .NET Framework 1.0 版中，已將 ISerializable 引入為用來序列化物件以便保存或做為資料傳輸用途的一般機制。有許多種 .NET Framework 型別都可實作 ISerializable，而且可以在應用程式之間傳遞。DataContractSerializer 很自然地會針對 ISerializable 類別提供支援。DataContractSerializer 會對應至 ISerializable 實作結構描述型別 (其中只有型別的 QName 限定名稱不同)，而且是有效的屬性集合。例如，DataContractSerializer 會將 Exception 對應至下列 http://schemas.datacontract.org/2004/07/System 命名空間中的 XSD 型別。

<xs:complexType name="Exception">
 <xs:sequence>
  <xs:any minOccurs="0" maxOccurs="unbounded" 
      namespace="##local" processContents="skip"/>
 </xs:sequence>
 <xs:attribute ref="ser:FactoryType"/>
</xs:complexType>

在資料合約序列化結構描述中宣告的選用屬性 ser:FactoryType 會參考可以還原序列化型別的處理站類別。處理站類別必須是正在使用之 DataContractSerializer 執行個體的已知型別集合的一部分。如需 已知型別的詳細資訊，請參閱資料合約已知型別。

DataContract 序列化結構描述

由 DataContractSerializer 匯出的一些結構描述使用來自特殊資料合約序列化命名空間的型別、項目和屬性：

https://schemas.microsoft.com/2003/10/Serialization

下列為完整的資料合約序列化結構描述宣告。

<xs:schema attributeFormDefault="qualified"        
   elementFormDefault="qualified"      
   targetNamespace = 
    "https://schemas.microsoft.com/2003/10/Serialization/" 
   xmlns:xs="http://www.w3.org/2001/XMLSchema"      
   xmlns:tns="https://schemas.microsoft.com/2003/10/Serialization/">

 <!-- Top-level elements for primitive types. -->
 <xs:element name="anyType" nillable="true" type="xs:anyType"/>
 <xs:element name="anyURI" nillable="true" type="xs:anyURI"/>
 <xs:element name="base64Binary" 
       nillable="true" type="xs:base64Binary"/>
 <xs:element name="boolean" nillable="true" type="xs:boolean"/>
 <xs:element name="byte" nillable="true" type="xs:byte"/>
 <xs:element name="dateTime" nillable="true" type="xs:dateTime"/>
 <xs:element name="decimal" nillable="true" type="xs:decimal"/>
 <xs:element name="double" nillable="true" type="xs:double"/>
 <xs:element name="float" nillable="true" type="xs:float"/>
 <xs:element name="int" nillable="true" type="xs:int"/>
 <xs:element name="long" nillable="true" type="xs:long"/>
 <xs:element name="QName" nillable="true" type="xs:QName"/>
 <xs:element name="short" nillable="true" type="xs:short"/>
 <xs:element name="string" nillable="true" type="xs:string"/>
 <xs:element name="unsignedByte" 
       nillable="true" type="xs:unsignedByte"/>
 <xs:element name="unsignedInt" 
       nillable="true" type="xs:unsignedInt"/>
 <xs:element name="unsignedLong" 
       nillable="true" type="xs:unsignedLong"/>
 <xs:element name="unsignedShort" 
       nillable="true" type="xs:unsignedShort"/>

 <!-- Primitive types introduced for certain .NET simple types. -->
 <xs:element name="char" nillable="true" type="tns:char"/>
 <xs:simpleType name="char">
  <xs:restriction base="xs:int"/>
 </xs:simpleType>

 <!-- xs:duration is restricted to an ordered value space, 
    to map to System.TimeSpan -->
 <xs:element name="duration" nillable="true" type="tns:duration"/>
 <xs:simpleType name="duration">
  <xs:restriction base="xs:duration">
   <xs:pattern 
     value="\-?P(\d*D)?(T(\d*H)?(\d*M)?(\d*(\.\d*)?S)?)?"/>
   <xs:minInclusive value="-P10675199DT2H48M5.4775808S"/>
   <xs:maxInclusive value="P10675199DT2H48M5.4775807S"/>
  </xs:restriction>
 </xs:simpleType>
 
 <xs:element name="guid" nillable="true" type="tns:guid"/>
 <xs:simpleType name="guid">
  <xs:restriction base="xs:string">
   <xs:pattern value="[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12}"/>
  </xs:restriction>
 </xs:simpleType>
 
 <!-- This is used for schemas exported from ISerializable type. -->
 <xs:attribute name="FactoryType" type="xs:QName"/>
</xs:schema>

請注意下列各項：

• ser:char 已引入來代表型別 Char 的 Unicode 字元。
• xs:duration 的 valuespace 已縮減為排序的組合，以對應至 TimeSpan。
• FactoryType 會用在衍生自 ISerializable 之型別所匯出的結構描述中。

匯入非 DataContract 結構描述

DataContractSerializer 具有 ImportXmlTypes 選項，可允許匯入不符合 DataContractSerializer XSD 設定檔的結構描述 (請參閱 Options 屬性)。將此選項設為 true 可允許接受不符的結構描述型別，並將之對應至下列實作：IXmlSerializable 包裝 XmlNode 的陣列 (只有類別名稱不同)。

[GeneratedCodeAttribute("System.Runtime.Serialization", "3.0.0.0")]
[System.Xml.Serialization.XmlSchemaProviderAttribute("ExportSchema")]
[System.Xml.Serialization.XmlRootAttribute(IsNullable=false)]
public partial class Person : object, IXmlSerializable
{  
  private XmlNode[] nodesField;  
  private static XmlQualifiedName typeName = 
new XmlQualifiedName("Person","http://Microsoft.ServiceModel.Samples");  
  public XmlNode[] Nodes
  {
    get {return this.nodesField;}
    set {this.nodesField = value;}
  }  
  public void ReadXml(XmlReader reader)
  {
    this.nodesField = XmlSerializableServices.ReadNodes(reader);
  }  
  public void WriteXml(XmlWriter writer)
  {
    XmlSerializableServices.WriteNodes(writer, this.Nodes);
  }  
  public System.Xml.Schema.XmlSchema GetSchema()
  {
    return null;
  }  
  public static XmlQualifiedName ExportSchema(XmlSchemaSet schemas)
  {
    XmlSerializableServices.AddDefaultSchema(schemas, typeName);
    return typeName;
  }
}

DateTimeOffset 序列化

DateTimeOffset 不會被視為基本型別。反之，它會被序列化為包含兩個部分的複雜項目。第一個部分代表日期時間，而第二個部分則代表日期時間的位移。下列程式碼提供序列化的 DateTimeOffset 值範例。

<OffSet xmlns:a="http://schemas.datacontract.org/2004/07/System">
  <DateTime i:type="b:dateTime"  
    xmlns:b="http://www.w3.org/2001/XMLSchema">2008-08-28T08:00:00  
  </DateTime> 
  <OffsetMinutes i:type="b:short"  
   xmlns:b="http://www.w3.org/2001/XMLSchema">-480
   </OffsetMinutes> 
</OffSet>

結構描述如下列所示。

<xs:schema targetNamespace=”http://schemas.datacontract.org/2004/07/System”>
   <xs:complexType name=”DateTimeOffset”>
      <xs:sequence minOccurs="1" maxOccurs="1">
         <xs:element name="DateTime" type="xs:dateTime"
         minOccurs="1" maxOccurs="1" />
         <xs:elementname="OffsetMinutes" type="xs:short"
         minOccurs="1" maxOccurs="1" />
      </xs:sequence>
   </xs:complexType>
</xs:schema>

請參閱

參考

DataContractSerializer
DataContractAttribute
DataMemberAttribute
XsdDataContractImporter

概念

使用資料合約