Schemareferens för datakontrakt

Det här avsnittet beskriver delmängden av XML-schema (XSD) som används av DataContractSerializer för att beskriva CLR-typer (Common Language Runtime) för XML-serialisering.

DataContractSerializer-mappningar

CLR-typerna DataContractSerializer mappas till XSD när metadata exporteras från en WCF-tjänst (Windows Communication Foundation) med hjälp av en metadataslutpunkt eller Verktyget för ServiceModel-metadata (Svcutil.exe). Mer information finns i Data Contract Serializer.

Mappar DataContractSerializer även XSD till CLR-typer när Svcutil.exe används för att komma åt WSDL-dokument (Web Services Description Language) eller XSD-dokument och generera datakontrakt för tjänster eller klienter.

Endast XML-schemainstanser som uppfyller kraven i det här dokumentet kan mappas till CLR-typer med hjälp av DataContractSerializer.

Supportnivåer

Ger DataContractSerializer följande stödnivåer för en viss XML-schemafunktion:

• Stöds. Det finns explicit mappning från den här funktionen till CLR-typer eller attribut (eller båda) med hjälp av DataContractSerializer.

• Ignorerad. Funktionen tillåts i scheman som importeras av DataContractSerializer, men har ingen effekt på kodgenereringen.

• Förbjudet. DataContractSerializer Stöder inte import av ett schema med hjälp av funktionen. Till exempel Svcutil.exe, när du kommer åt en WSDL med ett schema som använder en sådan funktion, återgår till att använda XmlSerializer i stället. Detta är som standard.

Allmän information

• Schemanamnområdet beskrivs i XML-schema. Prefixet "xs" används i det här dokumentet.

• Alla attribut med ett namnområde som inte är schema ignoreras.

• Eventuella anteckningar (förutom de som beskrivs i det här dokumentet) ignoreras.

<xs:schema>: attribut

<xs:schema>: innehåll

Komplexa typer – <xs:complexType>

Allmän information

Varje komplex typ <xs:complexType> mappar till ett datakontrakt.

<xs:complexType>: attribut

<xs:complexType>: innehåll

<xs:sequence> i en komplex typ: attribut

<xs:sequence> i en komplex typ: innehåll

Element – <xs:element>

Allmän information

<xs:element> kan inträffa i följande kontexter:

• Det kan inträffa inom ett <xs:sequence>, som beskriver en datamedlem i ett vanligt (icke-samling) datakontrakt. I det här fallet måste attributet maxOccurs vara 1. (Värdet 0 är inte tillåtet).

• Det kan inträffa inom en <xs:sequence>, som beskriver en datamedlem i ett samlingsdatakontrakt. I det här fallet maxOccurs måste attributet vara större än 1 eller "obundet".

• Det kan inträffa i en <xs:schema> som en global elementdeklaration (GED).

<xs:element> med maxOccurs=1 i en <xs:sequence> (datamedlemmar)

<xs:element> med maxOccurs>1 i en <xs:sequence> (samlingar)

• Mappar till en CollectionDataContractAttribute.

• I samlingstyper tillåts endast ett xs:element i en xs:sekvens.

Samlingar kan vara av följande typer:

• Vanliga samlingar (till exempel matriser).

• Ordlistesamlingar (mappa ett värde till ett annat, till exempel en Hashtable).

• Den enda skillnaden mellan en ordlista och en matris av nyckel/värde-partyp finns i den genererade programmeringsmodellen. Det finns en mekanism för schemaanteckning som kan användas för att indikera att en viss typ är en ordlistesamling.

Reglerna för attributen ref, block, default, fixed, formoch id är desamma som för icke-samlingsfallet. Andra attribut inkluderar dem i följande tabell.

<xs:element> i en <global elementdeklaration för xs:schema>

• En global elementdeklaration (GED) som har samma namn och namnområde som en typ i schemat, eller som definierar en anonym typ i sig, sägs vara associerad med typen.

• Schemaexport: associerade GED:er genereras för varje genererad typ, både enkel och komplex.

• Deserialisering/serialisering: associerade GED:er används som rotelement för typen.

• Schemaimport: associerade GED:er krävs inte och ignoreras om de följer följande regler (om de inte definierar typer).

<xs:element>: innehåll

* När du använder simpleType och complexTypeär mappningen för anonyma typer densamma som för icke-anonyma typer, förutom att det inte finns några anonyma datakontrakt, och därför skapas ett namngivet datakontrakt med ett genererat namn som härleds från elementnamnet. Reglerna för anonyma typer finns i följande lista:

• Information om WCF-implementering: Om xs:element namnet inte innehåller perioder mappar den anonyma typen till en inre typ av den yttre datakontraktstypen. Om namnet innehåller perioder är den resulterande datakontraktstypen oberoende (inte en inre typ).

• Det genererade datakontraktsnamnet för den inre typen är namnet på datakontraktet för den yttre typen följt av en period, namnet på elementet och strängen "Typ".

• Om det redan finns ett datakontrakt med ett sådant namn blir namnet unikt genom att lägga till "1", "2", "3" och så vidare tills ett unikt namn har skapats.

Enkla typer – <xs:simpleType>

<xs:simpleType>: attribut

<xs:simpleType>: innehåll

<xs:restriction>

• Komplexa typbegränsningar stöds endast för base="xs:anyType".

• Enkla typbegränsningar för xs:string som inte har några andra begränsningsfasetter än xs:enumeration mappas till uppräkningsdatakontrakt.

• Alla andra enkla typbegränsningar mappas till de typer som de begränsar. Till exempel en begränsning av xs:int kartor till ett heltal, precis som xs:int det gör. Mer information om primitiv typmappning finns i Typ/primitiv mappning.

<xs:restriction>: attribut

<xs:restriction> för alla andra fall: innehåll

Uppräkning

<xs:restriction> for enumerations: attributes

<xs:restriction> for enumerations: contents

Följande kod visar en C#-uppräkningsklass.

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

Den här klassen mappas till följande schema med DataContractSerializer. Om uppräkningsvärdena börjar från 1 xs:annotation genereras inte block.

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

<xs:list>

DataContractSerializer mappar uppräkningstyper som markerats med System.FlagsAttribute till xs:list härledda från xs:string. Inga andra xs:list varianter stöds.

<xs:list>: attribut

<xs:list>: innehåll

Om uppräkningsvärdet inte följer en effekt på 2 progression (standard för Flaggor) lagras värdet i elementet xs:annotation/xs:appInfo/ser:EnumerationValue .

Följande kod flaggar till exempel en uppräkningstyp.

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

Den här typen mappar till följande schema.

<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="http://schemas.microsoft.com/2003/10/Serialization/">16</EnumerationValue>
              </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="AuthWindowsLiveID">
            <xs:annotation>
              <xs:appinfo>
                <EnumerationValue xmlns="http://schemas.microsoft.com/2003/10/Serialization/">64</EnumerationValue>
              </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
        </xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>

Arv

Allmänna regler

Ett datakontrakt kan ärva från ett annat datakontrakt. Sådana datakontrakt mappas till en bas och härleds av tilläggstyper med hjälp av XML-schemakonstruktionen <xs:extension> .

Ett datakontrakt kan inte ärva från ett samlingsdatakontrakt.

Följande kod är till exempel ett datakontrakt.

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

Det här datakontraktet mappar till följande XML-schematypdeklaration.

<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>: attribut

<xs:complexContent>: innehåll

<xs:extension> i <xs:complexContent>: attribut

<xs:extension> in <xs:complexContent>: contents

Reglerna är desamma som för <xs:complexType> innehållet.

Om en <xs:sequence> tillhandahålls mappas dess medlemselement till ytterligare datamedlemmar som finns i det härledda datakontraktet.

Om en härledd typ innehåller ett element med samma namn som ett element i en bastyp mappar den duplicerade elementdeklarationen till en datamedlem med ett namn som genereras för att vara unikt. Positiva heltalsnummer läggs till i datamedlemsnamnet ("member1", "member2" och så vidare) tills ett unikt namn hittas. Omvänt:

• Om ett härlett datakontrakt har en datamedlem med samma namn och typ som en datamedlem i ett basdatakontrakt DataContractSerializer genererar motsvarande element i den härledda typen.

• Om ett härlett datakontrakt har en datamedlem med samma namn som en datamedlem i ett basdatakontrakt men en annan typ importeras DataContractSerializer ett schema med ett element av typen xs:anyType i både bastyps- och härledda typdeklarationer. Det ursprungliga typnamnet bevaras i xs:annotations/xs:appInfo/ser:ActualType/@Name.

Båda varianterna kan leda till ett schema med en tvetydig con tältläge l, som beror på ordningen för respektive datamedlemmar.

Typ-/primitiv mappning

DataContractSerializer Använder följande mappning för primitiva XML-schematyper.

Mappning av ISerializable-typer

I .NET Framework version 1.0 ISerializable introducerades som en allmän mekanism för att serialisera objekt för beständighet eller dataöverföring. Det finns många .NET Framework-typer som implementerar ISerializable och som kan skickas mellan program. DataContractSerializer ger naturligtvis stöd för ISerializable klasser. Schematyperna DataContractSerializer mappar ISerializable implementeringsscheman som endast skiljer sig åt med QName (kvalificerat namn) av typen och som i praktiken är egenskapssamlingar. Mappas DataContractSerializer Exception till exempel till följande XSD-typ i http://schemas.datacontract.org/2004/07/System namnområdet.

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

Det valfria attributet ser:FactoryType som deklareras i datakontrakts serialiseringsschemat refererar till en fabriksklass som kan deserialisera typen. Fabriksklassen måste vara en del av den kända typsamlingen för den DataContractSerializer instans som används. Mer information om kända typer finns i Kända typer av datakontrakt.

DataContract-serialiseringsschema

Ett antal scheman som exporteras av användningstyper DataContractSerializer , element och attribut från ett särskilt namnområde för datakontraktsserialisering:

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

Följande är en fullständig schemadeklaration för datakontraktsserierering.

<xs:schema attributeFormDefault="qualified"
   elementFormDefault="qualified"
   targetNamespace =
    "http://schemas.microsoft.com/2003/10/Serialization/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:tns="http://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>

Följande bör noteras:

• ser:char introduceras för att representera Unicode-tecken av typen Char.

• Av valuespace xs:duration reduceras till en ordnad uppsättning så att den kan mappas till en TimeSpan.

• FactoryType används i scheman som exporteras från typer som härleds från ISerializable.

Importerar icke-DataContract-scheman

DataContractSerializerImportXmlTypes har alternativet att tillåta import av scheman som inte överensstämmer med DataContractSerializer XSD-profilen (se egenskapenOptions). Om du anger det här alternativet kan true du godkänna icke-överensstämmande schematyper och mappa dem till följande implementering, IXmlSerializable omsluta en matris XmlNode med (endast klassnamnet skiljer sig åt).

[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-serialisering

DateTimeOffset Behandlas inte som en primitiv typ. I stället serialiseras det som ett komplext element med två delar. Den första delen representerar datumtiden och den andra delen representerar förskjutningen från datumtiden. Ett exempel på ett serialiserat DateTimeOffset-värde visas i följande kod.

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

Schemat är följande.

<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:element name="OffsetMinutes" type="xs:short"
         minOccurs="1" maxOccurs="1" />
      </xs:sequence>
   </xs:complexType>
</xs:schema>

Se även

• DataContractSerializer
• DataContractAttribute
• DataMemberAttribute
• XsdDataContractImporter
• Använda datakontrakt