Share via

Nillable Attribute Binding Support

  • Article

The .NET Framework provides partial binding support for the nillable attribute.

Explanation

When the nillable attribute is set to true in an <element> declaration, it allows an xsi:nil attribute to appear in a conforming element in an XML instance document. (The prefix xsi is commonly used for the XML Schema instance namespace, http://www.w3.org/2001/XMLSchema-instance.)

A value of true for the xsi:nil attribute in an XML element explicitly specifies that the element has no content, whether child elements or body text. The XmlSerializer class equates a true value for the nil attribute with a null reference (Nothing in Visual Basic). See the xsi:nil attribute for how the XmlSerializer class serializes and deserializes the nil attribute, including special cases.

If an element is declared with nillable="false" or no nillable attribute, a nil attribute cannot validly appear in a corresponding instance element, regardless of its value.

Generating the nillable attribute from code

When generating an XML Schema document from a set of classes in an assembly, Xsd.exe create a nillable attribute for a member of a value type if the type is a nullable type. This is because value types can be set to a null reference (Nothing).

For an object of a reference type, Xsd.exe checks the value of certain XML-related attributes' IsNullable property. If the IsNullable property is set to a true value, Xsd.exe creates a nillable attribute and sets its value to true. The IsNullable property is used by certain XML-related attribute classes. The property appears as follows:

An example usage follows:

[System.Xml.Serialization.XmlElementAttribute(IsNullable=true)]
public string NameNullable;

From this code, Xsd.exe generates the following XSD element declaration:

<xs:element minOccurs="1" maxOccurs="1" name="NameNullable" nillable="true" type="xs:string" />

If the IsNullable property is set to true and at run time an applicable object has been set to a null reference (Nothing), the XmlSerializer class generates an xsi:nil attribute with a value of true.

The IsNullable property must be set to true for an attribute applied to a nullable value type.

For reference types, the value of the IsNullable property also determines the value of an <element> element's minOccurs attribute. A true value for IsNullable produces a minOccurs value of 1; otherwise, the value is 0. See the minOccurs attribute.

Xsd.exe also generates a nillable="true" setting in an <element> declaration in certain other circumstances when an IsNullable property is not explicitly set to true.

Generating code from the nillable attribute

When encountering a nillable="true" setting, Xsd.exe generates an IsNullable=true parameter for the appropriate XML-related attribute that is applied to the generated class or member. For value types, nullable types will be generated.

Possible containing elements: <element>

See Also

Reference

XmlSchemaElement.IsNillable
Xsi:nil Attribute Binding Support