Serialization Options
The PersistenceManager class allows you to specify which properties of the UIElements to be persisted.
In order to take advantage of this feature you need to set the PersistenceManager.SerializationOptions attached property on the corresponding UIElement. The property expects a collection of type SerializationMetadataCollection which can host the following two types of elements.
PropertyNameMetadata: Determines the UIElement properties to be persisted by PersistenceManager.
PropertyTypeMetadata: Determines properties of what type to be persisted by PersistenceManager.
Serialization by Property Name
The PropertyNameMetadata class allows you to provide a name or a path to a property and based on a condition to decide whether the property should get serialized or not.
The PropertyNameMetadata class provides the following properties:
-
Condition: Defines the condition under which the property will get persisted. It is a SerializationMetadataCondition enumeration and exposes the following members:
- Only: States that only this property will be persisted. This is the default condition.
- Except: States that this property won't be persisted.
-
Expression: Defines a regular expression as a base for a Regex that is applied over the property names of the object that is being serialized. The Expression property also takes into account the value of the SearchType property.
Example 1: Using Expression to serialize only the Width property of a RadButton
<telerik:RadButton> <telerik:PersistenceManager.SerializationOptions> <telerik:SerializationMetadataCollection> <telerik:PropertyNameMetadata Condition="Only" Expression="^\b(Width)\b$" SearchType="PropertyName" /> </telerik:SerializationMetadataCollection> </telerik:PersistenceManager.SerializationOptions> </telerik:RadButton>Example 2: Using Expression to serialize all properties (of RadButton) containing Width in their name - like Width, MinWidth and MaxWidth
<telerik:RadButton> <telerik:PersistenceManager.SerializationOptions> <telerik:SerializationMetadataCollection> <telerik:PropertyNameMetadata Condition="Only" Expression="Width" SearchType="PropertyName" /> </telerik:SerializationMetadataCollection> </telerik:PersistenceManager.SerializationOptions> </telerik:RadButton> IsRecursive: Determines whether the Expression will be evaluated in depth.
-
SearchType: Determines whether the searched Expression is based on a property name or a property path. It is a MetadataSearchCriteria enumeration that allows you to choose between the following values:
- PropertyName: The Expression value will be evaluated against a property name in the UIElement.
- PropertyPath: The Expression value will be evaluated against the full path of the property (the path from the serialization root to the property) .
Example 3: Setting up PropertyNameMetadata
<telerik:RadButton>
<telerik:PersistenceManager.SerializationOptions>
<telerik:SerializationMetadataCollection>
<!-- Searching (and serializing) all properties of RadButton, except Background -->
<telerik:PropertyNameMetadata Condition="Except" Expression="^\b(Background)\b$" SearchType="PropertyName" />
</telerik:SerializationMetadataCollection>
</telerik:PersistenceManager.SerializationOptions>
</telerik:RadButton>
Serialization by Property Type
The PropertyTypeMetadata class allows you to provide a property type or a type name, and based on a condition to decide whether the property should get serialized or not.
The PropertyTypeMetadata class exposes the following properties:
AllowSubClasses: Determines whether properties of types that are sub-classes of the specified type should be persisted.
-
Condition: Define the condition under which the specified type of properties will be persisted. It is a SerializationMetadataCondition enumeration and exposes the following members:
- Only: States that only this type of properties will be persisted. This is the default condition.
-
Except: States that no property of the specified type will be persisted.
IsRecursive: Determines whether an in-depth search for properties of the specified type should be executed.
Type: Defines the type of properties that should be persisted. You can use this property as an alternative to the TypeString property.
-
TypeString: Defines the type of the properties that should be persisted. You can use this property as an alternative to the Type property.
The Type property has a higher priority than TypeString.
Example 4: Setting up PropertyTypeMetadata using the Type property
<telerik:RadButton>
<telerik:PersistenceManager.SerializationOptions>
<telerik:SerializationMetadataCollection>
<!-- Searching (and serializing) only properties of type Thickness -->
<telerik:PropertyTypeMetadata Condition="Only" Type="{x:Type Thickness}"/>
</telerik:SerializationMetadataCollection>
</telerik:PersistenceManager.SerializationOptions>
</telerik:RadButton>
Example 5: Setting up PropertyTypeMetadata using the TypeString property
<telerik:RadButton>
<telerik:PersistenceManager.SerializationOptions>
<telerik:SerializationMetadataCollection>
<!-- Searching (and serializing) only properties of type Thickness -->
<telerik:PropertyTypeMetadata Condition="Only" TypeString="System.Windows.Thickness"/>
</telerik:SerializationMetadataCollection>
</telerik:PersistenceManager.SerializationOptions>
</telerik:RadButton>
Multiple Options
The SerializationMetadataCollection class allows you to define what operator to be used when evaluating multiple metadata elements (PropertyNameMetadata and PropertyTypeMetadata). To do this, set the Operator property. It is of type LogicalOperator (enum) and allows the following values:
And: A property should fulfill all conditions defined by the items in the SerializationMetadataCollection in order to be persisted.
Or: A property can fulfill only a single of the conditions defined by the items in the SerializationMetadataCollection in order to be persisted. This is the default operator.
Example 6: Using multiple options with And operator
<telerik:RadButton>
<telerik:PersistenceManager.SerializationOptions>
<telerik:SerializationMetadataCollection Operator="And">
<!-- Searching (and serializing) only properties of type Double that don't contain the string "Width" in their names -->
<telerik:PropertyTypeMetadata Condition="Only" TypeString="System.Double"/>
<telerik:PropertyNameMetadata Condition="Except" Expression="Width" SearchType="PropertyName" />
</telerik:SerializationMetadataCollection>
</telerik:PersistenceManager.SerializationOptions>
</telerik:RadButton>
ShouldSerialize Method
SerializationMetadataCollection and its children (PropertyNameMetadata and PropertyTypeMetadata objects) expose the ShouldSerialize method. The method allows you to check if a property should be serialized based on the applied metadata.
Example 7: Checking if properties containing Width in their names will be serialized based on the settings applied to the PropertyNameMetadata object
PropertyNameMetadata propertyNameMetadata = PersistenceManager.GetSerializationOptions(this.radButton)[0];
var widthPropertyInfo = typeof(RadButton).GetProperty("Width");
MatchResult result = propertyNameMetadata.ShouldSerialize(widthPropertyInfo, "Width");
The MatchResult is an enum that can have the following values:
- Full: All conditions in the SerializationMetadataCollection are met.
- None: None of the conditions in the SerializationMetadataCollection are met.
- Partial: Only some of the conditions of the SerializationMetadataCollection are met.