Order Best Practices
Why is setting the Order property on data members recommended when adding fields in a new version of the contract?
The data contract versioning best practices recommend taking three steps when adding fields in a new version of a contract.
The first recommendation is to set the IsRequired property on the new field to false. Since older applications will not know about the new field, you obviously can’t require that the field always be present.
The second recommendation is to provide an OnDeserializing callback if the default value of the new field needs to be set. The default value of the field- zero, false, null, or the other similar defaults for data types- may not be a valid or desired value for the field. If the field is not required, then you will potentially see the field initialized with the default value. Creating a callback to set the default value appropriately takes care of compatibility problems.
The third is to set the Order property on the new field so that the field appears after all of the existing data members. If you are exchanging messages with an application that models the data using member name and namespace, then the order of the members tends not to matter. At most, there might be efficiency issues if the application has optimized for a specific member order but you’ve forced it to do extra work by providing the members in a different order.
On the other hand, if you are exchanging messages with an application that models the data using the structure of the contract, then the order of the members may be a more fundamental assumption. There are many applications deployed and in use that are intolerant of changing the order of members. In this case, changing the order of members or inserting new members in between doesn’t just affect the efficiency of the application but could entirely break validation or application logic. Always adding new fields to the end even when not strictly required is a conservative measure to promote compatibility and avoid having to deal with application bugs.