Riferimento allo schema del contratto dati

In questo argomento viene descritto il sottoinsieme dello schema XML (XSD) utilizzato da DataContractSerializer per descrivere i tipi di Common Language Runtime (CLR) per la serializzazione XML.

Mapping DataContractSerializer

DataContractSerializer esegue il mapping di tipi CLR a XSD quando i metadati vengono esportati da un servizio Windows Communication Foundation (WCF) utilizzando un endpoint di metadati o lo strumento ServiceModel Metadata Utility Tool (Svcutil.exe). Per ulteriori informazioni, vedere Serializzatore dei contratti dati.

DataContractSerializer esegue, inoltre, il mapping di XSD ai tipi CLR quando viene utilizzato Svcutil.exe per accedere a documenti WSDL (Web Services Description Language) o XSD e generare contratti dati per servizi o client.

È possibile eseguire il mapping ai tipi CLR tramite DataContractSerializer solo delle istanze dello schema XML conformi ai requisiti indicati nel presente documento.

Livelli di supporto

DataContractSerializer fornisce i livelli di supporto seguenti per una determinata funzionalità dello schema XML:

• Supportato. È disponibile il mapping esplicito da questa funzionalità a tipi e/o attributi CLR mediante DataContractSerializer.
• Ignorato. La funzionalità è consentita negli schemi importati da DataContractSerializer, ma non ha alcun effetto sulla generazione di codice.
• Non consentito. DataContractSerializer non supporta l'importazione di uno schema mediante la funzionalità. Svcutil.exe, ad esempio, quando si accede a un documento WSDL con uno schema che utilizza tale funzionalità, torna a utilizzare XmlSerializer. Questo accade per impostazione predefinita.

Informazioni generali

• Lo spazio dei nomi dello schema viene descritto nella pagina relativa allo schema ML (la pagina potrebbe essere in inglese). In questo documento viene utilizzato il prefisso "xs".
• Tutti gli attributi con un spazio dei nomi non di schema vengono ignorati.
• Tutte le annotazioni, ad eccezione di quelle descritte in questo documento, vengono ignorate.

<xs:schema>: attributi

<xs:schema>: contenuto

Tipi complessi – <xs:complexType>

Informazioni generali

Ogni tipo complesso <xs:complexType> esegue il mapping a un contratto dati.

<xs:complexType>: attributi

<xs:complexType>: contenuto

<xs:sequence> in un tipo complesso: attributi

<xs:sequence> in un tipo complesso: contenuto

Elementi – <xs:element>

Informazioni generali

<xs:element> può verificarsi nei contesti seguenti:

• Può verificarsi all'interno di un tag <xs:sequence> che descrive un membro dati di un contratto dati regolare (non di insieme). In questo caso, l'attributo maxOccurs deve essere 1 (non è consentito un valore pari a 0).
• Può verificarsi all'interno di un tag <xs:sequence> che descrive un membro dati di un contratto dati di insieme. In questo caso, l'attributo maxOccurs deve essere maggiore di 1 o "unbounded".
• Può verificarsi all'interno di un <xs:schema> come dichiarazione di elemento globale (GED).

<xs:element> con maxOccurs=1 all'interno di un tag <xs:sequence> (membri dati)

<xs:element> con maxOccurs>1 all'interno di un tag <xs:sequence> (insiemi)

• Esegue il mapping a un CollectionDataContractAttribute.
• Nei tipi di insieme, è consentito un solo xs:element all'interno di un xs:sequence.

Gli insiemi possono essere dei tipi seguenti:

• Insiemi regolari (ad esempio, matrici).
• Insiemi dizionario (esecuzione del mapping di un valore all'altro; ad esempio, Hashtable).

• La sola differenza tra un dizionario e una matrice di un tipo di coppia chiave/valore è nel modello di programmazione generato. Esiste un meccanismo di annotazione di schema che può essere utilizzato per indicare che un determinato tipo è un insieme dizionario.

Le regole per gli attributi ref, block, default, fixed, form e id solo uguali a quelle valide per il caso non di insieme. Tra gli altri attributi sono inclusi quelli riportati nella tabella seguente.

<xs:element> all'interno di una dichiarazione di elemento globale <xs:schema>

• Una dichiarazione di elemento globale (GED) con lo stesso nome e lo stesso spazio dei nomi di un tipo nello schema, o che definisce un tipo anonimo al suo interno, viene definita come associata al tipo.
• Esportazione dello schema: vengono generate dichiarazioni di elementi globali associate per ogni tipo generato, sia semplice che complesso.
• Deserializzazione/serializzazione: vengono utilizzate dichiarazioni di elementi globali associate come elementi principali per il tipo.
• Importazione dello schema: le dichiarazioni di elementi globali associate non sono necessarie e vengono ignorate se seguono le regole seguenti (a meno che non definiscano tipi).

<xs:element>: contenuto

* Quando si utilizzano simpleType e complexType, il mapping dei tipi anonimi è uguale a quello dei tipi non anonimi, tranne per il fatto che non esiste alcun contratto dati anonimo e quindi viene creato un contratto dati denominato, con un nome generato derivato dal nome dell'elemento. Le regole per i tipi anonimi sono riportate nell'elenco seguente:

• Dettaglio di implementazione di WCF: se il nome xs:element non contiene punti, il tipo anonimo esegue il mapping a un tipo interno del tipo di contratto dati esterno. Se il nome contiene punti, il tipo di contratto dati risultante è indipendente (non è un tipo interno).
• Il nome del contratto dati generato del tipo interno è il nome del contratto dati del tipo esterno seguito da un punto, dal nome dell'elemento e dalla stringa "Type".
• Se esiste già un contratto dati con tale nome, il nome viene reso univoco aggiungendo "1", "2", "3" e così via, fino a creare un nome univoco.

Tipi semplici - <xs:simpleType>

<xs:simpleType>: attributi

<xs:simpleType>: contenuto

<xs:restriction>

• Le restrizioni di tipi complessi sono supportate solo per la base = "xs:anyType".
• Le restrizioni di tipi semplici di xs:string che non hanno facet di restrizione diversi da xs:enumeration vengono associate a contratti dati di enumerazione.
• Tutte le altre restrizioni di tipi semplici vengono associate ai tipi che limitano. Ad esempio, una restrizione di xs:int esegue il mapping a un valore intero, esattamente come fa xs:int. Per ulteriori informazioni sul mapping dei tipi primitivi, vedere Mapping di tipi/primitivi.

<xs:restriction>: attributi

<xs:restriction> per tutti gli altri casi: contenuto

Enumerazione

<xs:restriction> per enumerazioni: attributi

<xs:restriction> per enumerazioni: contenuto

Nel codice seguente viene illustrata una classe di enumerazione C#.

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

}

Questa classe esegue il mapping allo schema seguente da DataContractSerializer. Se i valori dell'enumerazione iniziano da 1, non vengono generati blocchi 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 esegue il mapping dei tipi di enumerazione contrassegnati con System.FlagsAttribute a un xs:list derivato da xs:string. Non sono supportate altre variazioni di xs:list.

<xs:list>: attributi

<xs:list>: contenuto

Se il valore dell'enumerazione non segue una progressione per potenza di 2 (impostazione predefinita per i flag), viene memorizzato nell'elemento xs:annotation/xs:appInfo/ser:EnumerationValue.

Ad esempio, nel codice seguente viene contrassegnato un tipo di enumerazione.

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

Questo tipo esegue il mapping allo schema seguente.

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

Ereditarietà

Regole generali

Un contratto dati può ereditare da un altro contratto dati. Viene eseguito il mapping tra questi contratti dati, derivati da tipi di estensione tramite il costrutto dello schema XML <xs:extension>, e una base.

Un contratto dati non può ereditare da un contratto dati di insieme.

Ad esempio, nel codice seguente viene illustrato un contratto dati.

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

Questo contratto dati esegue il mapping alla dichiarazione di tipo dello schema XML seguente.

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

<xs:complexContent>: contenuto

<xs:extension> in <xs:complexContent>: attributi

<xs:extension> in <xs:complexContent>: contenuto

Le regole sono le stesse del contenuto <xs:complexType>.

Se viene fornito un <xs:sequence>, i relativi elementi membro eseguono il mapping a membri dati aggiuntivi presenti nel contratto dati derivato.

Se un tipo derivato contiene un elemento con lo stesso nome di un elemento in un tipo di base, la dichiarazione dell'elemento duplicato esegue il mapping a un membro dati con un nome generato per essere univoco. Vengono aggiunti numeri interi positivi al nome del membro dati ("membro1", "membro2" e così via) fino a trovare un nome univoco. Al contrario:

• Se un contratto dati derivato ha un membro dati con lo stesso nome e lo stesso tipo di un membro dati in un contratto dati di base, DataContractSerializer genera questo elemento corrispondente nel tipo derivato.
• Se un contratto dati derivato ha un membro dati con lo stesso nome di un membro dati in un contratto dati di base ma con un tipo diverso, DataContractSerializer importa uno schema con un elemento del tipo xs:anyType nelle dichiarazioni del tipo di base e del tipo derivato. Il nome del tipo originale viene mantenuto in xs:annotations/xs:appInfo/ser:ActualType/@Name.

Entrambe le variazioni possono condurre a un schema con un modello di contenuto ambiguo, che dipende dall'ordine dei rispettivi membri dati.

Mapping di tipi/primitivi

DataContractSerializer utilizza il mapping seguente per i tipi primitivi dello schema XML.

Mapping dei tipi ISerializable

In .NET Framework versione 1.0, ISerializable è stato introdotto come meccanismo generale per serializzare oggetti per la persistenza o il trasferimento di dati. Sono disponibili molti tipi .NET Framework che implementano ISerializable e che possono essere passati tra le applicazioni. DataContractSerializer fornisce naturalmente il supporto per le classi ISerializable. DataContractSerializer esegue il mapping ai tipi dello schema di implementazione di ISerializable che differiscono solo per il QName (nome completo) del tipo e sono effettivamente insiemi di proprietà. Ad esempio, DataContractSerializer esegue il mapping di Exception al tipo XSD seguente nello spazio dei nomi http://schemas.datacontract.org/2004/07/System.

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

L'attributo facoltativo ser:FactoryType dichiarato nello schema di serializzazione del contratto dati fa riferimento a una classe factory che può deserializzare il tipo. La classe factory deve far parte dell'insieme dei tipi conosciuti dell'istanza di DataContractSerializer utilizzata. Per ulteriori informazioni sui tipi conosciuti, vedere Tipi conosciuti di contratto dati.

Schema di serializzazione del contratto dati

Diversi schemi esportati da DataContractSerializer utilizzano tipi, elementi e attributi da uno speciale spazio dei nomi di serializzazione del contratto dati:

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

Di seguito è riportata una dichiarazione completa dello schema di serializzazione del contratto dati.

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

È necessario tenere presente quanto segue:

• ser:char viene introdotto per rappresentare caratteri Unicode di tipo Char.
• Il valuespace di xs:duration viene ridotto a un insieme ordinato, in modo che possa essere associato a un TimeSpan.
• FactoryType viene utilizzato negli schemi esportati da tipi derivati da ISerializable.

Importazione di schemi non di contratto dati

DataContractSerializer dispone dell'opzione ImportXmlTypes per consentire l'importazione di schemi non conformi al profilo XSD DataContractSerializer (vedere la proprietà Options). Se si imposta questa opzione su true, si consente l'accettazione di tipi di schema non conformi e il mapping di questi ultimi all'implementazione seguente, con IXmlSerializable che esegue il wrapping di una matrice di XmlNode (differisce solo il nome della classe).

[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;
  }
}

Serializzazione DateTimeOffset

DateTimeOffset non viene considerato un tipo primitivo. Viene invece serializzato come elemento complesso con due parti. La prima parte rappresenta il valore data/ora e la seconda parte rappresenta l'offset dal valore data/ora. Nel codice seguente viene illustrato un esempio di valore DateTimeOffset serializzato.

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

Lo schema è il seguente.

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

Vedere anche

Riferimenti

DataContractSerializer
DataContractAttribute
DataMemberAttribute
XsdDataContractImporter

Concetti

Utilizzo di contratti dati