Prise en charge de la liaison de l'attribut MinOccurs

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 partielle pour l'attribut minOccurs.

Xsd.exe vérifie la valeur de l'attribut minOccurs seulement pour l'élément <element>, et ce uniquement si la valeur de l'attribut Prise en charge de la liaison de l'attribut MaxOccurs n'impose pas de champ de tableau. Ensuite, la valeur est interprétée (ou générée) selon différents facteurs, le premier consistant à déterminer si le champ correspondant a un type référence ou un type valeur.

Explication

Les attributs minOccurs et maxOccurs limitent le nombre d'affichages successifs de l'entité spécifiée dans la position correspondante dans une instance de document XML.

Ces attributs apparaissent uniquement dans des définitions de type complexe. Par conséquent, pour un élément <element> ou <group>, l'élément doit être une déclaration locale ou une référence à une déclaration globale, et non la déclaration globale elle-même.

Pour les types complexes de schéma XML de liaison avec des classes non spécifiques XML, le .NET Framework ne fournit pas de langage de programmation directe équivalent à l'attribut minOccurs ou maxOccurs.

Traduction de XSD en source

Lors de la génération du code source à partir d'un document de schéma XML, Xsd.exe ignore l'attribut minOccurs appliqué aux éléments <choice>, <sequence>, <group>, <all> et <any>.

Pour l'élément <element>, Xsd.exe ignore l'attribut minOccurs si la valeur de l'attribut maxOccurs est supérieure à 1 ou est unbounded. Dans ce cas, l'outil produit un tableau de type correspondant au type de données XSD. Xsd.exe utilise la valeur de l'attribut maxOccurs pour déterminer s'il faut générer une seule instance ou un tableau.

Pour l'élément <element>, Xsd.exe ignore également l'attribut minOccurs s'il s'applique à un type de données de schéma qui est converti en un type référence .NET Framework.

Xsd.exe utilise la valeur de l'attribut minOccurs uniquement lorsque toutes les conditions suivantes sont remplies :

L'élément <element> est impliqué.
L'attribut maxOccurs impose une seule instance.
Le type de données est converti en un type valeur.

L'outil interprète ensuite la valeur comme suit :

1 or more : Xsd.exe génère un champ public. Aucun attribut XML n'est appliqué, donc le System.Xml.Serialization.XmlElementAttribute par défaut est utilisé.
0 : Xsd.exe génère un champ public. Aucun attribut XML n'est appliqué, donc XmlElementAttribute par défaut est utilisé. De plus, Xsd.exe génère un champ public de type bool dont le nom correspond au nom du champ d'élément auquel Specified est ajouté. Par exemple, si le nom du champ d'élément 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'élément doit être écrit. Le champ bool apparaît avec un System.Xml.Serialization.XmlIgnoreAttribute pour l'empêcher d'être sérialisé par XmlSerializer.

Informations supplémentaires sur les liaisons de tableau. Une perte de précision de la définition se produit lorsque Xsd.exe ignore l'attribut minOccurs dans le cas où la valeur de l'attribut maxOccurs impose une liaison de tableau. Une traduction inverse du tableau généré en une nouvelle déclaration <element> ne produit pas la valeur minOccurs d'origine, mais une valeur 0, ainsi qu'une valeur maxOccurs qui est unbounded.

Pour comprendre la liaison de type vers un tableau, considérez la différence entre la déclaration d'un objet d'un certain type et l'assignation d'une valeur (littéralement un emplacement de mémoire dans la pile ou le tas) à cet objet. Démarrez avec l'élément XSD suivant :

<xsd:element minOccurs="5" maxOccurs="5" name="items" type="xsd:token" />

En cas d'écriture manuelle du code, vous n'exprimeriez pas la taille du tableau (égale à cinq) dans la déclaration de type, qui serait : public string[] items. En effet, vous exprimeriez la taille du tableau lors de l'assignation d'une valeur : items = new string[5].

Les seuls types de code source générés par Xsd.exe à partir d'un schéma XML sont les déclarations de type et de champ ainsi que les métadonnées qui peuvent être appliquées aux types et aux champs en tant qu'attributs. L'assignation de valeurs à des objets est hors de portée.

L'application d'une valeur supérieure à 1 se fait par la validation d'un document XML avec la classe XmlValidatingReader par rapport à un document de schéma XML représenté par le modèle d'objet de schéma. Le modèle d'objet de schéma utilise les propriétés System.Xml.Schema.XmlSchemaParticle.MinOccurs et System.Xml.Schema.XmlSchemaParticle.MinOccursString, qui s'appliquent chacune à tous les éléments pouvant contenir un attribut minOccurs.

Pour plus d'informations sur la façon dont Xsd.exe gère les contraintes d'apparition dans différents éléments de langage XSD (XML Schema Definition), consultez l'attribut maxOccurs.

Traduction de la source en XSD

La valeur minOccurs que Xsd.exe produit lors de la génération d'un document de schéma XML à partir des classes dépend de l'élément de langage XSD (XML Schema Definition) contenant généré. Les éléments conteneur possibles, ainsi que leur comportement minOccurs, sont répertoriés comme suit :

<choice> : 1 si le choix représente un seul objet, 0 si le choix représente un tableau.

<sequence> : non spécifié, la valeur par défaut 1 est restaurée.

<group> : Xsd.exe ne génère pas d'élément <group> à partir de la source.

<all> : Xsd.exe ne génère pas d'élément <all> à partir de la source.

<any> : 0 d'après les règles expliquées pour l'élément <element>. L'élément <any> est traité ultérieurement dans cette rubrique.

<element> : Xsd.exe produit des valeurs différentes pour minOccurs en fonction des conditions suivantes : un champ ou une propriété est un tableau ou une seule instance ; un champ ou une propriété dispose d'un type valeur ou d'un type référence ; un type valeur dispose d'une valeur par défaut ou d'un champ supplémentaire indiquant une valeur spécifiée ; enfin, un type référence est assigné à un attribut XML avec un ensemble de propriétés IsNullable dont la valeur est true.

La propriété IsNullable est utilisée par certaines classes d'attributs XML. La propriété apparaît comme suit :

Si la propriété IsNullable d'un membre de classe a la valeur true et qu'un objet a la valeur d'une référence Null (Nothing en Visual Basic), la classe XmlSerializer génère un attribut xsi:nil dont la valeur est true. (Le préfixe xsiest utilisé pour l'espace de noms de l'instance de schéma XML, http://www.w3.org/2001/XMLSchema-instance).

La présence de xsi:nil="true" au sein d'un élément dans une instance de document déclare explicitement que l'élément n'a aucun contenu, soit aucun élément enfant ou corps de texte. Consultez l'attribut xsi:nil.

La propriété IsNullable correspond à l'attribut nillable en langage XSD (XML Schema Definition). Si, lors de la génération de définitions XSD à partir de classes, Xsd.exe rencontre une classe ou un membre dont la propriété IsNullable a la valeur true (et dont le type peut se voir assigner une référence Null), un paramètre nillable="true" est généré pour l'élément <element> XSD correspondant. Consultez l'attribut nillable.

Les règles affichées dans le tableau suivant déterminent la valeur de l'attribut minOccurs correspondant à un membre de classe qui est une seule instance. Les tableaux suivent également ces règles, avec une exception, décrites ultérieurement dans cette rubrique. Le tableau est organisé en fonction des variations de membres de classe pertinentes, avec les valeurs minOccurs qui en résultent :

Membre de classe d'entrée	Valeur minOccurs de l'élément <element> de sortie
Type valeur avec une valeur par défaut spécifiée via System.Component.DefaultValueAttribute.	`0`. Dans l'élément <element>, la valeur par défaut est également spécifiée via l'attribut XML default.
Type valeur accompagné d'un champ bool public qui utilise la convention d'affectation des noms `Specified` décrite précédemment à la section Traduction de XSD en source.	`0`.
Type valeur sans valeur par défaut ou champ booléen associé.	`1`.
Type référence avec une propriété IsNullable de l'attribut XmlElement dont la valeur est `true`.	`1`. Dans l'élément <element>, l'attribut nillable a également la valeur `true`.
Type référence avec `IsNullable=false` ou sans paramètre IsNullable.	`0`.

Xsd.exe conserve ces fonctionnalités caractéristiques pour la traduction inverse d'un document de schéma XML en code source.

Remarque : Si un attribut XML default apparaît avec un ensemble d'attributs minOccurs dont la valeur est 0, et que le type de données correspond au type valeur, seul l'attribut DefaultValue est généré. Le champ booléen associé n'est pas généré. Consultez également l'attribut default.

Par exemple, supposez que l'élément suivant soit présent dans le fichier source d'entrée :

<xsd:element name="birthdate" type="xsd:date" default="2002-03-04" minOccurs="0" />Xsd.exe would then produce: 
[System.Xml.Serialization.XmlElementAttribute(DataType="date")]
[System.ComponentModel.DefaultValueAttribute(typeof(System.DateTime), "2002-03-04")]
public System.DateTime birthdate = new System.DateTime(631507968000000000);

Liaisons de tableau. Xsd.exe génère toujours une déclaration <element> au format suivant pour les tableaux.

<element minOccurs="0" maxOccurs="unbounded" />

Cela est vrai, car les types de tableaux sont des types référence. Toutefois, contrairement aux autres types référence, cela est vrai même si la déclaration d'attribut suivante est appliquée au membre de tableau :

[XmlElementAttribute(IsNullable=true)]

Si un attribut XmlElement, au lieu du XmlArrayAttribute par défaut, est appliqué à un tableau, les éléments du tableau apparaissent dans un document d'instance en tant qu'enfants de l'élément qui crée une liaison avec la classe. Aucun élément supplémentaire n'est strictement introduit pour servir de parent aux éléments de tableau. Alors que Xsd.exe reconnaît le paramètre IsNullable=true en produisant un élément avec nillable="true", une valeur minOccurs de 0 est encore générée et les éléments de tableau peuvent être absents.

Si l'attribut par défaut XmlArray est appliqué, un type de données de schéma, dont le nom commence par ArrayOf, est créé pour représenter l'élément parent du tableau. Pour plus d'informations sur les liaisons de tableau, consultez l'attribut maxOccurs et la section Contrôle de la sérialisation XML à l'aide d'attributs.

Le type de données de schéma de l'élément parent correspond à un type référence, traité comme tel par Xsd.exe lors de la génération d'une valeur minOccurs. En d'autres termes, une valeur minOccurs de 1 est générée si la propriété IsNullable a la valeur true, comme suit :

[System.Xml.Serialization.XmlArrayAttribute(IsNullable=true)]

Sinon, une valeur minOccurs de 0 est générée.

Élément <any>. Xsd.exe génère minOccurs="0" pour un élément <any>, qu'un seul objet ou qu'un tableau soit impliqué, car la construction de code équivalente est un type référence. Cette construction est un champ (ou un tableau) de type System.Xml.XmlElement avec un attribut System.Xml.Serialization.XmlAnyElementAttribute. Une déclaration d'attribut, [XmlElementAttribute(IsNullable=true)], pourrait être appliquée à l'objet ou au tableau XmlElement, mais Xsd.exe n'interprète pas cette utilisation comme un élément <any> avec minOccurs="1".

Éléments conteneurs possibles : <all>, <any>, <choice>, <element>, <group>, <sequence>

Voir aussi

Référence

System.Xml.Schema.XmlSchemaParticle.MinOccurs
System.Xml.Schema.XmlSchemaParticle.MinOccursString
XmlSchemaAll
XmlSchemaAny
XmlSchemaChoice
XmlSchemaElement
XmlSchemaGroupRef
XmlSchemaSequence