Edit

Data Member Default Values

  • Article

In the .NET Framework, types have a concept of default values. For example, for any reference type the default value is null, and for an integer type it is zero. It is occasionally desirable to omit a data member from serialized data when it is set to its default value. Because the member has a default value, an actual value need not be serialized; this has a performance advantage.

To omit a member from serialized data, set the EmitDefaultValue property of the DataMemberAttribute attribute to false (the default is true).

Note

You should set the EmitDefaultValue property to false if there is a specific need to do so, such as for interoperability or data size reduction.

Example

The following code has several members with the EmitDefaultValue set to false.

[DataContract]
public class Employee
{
    [DataMember]
    public string employeeName = null;
    [DataMember]
    public int employeeID = 0;
    [DataMember(EmitDefaultValue = false)]
    public string position = null;
    [DataMember(EmitDefaultValue = false)]
    public int salary = 0;
    [DataMember(EmitDefaultValue = false)]
    public int? bonus = null;
    [DataMember(EmitDefaultValue = false)]
    public int targetSalary = 57800;
}

<DataContract()> _
Public Class Employee
    <DataMember()> _
    Public employeeName As String = Nothing
    <DataMember()> _
    Public employeeID As Integer = 0
    <DataMember(EmitDefaultValue:=False)> _
    Public position As String = Nothing
    <DataMember(EmitDefaultValue:=False)> _
    Public salary As Integer = 0
    <DataMember(EmitDefaultValue:=False)> _
    Public Bonus As Integer = Bonus OrElse Nothing
    <DataMember(EmitDefaultValue:=False)> _
    Public targetSalary As Integer = 57800
End Class

If an instance of this class is serialized, the result is as follows: employeeName and employeeID is serialized. The null value for employeeName and the zero value for employeeID is explicitly part of the serialized data. However, the position, salary, and bonus members are not serialized. Finally, targetSalary is serialized as usual, even though the EmitDefaultValue property is set to false, because 57800 does not match the .NET default value for an integer, which is zero.

XML Representation

If the previous example is serialized to XML, the representation is similar to the following.

<Employee>  
   <employeeName xsi:nil="true" />  
   <employeeID>0</employeeID>  
<targetSalary>57800</targetSalary>  
</Employee>

The xsi:nil attribute is a special attribute in the World Wide Web Consortium (W3C) XML Schema instance namespace that provides an interoperable way to explicitly represent a null value. Note that there is no information at all in the XML about position, salary, and bonus data members. The receiving end can interpret these as null, zero, and null, respectively. There is no guarantee that a third-party deserializer can make the correct interpretation, which is why this pattern is not recommended. The DataContractSerializer class always selects the correct interpretation for missing values.

Interaction with IsRequired

As discussed in Data Contract Versioning, the DataMemberAttribute attribute has an IsRequired property (the default is false). The property indicates whether a given data member must be present in the serialized data when it is being deserialized. If IsRequired is set to true, (which indicates that a value must be present) and EmitDefaultValue is set to false (indicating that the value must not be present if it is set to its default value), default values for this data member cannot be serialized because the results would be contradictory. If such a data member is set to its default value (usually null or zero) and a serialization is attempted, a SerializationException is thrown.

Schema Representation

The details of the XML Schema definition language (XSD) schema representation of data members when the EmitDefaultValue property is set to false are discussed in Data Contract Schema Reference. However, the following is a brief overview:

  • When the EmitDefaultValue is set to false, it is represented in the schema as an annotation specific to Windows Communication Foundation (WCF). There is no interoperable way to represent this information. In particular, the "default" attribute in the schema is not used for this purpose, the minOccurs attribute is affected only by the IsRequired setting, and the nillable attribute is affected only by the type of the data member.

  • The actual default value to use is not present in the schema. It is up to the receiving endpoint to appropriately interpret a missing element.

On schema import, the EmitDefaultValue property is automatically set to false whenever the WCF-specific annotation mentioned previously is detected. It is also set to false for reference types that have the nillable property set to false to support specific interoperability scenarios that commonly occur when consuming ASP.NET Web services.

See also