Attribute Element Binding Support

Article
02/13/2011

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

The .NET Framework provides binding support for the <attribute> element.

However, Xsd.exe does not differentiate between a locally declared attribute and a reference to a globally declared attribute, unless the global attribute is declared in a namespace other than the schema's target namespace.

Explanation

The XML Schema specification states that an attribute can be declared locally, within a complex type definition, or globally, in which case it can be referenced by one or more complex type definitions via the ref attribute.

Following is an example of an attribute declared locally:

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

Following is an example of the same attribute declared globally and then referenced:

<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 does not differentiate between a locally declared attribute and a reference to a globally declared attribute, unless the global attribute is declared in a namespace other than the schema's target namespace.

Reference within the same namespace

Because Xsd.exe does not differentiate within the same namespace, a round-trip translation from XML schema to classes and back creates a local attribute in the place of what had been a global attribute and a reference.

Reference to another namespace

If a referenced global declaration belongs to a different namespace, then Xsd.exe specifies the namespace using the Namespace property of an XmlAttributeAttribute attribute that is applied to the generated field. For that particular element, the namespace specified via the Namespace property overrides the namespace specified at the class level using the XmlTypeAttribute attribute and, optionally, the XmlRootAttribute. An example follows:

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

public string Key;

Additional namespaces are imported into an XML Schema definition using the <import> element.

Example

This first example shows how Xsd.exe processes a global attribute when that attribute is defined in the same target namespace that contains a reference to it.

Input XML Schema document:

<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# class generated from the preceding XML Schema document:

[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 Schema document generated from an assembly compiled from the preceding C# source:

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

In the preceding generated XML schema, the version attribute, originally declared globally, has been made a local attribute.

This second example shows how Xsd.exe processes a reference to a global attribute when that attribute is defined in a separate namespace. This example uses the <import> element to import a second namespace located in a separate XSD file. (The <import> element's schemaLocation attribute is not used to specify the location of the imported .xsd file. Instead, for Xsd.exe, the file is specified as an additional command-line argument.)

The top-level XML Schema document used as an input:

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

The imported XML Schema document used as an input:

<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# class generated from the preceding two XML Schema documents:

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

Top-level XML Schema document generated from an assembly compiled from the preceding C# source:

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

Imported XML Schema document generated from an assembly compiled from the preceding C# source:

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

The use attribute of an <attribute> declaration determines whether the attribute may or must appear in an XML instance document.

Use Attribute: Generating source code from an XML Schema document

Xsd.exe's interpretation of a value of optional for the use attribute depends on whether a default attribute value has been specified via the default attribute. The possible values for use, including the optional and default combinations, are listed with their Xsd.exe outputs as follows:

required: Xsd.exe generates a public field with a System.Xml.Serialization.XmlAttributeAttribute.
optional with default specified: Xsd.exe generates a public field with an XmlAttributeAttribute plus a System.Component.DefaultValueAttribute specifying the default value.
optional with no default specified: Xsd.exe generates a public field with an XmlAttributeAttribute. In addition, if the type of the attribute is not a reference type (for example, a string), it generates a public field of type bool whose name is the attribute field's name with Specified appended. For example, if the attribute field's name is startDate, the bool field's name becomes startDateSpecified. When serializing an object to XML, the XmlSerializer class checks the value of the bool field to determine whether to write the optional attribute. The bool field appears with a System.Xml.Serialization.XmlIgnoreAttribute to prevent it from being serialized by XmlSerializer.
prohibited: Xsd.exe doesn't generate anything.

Use Attribute: Generating an XML Schema document from classes

In either of the following two cases, Xsd.exe does not specify the use attribute, reverting to the default value optional:

An extra public bool field that follows the Specified naming convention is present.
A default value is assigned to the member via an attribute of type System.Component.DefaultValueAttribute.

If neither of these conditions is met, Xsd.exe produces a value of required for the use attribute.

Example: Use Attribute

Input XML Schema complex type:

<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# class generated from the preceding complex type:

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

The complex type generated from the preceding C# class is effectively equivalent to the original complex type.

Possible Attributes	Binding Support
default	The default attribute provides a default value to be used if the element is empty or the attribute is not present when an instance document is received. When generating source code from an XML schema, the Xsd.exe tool takes each field corresponding to an attribute with a default value and applies a System.ComponentModel.DefaultValueAttribute, passing the default value as an argument. In addition, Xsd.exe statically initializes the field to the default value, as in the following example: `[System.ComponentModel.DefaultValueAttribute(-1)] [System.Xml.Serialization.XmlAttributeAttribute()] public int age = -1;` In addition, when generating source code from a schema, Xsd.exe checks whether the default attribute has been specified to determine how to interpret a use attribute with a value of `optional`. See the default attribute for a full explanation. The Xsd.exe tool fails to generate valid source code for attributes of list types with default values. This case is described with the default attribute. Also see the <list> element.
fixed	For <attribute> declarations, Xsd.exe uses the value of the fixed attribute to statically initialize the field to the fixed value, as in the following example: `[System.Xml.Serialization.XmlAttribute()] public in age = -1;` See the fixed attribute.
form	The Xsd.exe tool equates the form XML attribute of the <attribute> element with the Form property of the XmlAttributeAttribute. The .NET Framework's XML serialization infrastructure recognizes the XML Schema's default value, `unqualified`. If an <attribute> declaration in an XML schema specifies `form="qualified"`, Xsd.exe generates an XmlAttribute attribute for the corresponding field and passes the attribute a parameter, `Form=XmlSchemaForm.Qualified`. See the form attribute.
id	The Xsd.exe utility ignores the id attribute, which is intended to provide a unique identifier. Instead, Xsd.exe recognizes the name attribute.
name	For generating source code from an XSD document, the value of the name attribute provides the name of the public class field that represents that attribute. If a name conflicts with a reserved keyword, the resulting name is prepended with the symbol @. When Xsd.exe generates an <attribute> declaration from a public class field, it uses the field name for the value of the name attribute. An alternate name—name attribute value—can be supplied via the AttributeName property. See the Name Attribute Binding Support attribute.
ref	When generating a .NET Framework type from an XML Schema complex type, Xsd.exe does not differentiate between a locally declared attribute and a reference to a globally declared attribute, unless the global attribute is declared in a namespace other than the schema's target namespace. See the sections Reference within the same namespace and Reference to another namespace.
type	The Xsd.exe tool associates the data types referenced with the type attribute of <attribute> and <element> declarations with .NET Framework types. Xsd.exe does not generate a .NET Framework type for an XML schema data type unless the data type can be traced back to a global element declaration that refers to a data type via the type attribute.
use	If `use=“optional”`, Xsd.exe checks for the presence of the default attribute to determine whether to generate a DefaultValueAttribute or an extra –Specified field. The extra field is not generated for reference types (for example, strings). The presence of neither for a public field causes Xsd.exe to specify `use=“required”` in a generated XSD document. See the preceding section, Use Attribute.

Possible parent elements: <attributeGroup>, <complexType>, <extension>, <restriction>, <schema>

Possible child elements: <annotation>, <simpleType>