Share via

Nillable Attribute Binding Support

  • Article

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

Xsi:nil Attribute Binding Support
System.Xml.Schema.XmlSchemaElement.IsNillable