Enumeration Element Binding Support

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

Only when the <enumeration> facet is applied to string-based types like xsd:string does the Xsd.exe translate it into a .NET Framework enum definition.

Explanation

The <enumeration> element is used to create a finite set of choices from a simple data type. It is used to derive a new simple type from an existing simple type by restricting the base type. The base type may have been created as an enumeration.

The XML Schema specification allows the <enumeration> facet to be applied to any simple type except xsd:boolean. However, when generating source code from an XML Schema document, Xsd.exe recognizes only enumerations based on string-based simple data types, such as xsd:string, as enumerations. In that case, the translation produces an enum definition.

The following built-in types from the XML Schema definition language are translated into enum type definitions:

• string

• normalizedString

• token

• Name

• NCName

• ID

• ENTITY

• NMTOKEN

When generating an XML Schema document from a set of classes, Xsd.exe translates an enum definition into an enumeration based on xsd:string.

What the Xsd.exe tool does with other, non-string-based simple types depends on both the context and the type. For an enumeration based on a built-in numeric data type, the translation produces a field of a type corresponding to the base type (such as System.Decimal for xsd:decimal), as long as the enumeration appears as an element or attribute within a complex type. Otherwise, the enumeration is simply ignored when it merely populates its own globally defined element.

The value attribute in string-based enumerations

An enumeration value needs to either qualify as a valid constant name or be converted by Xsd.exe into a constant name. An example is the following enumeration value:

<xsd:enumeration value="IRISH CREAM" />

This value is converted into the following enum member:

[System.Xml.Serialization.XmlEnumAttribute("IRISH CREAM")]
IRISHCREAM,

The single space is removed to produce a valid constant name, and an XmlEnumAttribute attribute is applied to the enum member. The attribute parameter changes the XML Schema enumeration value that is used for that enum value. The default is the enum value itself, in this case IRISHCREAM. For an XML Schema enumeration value that already qualifies as a valid constant name, the XmlEnum attribute is omitted.

While the .NET Framework does not translate a numeric XSD enumeration into an enum definition, it does translate a string XSD enumeration whose values happen to be numbers. The following simple type definition binds to an enum type because it specifies base="xsd:string":

<xsd:simpleType name="Primes">
    <xsd:restriction base="xsd:string">
        <xsd:enumeration value="2" />
        <xsd:enumeration value="3" />
        <xsd:enumeration value="5" />
        <xsd:enumeration value="7" />
        <xsd:enumeration value="11" />
        <xsd:enumeration value="13" />
        <xsd:enumeration value="17" />
    </xsd:restriction>
</xsd:simpleType>

The following enum type is produced:

public enum Primes { 
    [System.Xml.Serialization.XmlEnumAttribute("2")]
    Item2,
    [System.Xml.Serialization.XmlEnumAttribute("3")]
    Item3,
    [System.Xml.Serialization.XmlEnumAttribute("5")]
    Item5,
    [System.Xml.Serialization.XmlEnumAttribute("7")]
    Item7,
    [System.Xml.Serialization.XmlEnumAttribute("11")]
    Item11,
    [System.Xml.Serialization.XmlEnumAttribute("13")]
    Item13,
    [System.Xml.Serialization.XmlEnumAttribute("17")]
    Item17,
}

Again, the XmlEnum attribute is used to override the default binding of the xsd:enumeration value to an XML Schema enumeration value.

Example

Input XML Schema document that defines xsd:string and xsd:int enumerations:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            targetNamespace="http://example.org/" xmlns="http://example.org/" elementFormDefault="qualified">
    <xsd:element name="coffeeDrink" type="FancyCoffeeType" />

    <xsd:complexType name="FancyCoffeeType">
        <xsd:attribute ref="selection" use="required" />
        <xsd:attribute ref="shots" use="required" />
    </xsd:complexType>
    
    <xsd:attribute name="selection" type="Flavors"/>
    <xsd:attribute name="shots" type="Primes"/>

    <xsd:simpleType name="Flavors">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="VANILLA" />
            <xsd:enumeration value="HAZELNUT" />
            <xsd:enumeration value="CARAMEL" />
            <xsd:enumeration value="RASPBERRY" />
            <xsd:enumeration value="ALMOND" />
            <xsd:enumeration value="CHERRY" />
            <xsd:enumeration value="IRISH CREAM" />
        </xsd:restriction>
    </xsd:simpleType>

    <xsd:simpleType name="Primes">
        <xsd:restriction base="xsd:int">
            <xsd:enumeration value="2" />
            <xsd:enumeration value="3" />
            <xsd:enumeration value="5" />
            <xsd:enumeration value="7" />
            <xsd:enumeration value="11" />
            <xsd:enumeration value="13" />
            <xsd:enumeration value="17" />
        </xsd:restriction>
    </xsd:simpleType>
</xsd:schema>

C# classes generated from the preceding XML Schema document. The integer enumeration has been replaced by a field of type int:

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("coffeeDrink", Namespace="http://example.org/", IsNullable=false)]
public class FancyCoffeeType {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public Flavors selection;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public int shots;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
public enum Flavors {
    VANILLA,        
    HAZELNUT,
    CARAMEL,        
    RASPBERRY,
    ALMOND,
    CHERRY,
    System.Xml.Serialization.XmlEnumAttribute("IRISH CREAM")]
    IRISHCREAM,
}

XML Schema complex type and simple type generated from an assembly compiled from the preceding C# source:

  <xs:complexType name="FancyCoffeeType">
    <xs:attribute name="selection" type="tns:Flavors" />
    <xs:attribute name="shots" type="xs:int" />
  </xs:complexType>
  <xs:simpleType name="Flavors">
    <xs:restriction base="xs:string">
      <xs:enumeration value="VANILLA" />
      <xs:enumeration value="HAZELNUT" />
      <xs:enumeration value="CARAMEL" />
      <xs:enumeration value="RASPBERRY" />
      <xs:enumeration value="ALMOND" />
      <xs:enumeration value="CHERRY" />
      <xs:enumeration value="IRISH CREAM" />
    </xs:restriction>
  </xs:simpleType>

Possible parent elements: <restriction>

Possible child elements: <annotation>

See Also

Reference

XmlSchemaEnumerationFacet