[Breaking change]: Default property value converters will be added for all value types in Umbraco 13

[kjac]

Description

It is possible to create property editors without backing property value converters. Usually this is done using manifests. These property editors still declare a value type, which should be one of the predefined ones in ValueTypes.

However, the resulting property value output for these property editor types are not always typed according to their declared value types.

Moving forward we will introduce default property value converters to handle the conversion of all value types (except JSON, as it's already handled). Thus, property editors without backing property value converters will still have their property value outputs translated into types corresponding to their declared value types.

Besides having correctly typed property value outputs, this also ensures that the properties in ModelsBuilder generated models are typed correctly.

This change only affects custom property editors with no property value converters. Existing and/or custom property value converters will take precedence over these new default property value converters.

Version

Umbraco 13

Previous behavior

The following applies only to custom property editors with no backing property value converters.

• Property editors of value type DECIMAL output string values.
• Property editors of value type TIME output DateTime values.
• Property editors of value type BIGINT output string values.
• Property editors of value type XML output string values.

Properties of any other value type than JSON are represented as type object in ModelsBuilder generated classes. JSON value type properties are represented as JToken.

New behavior

The following applies only to custom property editors with no backing property value converters.

• Property editors of value type DECIMAL output decimal values (instead of string values).
• Property editors of value type TIME output TimeSpan values (instead of DateTime values).
• Property editors of value type BIGINT output long values (instead of string values).
• Property editors of value type XML output XDocument values (instead of string values).

Properties of any type are represented by their corresponding type in ModelsBuilder generated classes:

• A property of value type DATE or DATETIME becomes a DateTime property.
• A property of value type DECIMAL becomes a decimal property.
• A property of value type INT becomes an integer property.
• A property of value type BIGINT becomes a long property.
• A property of value type JSON becomes a JToken property.
• A property of value type STRING or TEXT becomes a string property.
• A property of value type TIME becomes a TimeSpan property.
• A property of value type XML becomes an XDocument property.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

To ensure type safety for all value types, not only for JSON-

Recommended action

If you have no custom property editors, or all custom property editors have backing property value converters, no action is necessary.

Regenerate ModelsBuilder models and recompile against the newly generated models.

Revisit any explicit parsing or casting when consuming property editor data from "property-value-converter-less" properties. Likely the assumptions will be wrong, as the property output values are now typed correctly.

Affected APIs

IPublishedContent and IPublishedElement