Bindungsunterstützung für das minOccurs-Attribut

Dieses Thema bezieht sich auf eine veraltete Technologie. XML-Webdienste und XML-Webdienstclients sollten nun mithilfe der folgenden Technologie erstellt werden: Windows Communication Foundation.

.NET Framework stellt partielle Bindungsunterstützung für das minOccurs-Attribut bereit.

Xsd.exe überprüft den Wert des minOccurs-Attributs ausschließlich für das <element>-Element nur dann, wenn mit dem Wert des Bindungsunterstützung für das maxOccurs-Attribut-Attributs kein Arrayfeld festgelegt wird. Der Wert wird anschließend nach verschiedenen Faktoren interpretiert (oder erstellt), je nachdem, ob das entsprechende Feld einen Verweis- oder Werttyp aufweist.

Erklärung

Mit dem minOccurs-Attribut und dem maxOccurs-Attribut wird einschränkend festgelegt, wie oft in Folge die angegebene Entität in der entsprechenden Position in einem XML-Instanzendokument angezeigt werden kann.

Diese Attribute werden nur in komplexen Typdefinitionen angezeigt. Aus diesem Grund muss es sich bei einem <element>-Element oder einem <group>-Element um eine lokale Deklaration oder einen Verweis auf eine globale Deklaration und nicht um die eigentliche Deklaration handeln.

Zur Bindung von komplexen XML-Schematypen mit nicht XML spezifischen Klassen bietet .NET Framework keine direkte dem minOccurs-Attribut oder dem maxOccurs-Attribut entsprechende Programmiersprache.

Übersetzen von XSD in Quellcode

Beim Generieren von Quellcode aus einem XML-Schemadokument ignoriert Xsd.exe das minOccurs-Attribut, das auf die Elemente <choice>, <sequence>, <group>, <all> und <any> angewendet wird.

Beim <element>-Element ignoriert Xsd.exe das minOccurs-Attribut, wenn der Wert des maxOccurs-Attributs größer als 1 oder unbounded ist. In diesem Fall erstellt das Tool ein Array des Typs, der dem XSD-Datentyp entspricht. Xsd.exe legt mit dem Wert des maxOccurs-Attributs fest, ob eine einzelne Instanz oder ein Array erstellt wird.

Beim <element>-Element ignoriert Xsd.exe zudem das minOccurs-Attribut, wenn es auf einen Schemadatentyp angewendet wird, der in einen .NET Framework-Verweistyp konvertiert wird.

Nur wenn alle folgenden Bedingungen erfüllt sind, verwendet Xsd.exe den Wert des minOccurs-Attributs:

• Das <element>-Element wird einbezogen.

• Über das maxOccurs-Attribut wird eine einzelne Instanz festgelegt.

• Der Datentyp wird in einen Werttyp konvertiert.

Das Tool interpretiert den Wert anschließend folgendermaßen:

• 1 or more: Xsd.exe generiert ein öffentliches Feld. Es wird kein XML-Attribut angewendet, folglich wird das als Standard definierte System.Xml.Serialization.XmlElementAttribute verwendet.

• 0: Xsd.exe generiert ein öffentliches Feld. Es wird kein XML-Attribut angewendet, deshalb wird das standardmäßige XmlElementAttribute verwendet. Darüber hinaus generiert Xsd.exe ein öffentliches Feld vom Typ bool, dessen Name der Name des Elementfelds mit nachgestelltem Specified ist. Wenn das Elementfeld beispielsweise den Namen startDate hat, wird der Name des bool-Felds zu startDateSpecified. Beim Serialisieren eines Objekts in XML überprüft die XmlSerializer-Klasse den Wert des bool-Felds, um festzulegen, ob das Element geschrieben werden soll. Das bool-Feld wird mit System.Xml.Serialization.XmlIgnoreAttribute dargestellt, um zu verhindern, dass es von XmlSerializer serialisiert wird.

Weitere Informationen zu Arraybindungen. Einbußen bei der Definitionsgenauigkeit entstehen, wenn Xsd.exe das minOccurs-Attribut in dem Fall ignoriert, dass der maxOccurs-Attributwert eine Arraybindung festlegt. Bei einer Rückübersetzung aus dem generierten Array in eine neue <element>-Deklaration wird nicht der ursprüngliche minOccurs-Wert, sondern der Wert0 sowie der Wert unbounded für maxOccurs erstellt.

Betrachten Sie zum besseren Verständnis der Typbindung mit einem Array den Unterschied zwischen dem Deklarieren eines Objekts eines bestimmten Typs und dem Zuweisen eines Werts (d. h. einen Speicherort im Stapel oder Heap) zu diesem Objekt. Beginnen Sie mit dem folgenden XSD-Element:

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

Beim manuellen Schreiben von Code wird die Arraygröße 5 in der Typdeklaration nicht angegeben, d. h.: public string[] items. Stattdessen wird die Arraygröße beim Zuweisen eines Werts angegeben: items = new string[5].

Xsd.exe erstellt aus einem XML-Schema als Quellcode lediglich Typ- und Felddeklarationen sowie Metadaten, die als Attribute auf Typen und Felder angewendet werden können. Durch Zuweisen von Werten zu Objekten wird dieser Gültigkeitsbereich erweitert.

Sie können einen größeren Wert als 1 erzwingen, indem Sie ein XML-Dokument mit der XmlValidatingReader-Klasse mit einem durch das Schemaobjektmodell (SOM) dargestellten XML-Schemadokument überprüfen. Das SOM verwendet die System.Xml.Schema.XmlSchemaParticle.MinOccurs-Eigenschaft und die System.Xml.Schema.XmlSchemaParticle.MinOccursString-Eigenschaft. Beide Eigenschaften gelten für alle Elemente, die ein minOccurs-Attribut enthalten können.

Weitere Informationen zur Verarbeitung von Vorkommensbeschränkungen in unterschiedlichen Elementen der XML-Schemadefinitionssprache finden Sie in den Ausführungen zum maxOccurs-Attribut.

Übersetzen von Quellcode in XSD

Der mit Xsd.exe beim Generieren eines XML-Schemadokuments aus Klassen erstellte minOccurs-Wert hängt vom generierten enthaltenden Element der XML-Schemadefinitionssprache ab. Die möglichen enthaltenen Elemente sowie das entsprechende minOccurs-Verhalten sind im Folgenden aufgeführt:

<choice>: 1, wenn die Auswahl ein einzelnes Objekt darstellt, 0, wenn die Auswahl ein Array darstellt.

<sequence>: Nicht angegeben, wird auf den Standardwert 1 zurückgesetzt.

<group>: Xsd.exe generiert kein <group>-Element aus dem Quellcode.

<all>: Xsd.exe generiert kein <all>-Element aus dem Quellcode.

<any>: 0 entsprechend den für das <element>-Element erklärten Regeln. Das <any>-Element wird weiter unten in diesem Thema erläutert.

<element>: Xsd.exe erstellt unterschiedliche Werte für minOccurs, je nachdem, ob es sich bei einem Feld oder einer Eigenschaft um ein Array oder eine einzelne Instanz handelt, ob ein Feld oder eine Eigenschaft über einen Werttyp oder einen Verweistyp verfügt, ob ein Werttyp über einen Standardwert oder ein zusätzliches Feld mit Angaben dazu verfügt, ob ein Wert angegeben wurde, sowie ob einem XML-Attribut mit einer IsNullable-Eigenschaft und dem Wert true ein Verweistyp zugewiesen ist.

Die IsNullable-Eigenschaft wird in bestimmten XML-Attributklassen verwendet. Die Eigenschaft wird folgendermaßen dargestellt:

• System.Xml.Serialization.XmlElementAttribute.IsNullable

• System.Xml.Serialization.XmlRootAttribute.IsNullable

• System.Xml.Serialization.XmlArrayAttribute.IsNullable

• System.Xml.Serialization.XmlArrayItemAttribute.IsNullable

Wenn die IsNullable-Eigenschaft eines Klassenmembers auf true festgelegt ist und ein Objekt auf einen NULL-Verweis (Nothing in Visual Basic) festgelegt wurde, generiert die XmlSerializer-Klasse ein xsi:nil-Attribut mit dem Wert true. (Das Präfix xsiwird für den XML-Schemainstanz-Namespace, http://www.w3.org/2001/XMLSchema-instance, verwendet).

Der Wert xsi:nil="true" in einem Element eines Instanzendokuments gibt ausdrücklich an, dass das Element keinen Inhalt hat, d. h. weder untergeordnete Elemente noch Textkörper. Weitere Informationen finden Sie in den Ausführungen zum xsi:nil-Attribut.

Die IsNullable-Eigenschaft entspricht dem nillable-Attribut in der XML-Schemadefinitionssprache. Wenn Xsd.exe beim Generieren von XSD-Definitionen aus Klassen einen true-Wert für eine Klasse oder die Eigenschaft IsNullable eines Members findet (und der Typ einem NULL-Verweis zugewiesen werden kann), wird für das entsprechende <element>-XSD-Element eine nillable="true"-Einstellung generiert. Weitere Informationen finden Sie in den Ausführungen zum nillable-Attribut.

Mit den in der folgenden Tabelle aufgeführten Regeln wird der Wert des minOccurs-Attributs entsprechend einem Klassenmember festgelegt, der eine einzelne Instanz ist. Für Arrays gelten dieselben Regeln, mit einer Ausnahme, die weiter unten in diesem Thema beschrieben wird. Die Tabelle ist entsprechend den unterschiedlichen relevanten Klassenmembern und den entsprechenden minOccurs-Werten angeordnet:

Eingabe für Klassenmember	minOccurs-Wert des <element>-Ausgabeelements
Werttyp mit einem über System.Component.DefaultValueAttribute angegebenen Standardwert.	0. Im <element>-Element wird der Standardwert auch über das default-XML-Attribut angegeben.
Werttyp mit einem öffentlichen bool-Feld, in dem die weiter oben unter Übersetzen von XSD in Quellcode beschriebene Specified-Namenskonvention verwendet wird.	0.
Werttyp ohne Standardwert oder entsprechendes boolesches Feld.	1.
Verweistyp, bei dem die IsNullable-Eigenschaft des XmlElement-Attributs auf true festgelegt ist.	1. Im <element>-Element ist das nillable-Attribut ebenfalls auf true festgelegt.
Verweistyp mit IsNullable=false oder ohne IsNullable-Einstellung.	0.

Xsd.exe behält diese kennzeichnenden Funktionen bei einer Rückübersetzung eines XML-Schemadokuments in Quellcode bei.

Hinweis: Wenn ein default-XML-Attribut mit einem minOccurs-Attribut angezeigt wird, das auf 0 festgelegt ist, und der Datentyp einem Werttyp zugeordnet ist, wird nur das DefaultValue-Attribut generiert, das entsprechende boolesche Feld dagegen nicht. Weitere Informationen finden Sie in den Ausführungen zum default-Attribut.

Im nachstehenden Beispiel wurde das folgende Element in der Eingabequelldatei gefunden:

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

Arraybindungen. Xsd.exe erstellt immer die folgende <element>-Deklaration für Arrays.

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

Dies gilt, da Arraytypen Verweistypen sind. Im Gegensatz zu anderen Verweistypen gilt dies jedoch auch, wenn die folgende Attributdeklaration auf den Arraymember angewendet wird:

[XmlElementAttribute(IsNullable=true)]

Wenn ein XmlElement-Attribut anstelle des standardmäßig verwendeten XmlArrayAttribute auf ein Array angewendet wird, werden die Arrayelemente in einem Instanzendokument als untergeordnete Elemente des Elements angezeigt, das an die Klasse gebunden ist. Es wird kein spezielles übergeordnetes Element ausschließlich für das Arrayelement eingefügt. Wenn Xsd.exe durch Erstellen eines Elements mit nillable="true" die IsNullable=true-Eigenschaft erkennt, wird der Wert 0 für minOccurs weiterhin generiert. Zudem müssen die Arrayelemente weiterhin nicht angegeben werden.

Wenn das XmlArray-Standardattribut angewendet wird, wird zur Darstellung des übergeordneten Elements für das Array ein Schemadatentyp erstellt, dessen Name mit ArrayOf beginnt. Weitere Informationen zu Arraybindungen finden Sie in den Ausführungen zum maxOccurs-Attribut und unter Steuern der XML-Serialisierung mit Attributen.

Der Schemadatentyp des übergeordneten Elements entspricht einem Verweistyp, der in Xsd.exe beim Generieren eines minOccurs-Werts als solcher verabeitet wird. Dies bedeutet, dass der Wert 1 für minOccurs folgendermaßen generiert wird, wenn die IsNullable-Eigenschaft auf true festgelegt ist:

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

Andernfalls wird der Wert 0 für minOccurs generiert.

<any>-Element. Xsd.exe generiert minOccurs="0" für ein <any>-Element, unabhängig davon, ob es sich um ein einzelnes Objekt oder ein Array handelt, da das entsprechende Codekonstrukt ein Verweistyp ist. Dieses Konstrukt ist ein Feld des Typs System.Xml.XmlElement (oder ein Array davon) mit dem System.Xml.Serialization.XmlAnyElementAttribute-Attribut. Die Attributdeklaration [XmlElementAttribute(IsNullable=true)] kann auf das XmlElement-Objekt oder das Array angewendet werden, Xsd.exe interpretiert diese Verwendung jedoch nicht als <any>-Element mit minOccurs="1".

Mögliche enthaltene Elemente: <all>, <any>, <choice>, <element>, <group>, <sequence>

Siehe auch

Verweis

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