Prise en charge de la liaison de l'élément Attribute

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 prend en charge la liaison pour l'élément <attribute>.

Toutefois, Xsd.exe ne fait pas de distinction entre un attribut déclaré localement et une référence à un attribut déclaré globalement, sauf si l'attribut global est déclaré dans un espace de noms autre que l'espace de noms cible du schéma.

Explication

La spécification de schéma XML indique qu'un attribut peut être déclaré localement, dans une définition de type complexe, ou globalement, auquel cas il peut être référencé par une ou plusieurs définitions de type complexe via l'attribut ref.

Voici un exemple d'un attribut déclaré localement :

<xsd:complexType name="PurchaseOrderType">
  <xsd:sequence>
    <xsd:element name="field1" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string"/>
</xsd:complexType>

Voici un exemple du même attribut déclaré globalement, puis référencé :

<xsd:attribute name="name" type="xsd:string"/>
<xsd:complexType name="PurchaseOrderType">
  <xsd:sequence>
    <xsd:element name="field1" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute ref="name"/>
</xsd:complexType>

Xsd.exe ne fait pas de distinction entre un attribut déclaré localement et une référence à un attribut déclaré globalement, sauf si l'attribut global est déclaré dans un espace de noms autre que l'espace de noms cible du schéma.

Référence dans le même espace de noms

Dans la mesure où Xsd.exe ne fait pas de distinction dans le même espace de noms, une traduction aller-retour d'un schéma XML en classes et vice-versa crée un attribut local qui remplace la référence et l'attribut global.

Référence à un autre espace de noms

Si une déclaration globale référencée appartient à un espace de noms différent, Xsd.exe spécifie l'espace de noms à l'aide de la propriété Namespace d'un attribut XmlAttributeAttribute qui s'applique au champ généré. Pour cet élément spécifique, l'espace de noms spécifié par la propriété Namespace substitue l'espace de noms spécifié au niveau de la classe à l'aide de l'attribut XmlTypeAttribute et, éventuellement, de l'attribut XmlRootAttribute. Voici un exemple :

[System.Xml.Serialization.XmlAttributeAttribute(Namespace="http://example.org/attr")]

public string Key;

Des espaces de noms supplémentaires sont importés dans une définition de schéma XML à l'aide de l'élément <import>.

Example

Ce premier exemple indique comment Xsd.exe traite un attribut global lorsqu'il est défini dans le même espace de noms cible qui contient une référence à cet attribut.

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

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            xmlns="http://example.org/" targetNamespace="http://example.org/" elementFormDefault="qualified">
  <xsd:attribute name="version" type="xsd:string"/>
  <xsd:complexType name="keyInfo">
    <xsd:attribute ref="version" />
    <xsd:attribute name="public" type="xsd:boolean" use="required"/>
  </xsd:complexType>
  <xsd:element name="key" type="keyInfo"/>
</xsd:schema>

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

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("key", Namespace="http://example.org/", IsNullable=false)]
public class keyInfo {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public string version;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public bool @public;
}

Document de schéma XML généré à partir d'un assembly compilé depuis la source C# précédente :

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="key" type="tns:keyInfo" />
  <xs:complexType name="keyInfo">
    <xs:attribute name="version" type="xs:string" />
    <xs:attribute name="public" type="xs:boolean" />
  </xs:complexType>
</xs:schema>

Dans le schéma XML généré précédemment, l'attribut de version, déclaré globalement à l'origine, est devenu un attribut local.

Ce deuxième exemple indique comment Xsd.exe traite une référence à un attribut global lorsque cet attribut est défini dans un espace de noms séparé. Cet exemple utilise l'élément <import> pour importer un deuxième espace de noms situé dans un fichier XSD séparé. (L'attribut schemaLocation de l'élément <import> n'est pas utilisé pour spécifier l'emplacement du fichier .xsd importé. À la place, le fichier est spécifié comme un argument de ligne de commande supplémentaire pour Xsd.exe.)

Document de schéma XML de niveau supérieur utilisé comme entrée :

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
            xmlns="http://example.org/" targetNamespace="http://example.org/" xmlns:attr="http://example.org/attr">
  <xsd:import  namespace="http://example.org/attr" />
  <xsd:element name="key" type="keyInfo" />
  <xsd:complexType name="keyInfo">
    <xsd:attribute ref="attr:version" />
    <xsd:attribute name="public" type="xsd:boolean" use="required" />
  </xsd:complexType>
</xsd:schema>

Document de schéma XML importé utilisé comme entrée :

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
            xmlns="http://example.org/attr" targetNamespace="http://example.org/attr">
  <xsd:attribute name="version" type="xsd:string" />
</xsd:schema>

Classe C# générée à partir des deux documents de schéma XML précédents :

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("key", Namespace="http://example.org/", IsNullable=false)]
public class keyInfo {
        
    [System.Xml.Serialization.XmlAttributeAttribute(Namespace="http://example.org/attr")]
    public string version;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public bool @public;
}

Document de schéma XML de niveau supérieur généré à partir d'un assembly compilé depuis la source C# précédente :

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://example.org/attr" />
  <xs:element name="key" type="tns:keyInfo" />
  <xs:complexType name="keyInfo">
    <xs:attribute xmlns:q1="http://example.org/attr" ref="q1:version" />
    <xs:attribute name="public" type="xs:boolean" />
  </xs:complexType>
</xs:schema>

Document de schéma XML importé généré à partir d'un assembly compilé depuis la source C# précédente :

<xs:schema xmlns:tns="http://example.org/attr" elementFormDefault="qualified" targetNamespace="http://example.org/attr" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:attribute name="version" type="xs:string" />
</xs:schema>

Attribut use

L'attribut use d'une déclaration <attribute> détermine si l'attribut peut ou doit apparaître dans une instance de document XML.

Attribut use : génération de code source à partir d'un document de schéma XML

Xsd.exe interprète une valeur optional pour l'attribut use si une valeur d'attribut par défaut a été spécifiée via l'attribut default. Les valeurs possibles pour use, y compris les combinaisons optional et default, sont répertoriées avec leurs sorties Xsd.exe comme suit :

required : Xsd.exe génère un champ public avec un System.Xml.Serialization.XmlAttributeAttribute.
optional avec default spécifié : Xsd.exe génère un champ public avec un XmlAttributeAttribute et un System.Component.DefaultValueAttribute spécifiant la valeur par défaut.
optional sans default spécifié : Xsd.exe génère un champ public avec un XmlAttributeAttribute. De plus, si le type de l'attribut n'est pas un type référence (par exemple, une chaîne), il génère un champ public de type bool dont le nom est le nom du champ d'attribut avec Specified 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.
prohibited : Xsd.exe ne génère rien.

Attribut use : génération d'un document de schéma XML à partir de classes

Dans l'un des deux cas suivants, Xsd.exe ne spécifie pas l'attribut use, rétablissant la valeur par défaut optional :

Un champ public supplémentaire bool respectant la convention d'affectation de noms Specified est présent.
Une valeur par défaut est assignée au membre via un attribut de type System.Component.DefaultValueAttribute.

Si aucune de ces conditions n'est satisfaite, Xsd.exe génère une valeur required pour l'attribut use.

Exemple : attribut use

Type complexe de schéma XML d'entrée :

<xsd:complexType name="Numbers">
  <xsd:attribute name="optionalNumber" type="xsd:int" use="optional"/>
  <xsd:attribute name="requiredNumber" type="xsd:int" use="required"/>
  <xsd:attribute name="prohibitedNumber" type="xsd:int" use="prohibited"/>
</xsd:complexType>

Classe C# générée à partir du type complexe précédent :

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute(Namespace="http://example.org/", IsNullable=false)]
public class Numbers {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public int optionalNumber;
        
    [System.Xml.Serialization.XmlIgnoreAttribute()]
    public bool optionalNumberSpecified;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public int requiredNumber;
}

Le type complexe généré à partir de la classe C# précédente équivaut au type complexe d'origine.

Attributs possibles	Prise en charge de la liaison
default	L'attribut default 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. Lors de la génération du code source à partir d'un schéma XML, l'outil Xsd.exe prend chaque champ correspondant à 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)] [System.Xml.Serialization.XmlAttributeAttribute()] public int age = -1;` De plus, lors de la génération du code source à partir d'un schéma, Xsd.exe vérifie si l'attribut default a été spécifié pour déterminer comment interpréter un attribut use avec une valeur `optional`. Consultez l'attribut default pour obtenir une explication complète. L'outil Xsd.exe ne parvient pas à générer un code source valide pour les attributs de types de listes avec les valeurs par défaut. Ce cas est décrit avec l'attribut default. Consultez également l'élément <list>.
fixed	Pour les déclarations <attribute>, Xsd.exe utilise la valeur de l'attribut fixed pour initialiser statiquement le champ à la valeur fixed, comme dans l'exemple suivant : `[System.Xml.Serialization.XmlAttribute()] public in age = -1;` Consultez l'attribut fixed.
form	L'outil Xsd.exe assimile l'attribut XML form de l'élément <attribute>> à la propriété Form de XmlAttributeAttribute. L'infrastructure de sérialisation XML du .NET Framework reconnaît la valeur par défaut du schéma XML, `unqualified`. Si une déclaration <attribute> dans un schéma XML spécifie `form="qualified"`, Xsd.exe génère un attribut XmlAttribute pour le champ correspondant et passe un paramètre `Form=XmlSchemaForm.Qualified` à l'attribut. Consultez l'attribut form.
id	L'utilitaire Xsd.exe ignore l'attribut id qui a pour but de fournir un identificateur unique. À la place, Xsd.exe reconnaît l'attribut name.
name	Pour la génération du code source à partir d'un document XSD, la valeur de l'attribut name fournit le nom du champ de classe public qui représente cet attribut. Si un nom est en conflit avec un mot clé réservé, le nom résultant est précédé du symbole @. Lorsque Xsd.exe génère une déclaration <attribute> à partir d'un champ de classe public, il utilise le nom de champ pour la valeur de l'attribut name. Un autre nom (valeur de l'attribut name) peut être fourni via la propriété AttributeName. Consultez l'attribut Prise en charge de la liaison de l'attribut Name.
ref	Lors de la génération d'un type .NET Framework à partir d'un type complexe de schéma XML, Xsd.exe ne fait pas de distinction entre un attribut déclaré localement et une référence à un attribut déclaré globalement, sauf si l'attribut global est déclaré dans un espace de noms autre que l'espace de noms cible du schéma. Consultez les sections Référence dans le même espace de noms et Référence à un autre espace de noms.
type	L'outil Xsd.exe associe les types de données référencés à l'attribut type des déclarations <attribute> et <element> aux types .NET Framework. Xsd.exe ne génère pas de type .NET Framework pour un type de données de schéma XML, à moins que le type de données ne permette de remonter jusqu'à une déclaration d'élément globale faisant référence à un type de données via l'attribut type.
use	Si `use=“optional”`, Xsd.exe vérifie la présence de l'attribut default pour déterminer s'il faut générer un DefaultValueAttribute ou un champ –Specified supplémentaire. Le champ supplémentaire n'est pas généré pour les types référence (par exemple, strings). En cas d'absence de ces éléments pour un champ public, Xsd.exe spécifie `use=“required”` dans un document XSD généré. Consultez la section Attribute use précédente.

Éléments parents possibles : <attributeGroup>, <complexType>, <extension>, <restriction>, <schema>

Éléments enfants possibles : <annotation>, <simpleType>

Voir aussi

Référence

XmlSchemaAttribute