ValueConverter Class

Serves as a base for the classes that represent property Value Converters.

Namespace: DevExpress.Xpo.Metadata

Assembly: DevExpress.Xpo.v24.1.dll

NuGet Packages: DevExpress.Win.PivotGrid, DevExpress.Win.TreeMap, DevExpress.Xpo

NuGet Package: DevExpress.Xpo

Declaration

C#

public abstract class ValueConverter

VB.NET

Public MustInherit Class ValueConverter

Related API Members

The following members return ValueConverter objects:

• ValueConverterAttribute.Converter
• XPDictionary.GetConverter(Type)
• XPMemberInfo.Converter

Remarks

Value Converters can be used to persist properties that are non-persistent by default.

To implement a property value converter, create a class inherited from the ValueConverter class and override its abstract members.

• The ValueConverter.StorageType property should return a persistent type used to store the property value in the database.
• The ValueConverter.ConvertToStorageType method should return an argument value converted to the type specified by the StorageType property.
• The ValueConverter.ConvertFromStorageType method should return an argument value converted from the storage type to a type of the property.

The value converter can be associated either with a specific property by applying the ValueConverterAttribute attribute to the property or with a property type by calling the XPDictionary.RegisterValueConverter method of the metadata dictionary.

Note

The value converter mechanism is designed to allow persisting non-persistent data types by transforming them into a persistable equivalent. Value converters are not intended for introducing encryption, compression, or other business logic into the persistence process.

Important

• Properties persisted using Value Converters require the client-side conversion logic, and should not be used in criteria expressions evaluated on the database server side. An attempt to use such properties in criteria may lead to undefined behavior. For instance, when a criterion is translated to a database query, a conversion implemented programmatically may not be applied or may be applied multiple times.

• Value Converters cannot be applied to a property that represents a primary or foreign key. Use the approach described in the How to make user-friendly object identifiers Knowledge Base article if you need to use text values for object identifiers instead of auto-generated numbers.

If it is required to filter or sort by a value of a persistent type transformed from a stored persistent value, do not use value converters. Instead, create an additional calculated property decorated with PersistentAliasAttribute and express a conversion algorithm using the Criteria Language. If the algorithm is complex, implement a Custom Function Operator and use it in the criteria expression.

Example

The following code example demonstrates how to store your boolean data in the database using the “T” string for true and “F” for false by defining a new ValueConverter descendant. You may need this converter when using an existing database in which boolean properties are stored such form.

C#

//...       
[Size(1), ValueConverter(typeof(BooleanToStringValueConverter))]
public bool Answer {
    get { return GetPropertyValue<bool>(nameof(Answer)); }
    set { SetPropertyValue<bool>(nameof(Answer), value); }
}

//...
public class BooleanToStringValueConverter : ValueConverter {
    public override object ConvertFromStorageType(object value) {
        return Convert.ToString(value) == "T";
    }
    public override object ConvertToStorageType(object value) {
        return Convert.ToBoolean(value) ? "T" : "F";
    }
    public override System.Type StorageType {
        get { return typeof(string); }
    }
}

VB.NET

'...       
<Size(1), ValueConverter(GetType(BooleanToStringValueConverter))> _
Public Property Answer() As Boolean
    Get
        Return GetPropertyValue(Of Boolean)(NameOf(Answer))
    End Get
    Set(ByVal value As Boolean)
        SetPropertyValue(Of Boolean)(NameOf(Answer), value)
    End Set
End Property

'...
Public Class BooleanToStringValueConverter
    Inherits ValueConverter
    Public Overrides Function ConvertFromStorageType(ByVal value As Object) As Object
        Return Convert.ToString(value) = "T"
    End Function
    Public Overrides Function ConvertToStorageType(ByVal value As Object) As Object
        Return If(Convert.ToBoolean(value), "T", "F")
    End Function
    Public Overrides ReadOnly Property StorageType() As System.Type
        Get
            Return GetType(String)
        End Get
    End Property
End Class

Inheritance

Object

ValueConverter

ImageValueConverter

UtcDateTimeConverter