Поддержка привязки элемента Attribute

  • Статья

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

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

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

Объяснение

Спецификация схемы XML указывает, что атрибут может быть задан локально, в рамках определения сложного типа, или глобально; во втором случае на него могут ссылаться одно или несколько определений сложных типов при помощи атрибута ref.

Пример локально объявленного атрибута:

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

Пример, где тот же атрибут объявлен глобально и имеется ссылка на него:

<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 не делает различия между локально объявленным атрибутом и ссылкой на глобально объявленный атрибут, если только глобальный атрибут не объявлен в пространстве имен, отличном от целевого пространства имен схемы.

Ссылка в рамках одного пространства имен

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

Ссылка на другое пространство имен

Если глобальное объявление, на которое существует ссылка, принадлежит другому пространству имен, программа Xsd.exe задает пространство имен при помощи свойства Namespace атрибута XmlAttributeAttribute сгенерированного поля. Конкретно для этого элемента пространство имен, заданное в свойстве Namespace, переопределяет пространство имен, заданное на уровне класса при помощи атрибута XmlTypeAttribute и, возможно, XmlRootAttribute. См. пример ниже:

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

public string Key;

Дополнительные пространства имен импортируются в определение схемы XML при помощи элемента <import>.

Example

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

Входной документ схемы XML:

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

Класс C#, созданный на основе приведенного выше документа схемы XML:

[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;
}

Документ схемы XML, созданный из сборки, скомпилированной на основе предыдущего исходного кода C#:

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

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

Второй пример показывает, как программа Xsd.exe обрабатывает ссылку на глобальный атрибут, заданный в другом пространстве имен. В этом примере используется элемент <import> для импорта второго пространства имен из другого XSD-файла. (Атрибут schemaLocation элемента <import> не используется для задания расположения импортируемого XSD-файла. Вместо этого расположение файла задается для программы Xsd.exe дополнительным аргументом командной строки.)

Входной документ схемы XML верхнего уровня:

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

Импортированный входной документ схемы XML:

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

Класс C#, созданный на основе двух приведенных выше документов схем XML:

[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;
}

Документ схемы XML верхнего уровня, созданный из сборки, скомпилированной на основе предыдущего исходного кода C#:

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

Импортированный документ схемы XML, созданный из сборки, скомпилированной на основе приведенного выше исходного кода C#:

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

Атрибут use

Атрибут use объявления <attribute> определяет, обязательно ли должен появиться этот атрибут в XML-документе экземпляра.

Атрибут use. Генерирование исходного кода по документу схемы XML

То, как программа Xsd.exe интерпретирует значение optional атрибута use, зависит от того, задано ли значение по умолчанию при помощи атрибута default. Возможные значения атрибута use, в том числе комбинации значений optional и default, приведены ниже вместе с выходными данными программы Xsd.exe.

  • required: программа Xsd.exe генерирует открытое поле с элементом System.Xml.Serialization.XmlAttributeAttribute.

  • optional, значение default задано: программа Xsd.exe генерирует открытое поле с элементом XmlAttributeAttribute, а также элементом System.Component.DefaultValueAttribute, задающим значение по умолчанию.

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

  • prohibited: программа Xsd.exe ничего не генерирует.

Атрибут use. Генерирование документа схемы XML из классов

В обоих описанных ниже случаях программа Xsd.exe не задает атрибут use, а отсылает к значению по умолчанию optional:

  • Присутствует дополнительное открытое поле типа bool, соответствующее правилам именования Specified.

  • Значение по умолчанию присваивается элементу при помощи атрибута типа System.Component.DefaultValueAttribute.

Если ни одно из условий не выполняется, Xsd.exe генерирует значение required для атрибута use.

Пример: атрибут use

Входной сложный тип схемы XML:

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

Класс C#, сгенерированный из приведенного выше сложного типа:

[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;
}

Сложный тип, созданный из приведенного выше класса C#, фактически эквивалентен исходному сложному типу.

Возможные атрибуты Поддержка привязки

default

Атрибут default предоставляет значение по умолчанию, которое используется, если элемент пуст или атрибут отсутствует при получении документа экземпляра.

При генерировании исходного кода из схемы XML программа Xsd.exe к каждому полю, соответствующему атрибуту со значением по умолчанию, применяет System.ComponentModel.DefaultValueAttribute, передавая значение по умолчанию как аргумент. Кроме того, программа Xsd.exe статически инициализирует поле со значением по умолчанию, как в следующем примере:

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

Помимо этого, при генерировании исходного кода из схемы Xsd.exe проверяет, задан ли атрибут default, чтобы определить, как интерпретировать атрибут use со значением optional. Полное описание см. в разделе об атрибуте default.

Программа Xsd.exe не может сгенерировать допустимый код для атрибутов типа список со значениями по умолчанию. Этот случай описан с атрибутом default. См. также описание элемента <list>.

fixed

Для объявлений <attribute> программа Xsd.exe использует значение атрибута fixed для статической инициализации поля фиксированным значением, как в следующем примере:

[System.Xml.Serialization.XmlAttribute()]
public in age = -1;

См. описание атрибута fixed.

form

Программа Xsd.exe считает XML-атрибут form элемента <attribute> равным свойству Form XmlAttributeAttribute. Инфраструктура XML-сериализации платформы .NET Framework распознает значение по умолчанию unqualified схемы XML.

Если объявление <attribute> в схеме XML задает значение form="qualified", программа Xsd.exe создает атрибут XmlAttribute для соответствующего поля и передает атрибуту параметр Form=XmlSchemaForm.Qualified.

См. описание атрибута form.

id

Программа Xsd.exe игнорирует атрибут id, который предназначен для обеспечения уникального идентификатора. Вместо него она использует атрибут name.

name

В процессе генерирования кода из документа XSD значение атрибута name используется как имя открытого поля класса, представляющего атрибут. Если имя совпадает с зарезервированным ключевым словом, в начало имени добавляется символ @.

Когда программа Xsd.exe создает объявление элемента <attribute> из открытого поля класса, она использует имя этого поля в качестве значения атрибута name. Альтернативное имя (значение атрибута name) можно указать с помощью свойства AttributeName.

См. описание атрибута Поддержка привязки атрибута Name.

ref

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

См. разделы "Ссылка в рамках одного пространства имен" и "Ссылка на другое пространство имен".

type

Программа Xsd.exe связывает типы данных, на которые ссылается атрибут type объявлений <attribute> и <element>, с типами платформы .NET Framework.

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

use

Если значение use=“optional”, Xsd.exe проверяет наличие атрибута default, чтобы определить, генерировать ли DefaultValueAttribute, или дополнительное поле –Specified. Дополнительное поле не создается для ссылочных типов (например, строк). Если у открытого поля нет ни дополнительного поля, ни значения по умолчанию, программа Xsd.exe задает значение use=“required” в генерируемом документе XSD.

См. предшествующий раздел «Атрибут use».

Возможные родительские элементы: <attributeGroup>, <complexType>, <extension>, <restriction>, <schema>

Возможные дочерние элементы: <annotation>, <simpleType>

См. также

Справочник

XmlSchemaAttribute