Поддержка привязки атрибута MinOccurs

Этот раздел посвящен технологии прежних версий. Веб-службы XML и клиенты веб-служб XML должны создаваться с использованием Windows Communication Foundation.

Платформа .NET Framework обеспечивает частичную поддержку привязки для атрибута minOccurs.

Программа Xsd.exe проверяет значение атрибута minOccurs только для элемента <element> и только в том случае, если значение атрибута Поддержка привязки атрибута MaxOccurs не указывает поле массива. Затем значение интерпретируется в зависимости от различных факторов, начиная с того, имеет ли соответствующее поле ссылочный тип или тип значения.

Объяснение

Атрибуты minOccurs и maxOccurs ограничивают число последовательных появлений заданной сущности в соответствующей позиции в документе экземпляра XML.

Эти атрибуты появляются только в определениях сложных типов. Поэтому для элемента <element> или <group> элемент должен быть локальным объявлением или ссылкой на глобальное объявление, но не глобальным объявлением.

Для связывания сложных типов схемы XML и классов, неспецифичных для XML, платформа .NET Framework не предоставляет прямого языкового эквивалента атрибутов minOccurs и maxOccurs.

Преобразование XSD в исходный код

При создании исходного кода по документу схемы XML программа Xsd.exe не обрабатывает атрибут minOccurs для элементов <choice>, <sequence>, <group>, <all> и <any>.

Для элемента <element> программа Xsd.exe не обрабатывает атрибут minOccurs, если значение атрибута maxOccurs больше 1 или равно unbounded. В таком случае создается массив типа, соответствующего типу данных XSD. Программа Xsd.exe использует значение атрибута maxOccurs, определяя, создать ли один экземпляр или массив.

Для элемента <element> программа Xsd.exe также не обрабатывает атрибут minOccurs, если он применен к типу данных схемы, который преобразуется в ссылочный тип платформы .NET Framework.

Xsd.exe использует значение атрибута minOccurs, только если выполняются все перечисленные условия:

• задействован элемент <element>;

• атрибут maxOccurs требует один экземпляр;

• тип данных преобразуется в тип значения.

Тогда значение интерпретируется следующим образом:

• 1 or more: программа Xsd.exe генерирует открытое поле. Не применены атрибуты, связанные с XML, поэтому используется атрибут по умолчанию System.Xml.Serialization.XmlElementAttribute.

• 0: программа Xsd.exe генерирует открытое поле. Не применены атрибуты, связанные с XML, поэтому используется атрибут по умолчанию XmlElementAttribute. Кроме того, программа Xsd.exe генерирует открытое поле типа bool, именем которого является имя поля элемента с присоединенным словом Specified. Например, если имя поля элемента — startDate, именем поля bool будет startDateSpecified. При сериализации объекта в XML класс XmlSerializer проверяет значение поля bool, чтобы определить, записывать ли элемент. Поле bool имеет атрибут System.Xml.Serialization.XmlIgnoreAttribute для предотвращения сериализации объектом XmlSerializer.

Дополнительные сведения о привязке массива. Когда Xsd.exe пропускает атрибут minOccurs, в случае если значение атрибута maxOccurs задает привязку массива, происходит потеря точности определения. Обратное преобразование из созданного массива в новое объявление <element> создает не исходное значение minOccurs, а значение 0, а также значение maxOccurs unbounded.

Чтобы понять привязку типов к массиву, обратите внимание на разницу между объявлением объекта определенного типа и присваиванием значения (буквально, ячейки памяти стека или кучи) этому объекту. Рассмотрим следующий элемент XSD:

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

При написании кода вручную вы не станете выражать размер массива (5) в объявлении типа, которое будет таким: public string[] items. Вместо этого вы укажете размер массива при присваивании значения: items = new string[5].

Xsd.exe генерирует из схемы XML только исходный код объявлений типов и полей, плюс метаданные, которые могут применяться к типам и полям как атрибуты. Присваивание значений объектам выходит за рамки области действия.

Способ принудительно задать значение больше 1 — проверить документ XML при помощи класса XmlValidatingReader на соответствие документу схемы XML, представленному объектной моделью схемы (SOM). Объектная модель схемы использует свойства System.Xml.Schema.XmlSchemaParticle.MinOccurs и System.Xml.Schema.XmlSchemaParticle.MinOccursString, оба они применяются ко всем элементам, которые могут содержать атрибут minOccurs.

Более подробную информацию о том, как программа Xsd.exe обрабатывает ограничения по числу вхождений для различных элементов XSD, см. в разделе об атрибуте maxOccurs.

Преобразование исходного кода в XSD

Значение minOccurs, которое создает программа Xsd.exe при генерации документа схемы XML из классов, зависит от генерируемого элемента XSD, содержащего атрибут. Ниже приведен список элементов, которые могут содержать данный атрибут, и описано, что происходит с их атрибутом minOccurs.

<choice>: 1, если элемент choice представляет один объект, и 0, если элемент choice представляет массив.

<sequence>: не определено, возвращается значение по умолчанию — 1.

<group>: программа Xsd.exe не создает элемент <group> по исходному коду.

<all>: программа Xsd.exe не создает элемент <all> по исходному коду.

<any>: 0 в соответствии с правилами для элемента <element>. Элемент <any> подробно обсуждается далее в этом разделе.

<element>: программа Xsd.exe создает различные значения для атрибута minOccurs в зависимости от того, является поле или свойство массивом или единственным экземпляром; имеет поле или свойство тип значения или ссылочный тип; имеет тип значения значение по умолчанию или дополнительное поле, указывающее, задано ли значение; назначен ли ссылочному типу связанный с XML атрибут со значением true для свойства IsNullable.

Свойство IsNullable используется определенными классами атрибутов, связанными с XML. Это свойство выглядит следующим образом:

• System.Xml.Serialization.XmlElementAttribute.IsNullable

• System.Xml.Serialization.XmlRootAttribute.IsNullable

• System.Xml.Serialization.XmlArrayAttribute.IsNullable

• System.Xml.Serialization.XmlArrayItemAttribute.IsNullable

Если свойство IsNullable члена класса имеет значение true и объект является пустой ссылкой null (Nothing в Visual Basic), класс XmlSerializer создает атрибут xsi:nil со значением true. (Префикс xsi используется для пространства имен экземпляров схем XML, http://www.w3.org/2001/XMLSchema-instance).

Наличие атрибута xsi:nil="true" у элемента в документе экземпляра явно указывает, что у элемента отсутствует содержимое, будь то дочерние элементы или основной текст. См. описание атрибута xsi:nil.

Свойство IsNullable соответствует атрибуту nillable в языке определения схем XSD. Если во время создания определений XSD из классов программа Xsd.exe встречает значение true свойства IsNullable для класса или элемента (и типу можно присвоить ссылку NULL), то создается параметр nillable="true" для соответствующего XSD-элемента <element>. См. описание атрибута nillable.

Правила, приведенные в таблице, указывают значение атрибута minOccurs, соответствующее члену класса, который является единственным экземпляром. Массивы также следуют этим правилам, но с одним исключением, которое описано ниже. Таблица содержит соответствующие варианты членов классов и конечные значения minOccurs.

Входной элемент класса	Значение атрибута minOccurs выходного элемента <element>
Тип значения со значением по умолчанию, заданным с помощью System.Component.DefaultValueAttribute.	0. Для элемента <element> значение по умолчанию также задается при помощи XML-атрибута default.
Тип значения с открытым полем bool, которое использует соглашение об именах Specified, описанные выше в разделе Преобразование XSD в исходный код.	0.
Тип значения без значения по умолчанию и логического поля.	1.
Ссылочный тип, у атрибута XmlElement свойство IsNullable имеет значение true.	1. В элементе <element> атрибут nillable также устанавливается в значение true.
Ссылочный тип, свойство IsNullable=false, либо свойство IsNullable не задано.	0.

Программа Xsd.exe сохраняет данные отличительные черты при обратном преобразовании из документа схемы XML в исходный код.

Примечание. Если атрибут XML default дан одновременно с атрибутом minOccurs, значение которого равно 0, и если тип данных сопоставляется с типом значения, генерируется только атрибут DefaultValue. Сопутствующее логическое поле не создается. Также см. описание атрибута default.

Например, во входном файле встречается такой элемент:

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

Привязки массивов. Программа Xsd.exe всегда создает объявление <element> для массивов следующим образом.

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

Так происходит потому, что типы массивов являются ссылочными типами. Однако, в отличие от других ссылочных типов, это выполняется, даже если к элементу массива применяется следующее объявление атрибута:

[XmlElementAttribute(IsNullable=true)]

Если к массиву применен атрибут XmlElement вместо атрибута по умолчанию XmlArrayAttribute, элементы массива включаются в документ экземпляра в виде дочерних элементов элемента, привязанного к классу. Дополнительный элемент, который должен только служить родительским для элементов массива, не вводится. Тогда как программа Xsd.exe распознает атрибут IsNullable=true и создает элемент с атрибутом nillable="true", значение minOccurs 0 по-прежнему генерируется и элементы массива по прежнему могут отсутствовать.

Если к массиву применен атрибут по умолчанию XmlArray, для представления родительского элемента массива создается тип данных схемы с именем, начинающимся знаками ArrayOf. Дополнительные сведения о привязке массивов см. в разделе об атрибуте maxOccurs и в разделе Управление XML-сериализацией с использованием атрибутов.

Тип данных схемы для родительского элемента соответствует ссылочному типу, и программа Xsd.exe обращается с ним как со ссылочным типом при генерации значения minOccurs. Таким образом, значение minOccurs 1 формируется, если свойство IsNullable имеет значение true:

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

В противном случае создается значение minOccurs 0.

Элемент <any>. Программа Xsd.exe создает значение minOccurs="0" для элемента <any>, независимо от того, задействован один объект или массив, поскольку эквивалентной конструкцией кода является ссылочный тип. Эта конструкция — поле типа System.Xml.XmlElement (или массив полей) с атрибутом System.Xml.Serialization.XmlAnyElementAttribute. Объявление атрибута [XmlElementAttribute(IsNullable=true)] может применяться к объекту XmlElement или массиву, но программа Xsd.exe не интерпретирует такое использование, как элемент <any> с атрибутом minOccurs="1".

Возможные содержащие элементы: <all>, <any>, <choice>, <element>, <group>, <sequence>

См. также

Справочник

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