Référence des schémas de contrats de données

Cette rubrique décrit le sous-ensemble du schéma XML (XSD) utilisé par DataContractSerializer pour décrire les types CLR (Common Language Run-time) pour la sérialisation XML.

Mappages DataContractSerializer

DataContractSerializer mappe des types CLR à XSD lorsque les métadonnées sont exportés d'un service Windows Communication Foundation (WCF) à l'aide d'un point de terminaison de métadonnées ou à l'aide de ServiceModel Metadata Utility Tool (Svcutil.exe). Pour plus d'informations, consultez Sérialiseur de contrat de données.

DataContractSerializer mappe également XSD aux types CLR lorsque Svcutil.exe est utilisé pour accéder à Web Services Description Language (WSDL) ou aux documents XSD et génère des contrats de données pour les services ou les clients.

Uniquement les instances de schéma XML conformes aux spécifications déclarées dans ce document peuvent être mappées aux types CLR à l'aide de DataContractSerializer.

Niveaux pris en charge

DataContractSerializer fournit les niveaux de prise en charge suivants pour une fonctionnalité de schéma XML donnée :

• Pris en charge. Il y a mappage explicite de cette fonctionnalité aux types ou aux attributs CLR (ou les deux à la fois) via DataContractSerializer.
• Ignoré. La fonctionnalité est autorisée dans les schémas importés par DataContractSerializer, mais n'a aucun effet sur la génération du code.
• Interdit. DataContractSerializer ne prend pas en charge l'importation d'un schéma à l'aide de la fonctionnalité. Par exemple, Svcutil.exe, lors de l'accès à un WSDL avec un schéma qui utilise une telle fonctionnalité, revient à la place à l'utilisation de XmlSerializer. La valeur est par défaut.

Informations générales

• L'espace de noms du schéma est décrit dans le schéma XML (page pouvant être en anglais) Le préfixe "xs" est utilisé dans ce document.
• Les attributs avec un espace de noms qui n'est pas un schéma sont ignorés.
• Les annotations (sauf celles décrites dans ce document) sont ignorées.

<xs:schema> : attributs

<xs:schema> : contenu

Types complexes – <xs:complexType>

Informations générales

Chaque type complexe <xs:complexType> mappe à un contrat de données.

<xs:complexType> : attributs

<xs:complexType> : contenu

<xs:sequence> dans un type complexe : attributs

<xs:sequence> dans un type complexe : contenu

Éléments – <xs:element>

Informations générales

<xs:element> peut se produire dans les contextes suivants :

• Il peut se produire dans un <xs:sequence>, qui décrit un membre de données d'un contrat de données normal (qui n'est pas une collection). Dans ce cas, l'attribut maxOccurs doit être 1. (La valeur 0 n'est pas autorisée).
• Il peut se produire dans un <xs:sequence>, qui décrit un membre de données d'un contrat de données de collection. Dans ce cas, l'attribut maxOccurs doit être supérieur à 1 ou « unbounded ».
• Il peut se produire dans un <xs:schema> en tant que déclaration d'élément globale (GED).

<xs:element> avec maxOccurs=1 dans un <xs:sequence> (membres de données)

<xs:element> avec maxOccurs>1 dans un <xs:sequence> (collections)

• Mappe à un CollectionDataContractAttribute.
• Dans les types collection, un seul xs:element est autorisé dans un xs:sequence.

Les collections peuvent appartenir aux types suivants :

• Collections normales (par exemple, tableaux).
• Collections de dictionnaires (mappage d'une valeur à une autre; par exemple, un Hashtable).

• La seule différence entre un dictionnaire et un tableau pour un type de paire clé/valeur réside dans le modèle de programmation généré. Il existe un mécanisme d'annotation de schéma qui peut être utilisé pour indiquer qu'un type donné est une collection de dictionnaires.

Les règles appliquées aux attributs ref, block, default, fixed, formet id sont les mêmes que pour le type qui n'est pas une collection. Les autres attributs sont inclus dans le tableau suivant.

<xs:element> dans un <xs:schema> (déclaration d'élément globale)

• Une déclaration d'élément globale (GED) qui a le même nom et espace de noms qu'un type dans le schéma, ou qui définit un type anonyme à l'intérieur d'elle-même, est considéré comme associée au type.
• Exportation de schéma : les GED associées sont générées pour chaque type généré, simple et complexe.
• Désérialisation/sérialisation : les GED associées sont utilisées comme éléments racine pour le type.
• Importation de schéma : les GED associées ne sont pas requises et sont ignorées si elles suivent les règles suivantes (à moins qu'elles définissent des types).

<xs:element> : contenu

* L'utilisation des mappages simpleType et complexType, pour les types anonymes est la même que pour les types non anonymes, à l'exception qu'il n'y a pas de contrats de données anonymes, ainsi, un contrat de données nommé est créé, avec un nom généré dérivé du nom d'élément. Les règles pour les types anonymes sont les suivantes :

• Détail de l'implémentation WCF : si le nom xs:element ne contient pas de points, le type anonyme mappe à un type interne du type externe de contrat de données. Si le nom contient des points, le type de contrat de données résultant est indépendant (n'est pas un type interne).
• Le nom de contrat de données généré du type interne est le nom de contrat de données du type externe suivi par un point, le nom de l'élément et la chaîne "Type".
• Si un contrat de données avec un tel nom existe déjà, le nom est rendu unique en ajoutant "1", "2", "3" et ainsi de suite jusqu'à ce qu'un nom unique soit créé.

Types simples - <xs:simpleType>

<xs:simpleType> : attributs

<xs:simpleType> : contenu

<xs:restriction>

• Les restrictions de type complexe sont prises en charge uniquement pour la base = "xs:anyType".
• Les restrictions de type simple de xs:string qui n'ont pas de facettes de restriction autres que xs:enumeration sont mappées aux contrats de données d'énumération.
• Toutes les autres restrictions de type simple sont mappées aux types qu'elles restreignent. Par exemple, une restriction de xs:int mappe à un entier, tout comme xs:int lui-même. Pour plus d'informations sur le mappage de type primitif, consultez la section Mappage de type/primitif.

<xs:restriction> : attributs

<xs:restriction> pour tous les autres cas : contenu

Énumération

<xs:restriction> pour les énumérations : attributs

<xs:restriction> pour les énumérations : contenu

Le code suivant montre une classe d'énumération C#.

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

}

Cette classe mappe au schéma suivant par DataContractSerializer. Si les valeurs d'énumération démarrent à partir de 1, les blocs xs:annotation ne sont pas générés.

<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 mappe des types énumération marqués avec System.FlagsAttribute à xs:list dérivé de xs:string. Aucune autre variation xs:list n'est prise en charge.

<xs:list> : attributs

<xs:list> : contenu

Si la valeur d'énumération ne suit pas une progression de puissance de 2 (valeur par défaut pour les indicateurs), la valeur est stockée dans l'élément xs:annotation/xs:appInfo/ser:EnumerationValue.

Par exemple, le code suivant marque un type énumération.

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

Ce type mappe au schéma suivant.

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

Héritage

Règles Générales

Un contrat de données peut hériter d'un autre contrat de données. De tels contrats de données mappent à une base et sont dérivés des types d'extension à l'aide de la construction de schéma XML <xs:extension>.

Un contrat de données ne peut pas hériter d'un contrat de données de collection.

Le code ci-dessous montre un exemple de contrat de données.

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

Ce contrat de données mappe à la déclaration de type de schéma XML suivante.

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

<xs:complexContent> : contenu

<xs:extension> dans <xs:complexContent> : attributs

<xs:extension> dans <xs:complexContent> : contenu

Les règles sont les mêmes que pour le contenu <xs:complexType>.

Si un <xs:sequence> est fourni, ses éléments membres mappent aux membres de données supplémentaires qui sont présents dans le contrat de données dérivé.

Si un type dérivé contient un élément portant le même nom qu'un élément dans un type de base, la déclaration d'élément en double mappe à un membre de données avec un nom généré pour être unique. Des entiers positifs sont ajoutés au nom du membre de données ("member1", "member2" et ainsi de suite) jusqu'à ce qu'un nom unique soit trouvé. Inversement :

• Si un contrat de données dérivé a un membre de données portant le même nom et type qu'un membre de données dans un contrat de données de base, DataContractSerializer génère cet élément correspondant dans le type dérivé.
• Si un contrat de données dérivé a un membre de données portant le même nom qu'un membre de données dans un contrat de données de base mais ayant un type différent, DataContractSerializer importe un schéma avec un élément de type xs:anyType à la fois dans le type de base et dans les déclarations de type dérivé. Le nom du type d'origine est conservé dans xs:annotations/xs:appInfo/ser:ActualType/@Name.

Les deux variations peuvent aboutir à schéma ayant un modèle de contenu ambigu, qui dépend de l'ordre des membres de données respectifs.

Mappage de type/primitif

DataContractSerializer utilise le mappage suivant pour les types primitifs de schéma XML.

Mappage de types ISerializable

Dans le .NET Framework version 1.0, ISerializable a été introduit comme mécanisme général pour sérialiser des objets pour la persistance ou le transfert de données. Il y a de nombreux types .NET Framework qui implémentent ISerializable et qui peuvent être passés entre des applications. DataContractSerializer fournit naturellement le support pour les classes ISerializable. DataContractSerializer mappe des types de schéma d'implémentation ISerializable qui diffèrent uniquement par le QName (nom qualifié) du type et sont des collections de propriétés. Par exemple, DataContractSerializer mappe Exception au type XSD suivant dans l'espace de noms 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'attribut facultatif ser:FactoryType déclaré dans le schéma de sérialisation du contrat de données référence une classe de fabrique qui peut désérialiser le type. La classe de fabrique doit faire partie de la collection de types connus de l'instance DataContractSerializer qui est utilisée. Pour plus d'informations sur les types connus, consultez Types connus de contrats de données.

Schéma de sérialisation DataContract

Plusieurs schémas exportés par DataContractSerializer, utilisent des types, des éléments et des attributs d'un espace de noms spécial de la sérialisation du contrat de données :

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

Voici une déclaration de schéma de sérialisation du contrat de données complète.

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

Il convient de remarquer les points suivants :

• ser:char est introduit pour représenter des caractères Unicode de type Char.
• Le valuespace de xs:duration est réduit à un jeu ordonné afin qu'il puisse être mappé à un TimeSpan.
• FactoryType est utilisé dans les schémas exportés des types dérivés de ISerializable.

Importation de schémas qui ne sont pas DataContract

DataContractSerializer dispose de l'option ImportXmlTypes pour autoriser l'importation des schémas non conformes au profil XSD DataContractSerializer (consultez la propriété Options). Affecter à cette option la valeur true active l'acceptation des types de schémas non conformes et les mappe à l'implémentation suivante, IXmlSerializable qui encapsule un tableau de XmlNode (seul le nom de la classe diffère).

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

Sérialisation DateTimeOffset

DateTimeOffset n'est pas traité comme un type primitif. À la place, il est sérialisé comme un élément complexe comportant deux parties. La première partie représente la date et l'heure et la deuxième partie représente l'offset de la date et de l'heure. Un exemple d'une valeur DateTimeOffset sérialisée est illustré dans le code suivant.

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

Le schéma se présente comme suit :

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

Voir aussi

Référence

DataContractSerializer
DataContractAttribute
DataMemberAttribute
XsdDataContractImporter

Concepts

Utilisation de contrats de données