Prise en charge de la liaison de l'attribut par défaut

Article
02/27/2011

Cette rubrique est spécifique à une technologie existante. Les services Web XML et les clients du service Web XML doivent à présent être créés à l'aide de Windows Communication Foundation.

Le .NET Framework fournit la prise en charge de liaison partielle pour l'attribut default.

L'outil Xsd.exe assimile une valeur d'élément ou d'attribut par défaut à un System.ComponentModel.DefaultValueAttribute appliqué à un champ généré ; le champ est également réinitialisé statiquement.

Explication

L'attribut default, qui peut apparaître dans une déclaration <element> ou <attribute>, fournit une valeur par défaut à utiliser si l'élément est vide ou si l'attribut n'est pas présent lorsqu'une instance de document est reçue.

Pour les attributs, une valeur par défaut est pertinente uniquement si un attribut est facultatif (l'attribut use décrit dans Prise en charge de la liaison de l'élément Attribute a la valeur par défaut optional). Lorsqu'un attribut est spécifié, il doit l'être avec une valeur.

Pour les éléments, une valeur par défaut est utilisée uniquement si l'élément apparaît dans une instance de document sans contenu. Si l'élément n'apparaît pas du tout, il n'est pas rempli.

Lors de la génération du code source à partir d'un document de schéma XML, Xsd.exe prend chaque champ correspondant à un élément ou un attribut avec une valeur par défaut et applique un System.ComponentModel.DefaultValueAttribute, en passant la valeur par défaut comme un argument. De plus, Xsd.exe initialise statiquement le champ avec la valeur par défaut, comme dans l'exemple suivant :

[System.ComponentModel.DefaultValueAttribute(-1)]
public int age = -1;

L'attribut par défaut sera ignoré sur les tableaux (éléments dont maxOccurs est supérieur à 1).

Prise en charge de la liaison par type de données

D'après le schéma XML, la valeur de l'attribut default doit correspondre à un type simple. Pour la plupart des types simples, Xsd.exe conserve la valeur par défaut lorsqu'il exécute une traduction aller-retour du schéma XML vers les classes et inversement vers un nouveau document de schéma XML.

Les éléments ou les attributs de type xsd:base64Binary ou xsd:hexBinary constituent une exception. Un attribut DefaultValue n'est pas appliqué au champ System.Byte correspondant créé.

Les attributs des types de listes constituent également une exception. La construction <list> permet de définir un type simple dont les valeurs possibles sont une série de valeurs séparées par des espaces provenant d'un autre type simple. (Xsd.exe ne génère pas de code source pour les éléments des types de listes.) Pour les listes, Xsd.exe crée un tableau du type constitutif, mais convertit la valeur par défaut en instance du type constitutif, et non en tableau.

Considérons la déclaration <attribute> d'entrée suivante :

<xsd:attribute name="siblings" default="unknown">
  <xsd:simpleType>
    <xsd:list itemType="xsd:string"/>
  </xsd:simpleType>
</xsd:attribute>

Pour cette déclaration, le code source suivant est généré :

[System.Xml.Serialization.XmlAttributeAttribute()]
[System.ComponentModel.DefaultValueAttribute("unknown")]
public string[] siblings = "unknown";

Cette source ne parvient pas à effectuer la compilation, car un objet String ne peut pas être converti implicitement en tableau d'objets String. La même erreur survient pour les listes de tous les types simples, notamment les types énumération.

Effet sur l'attribut minOccurs pour les types valeur de liaison d'élément

Supposez qu'un membre d'une classe a un type valeur .NET Framework et est mappé à un élément XML (via l'attribut XmlElementAttribute par défaut). Si Xsd.exe rencontre un attribut DefaultValue appliqué à ce membre lors de la génération d'un document XSD à partir des classes, il génère la valeur 0 pour l'attribut minOccurs de l'élément <element>. Cela indique que l'élément n'a pas besoin d'apparaître dans une instance de document XML valide.

Combinaison avec use="optional" pour les attributs

Supposons qu'une déclaration <attribute> contient un attribut use auquel est affectée la valeur optional, qui correspond également à la valeur par défaut. Lors de la génération du code source à partir d'un document XSD, Xsd.exe interprète cette valeur différemment selon que l'attribut default a été ou non spécifié. Les deux interprétations possibles sont les suivantes :

défaut spécifié : Xsd.exe génère un champ public avec un XmlAttributeAttribute plus un DefaultValueAttribute qui spécifie la valeur par défaut.
aucun default spécifié : Xsd.exe génère un champ public avec un XmlAttributeAttribute. De plus, pour les types valeur, il génère un champ public de type bool dont le nom correspond au nom du champ d'attribut auquel Specified est ajouté. Par exemple, si le nom du champ d'attribut est startDate, le nom du champ bool devient startDateSpecified. Lors de la sérialisation d'un objet vers XML, la classe XmlSerializer vérifie la valeur du champ bool pour déterminer si l'attribut facultatif doit être écrit. Le champ bool apparaît avec un System.Xml.Serialization.XmlIgnoreAttribute pour l'empêcher d'être sérialisé par XmlSerializer.

Example

Document de schéma XML d'entrée :

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            targetNamespace="http://example.org/" xmlns="http://example.org/" elementFormDefault="qualified">
    <xsd:element name="FamilyDog" type="FamilyDogType"/>

    <xsd:complexType name="FamilyDogType">
        <xsd:sequence>
            <xsd:element name="name" type="xsd:stringo" default="Spot"/>
            <xsd:element name="birthdate" type="xsd:date" default="2002-03-04"/>
        </xsd:sequence>
        <xsd:attribute name="gender" type="GenderType" default="UNKNOWN"/>
        <xsd:attribute name="fixed" type="xsd:boolean" default="false"/>
        <xsd:attribute name="breed" type="xsd:string" default="Swedish Vallhund"/>
    </xsd:complexType>
    
    <xsd:simpleType name="GenderType">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="FEMALE" />
            <xsd:enumeration value="MALE" />
            <xsd:enumeration value="UNKNOWN" />
        </xsd:restriction>
    </xsd:simpleType>
</xsd:schema>

Classes C# générées à partir du document de schéma XML précédent :

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("FamilyDog", Namespace="http://example.org/", IsNullable=false)]
public class FamilyDogType {
        
    [System.ComponentModel.DefaultValueAttribute("Spot")]
    public string name = "Spot";
        
    [System.Xml.Serialization.XmlElementAttribute(DataType="date")]
    [System.ComponentModel.DefaultValueAttribute(typeof(System.DateTime), "2002-03-04")]
    public System.DateTime birthdate = new System.DateTime(631507968000000000);
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    [System.ComponentModel.DefaultValueAttribute(GenderType.UNKNOWN)]
    public GenderType gender = GenderType.UNKNOWN;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    [System.ComponentModel.DefaultValueAttribute(false)]
    public bool @fixed = false;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    [System.ComponentModel.DefaultValueAttribute("Swedish Vallhund")]
    public string breed = "Swedish Vallhund";
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
public enum GenderType {        
    FEMALE,        
    MALE,
    UNKNOWN,
}

Le document de schéma XML généré depuis un assembly compilé à partir du code source C# précédent est identique au schéma XML d'origine à partir duquel la source C# a été générée.

Éléments conteneurs possibles : <attribute>, <element>

Voir aussi

Référence

System.Xml.Schema.XmlSchemaAttribute.DefaultValue
System.Xml.Schema.XmlSchemaElement.DefaultValue