Table of Contents

Create a value converter

What is a value converter ?

When dealing with data modeling, you may store data in a different format than the one you use in your application. Value converters allow property values to be converted when reading from or writing to the database. This conversion can be from one value to another of the same type (for example, encrypting strings) or from a value of one type to a value of another type (for example, converting enum values to and from strings in the database.)

How to implement a value converter

The example below represents a converter from boolean values to character strings:

    /// <summary>
    /// Represents an boolean to string converter.
    /// </summary>
    public class BooleanToStringConverter : ValueConverter<bool?, string?>
    {
        /// <summary>
        /// Represents the boolean value <c>true</c> as a string.
        /// </summary>
        public const string TrueString = "Yes";

        /// <summary>
        /// Represents the boolean value <c>false</c> as a string.
        /// </summary>
        public const string FalseString = "No";

        /// <summary>
        /// Initializes a new instance of the <see cref="BooleanToStringConverter"/> class.
        /// </summary>
        public BooleanToStringConverter()
            : base(v => ConvertFromBooleanToProvider(v, TrueString, FalseString), v => ConvertFromProviderToBoolean(v, TrueString, FalseString))
        {
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="BooleanToStringConverter"/> class.
        /// </summary>
        /// <param name="trueString">Boolean value <c>true</c> as a string.</param>
        /// <param name="falseString">Boolean value <c>false</c> as a string.</param>
        public BooleanToStringConverter(string trueString, string falseString)
            : base(v => ConvertFromBooleanToProvider(v, trueString, falseString), v => ConvertFromProviderToBoolean(v, trueString, falseString))
        {
        }

        private static string? ConvertFromBooleanToProvider(bool? value, string trueString, string falseString)
        {
            if (value.HasValue)
            {
                return value.Value ? trueString : falseString;
            }

            return null;
        }

        private static bool? ConvertFromProviderToBoolean(string? value, string trueString, string falseString)
        {
            if (string.Equals(value, trueString, StringComparison.OrdinalIgnoreCase))
            {
                return true;
            }

            if (string.Equals(value, falseString, StringComparison.OrdinalIgnoreCase))
            {
                return false;
            }

            return null;
        }
    }

First of all the class representing the value converter must inherit from the ValueConverter class provided by the Entity Framework Core library. This is a generic class so you must also specify the entity property data type and the data column data type.

Then you need to provide a function that converts the value to the type expected by the data provider and another method that converts back the data from the provider to the type of the model object property.

Warning

The value converter MUST HAVE a default constructor without parameters.

Note

A null value will never be passed to a value converter. A null in a database column is always a null in the entity instance, and vice versa.

How to register a value converter

You must inform Neos about the availability of these value converters. To do this, they must be saved in the configuration file:

Csprojs:
  Persistence:
    - ./projects/Persistence/GroupeIsa.Northwind.Converters/GroupeIsa.Northwind.Converters/GroupeIsa.Northwind.Converters.csproj
PersistenceConverters:
  - Name: BooleanToStringConverter
    Type: GroupeIsa.Northwind.Converters.BooleanToStringConverter
    EntityPropertyDataType: Boolean
    DataColumnDataType: String
  - Name: BooleanToIntegerConverter
    Type: GroupeIsa.Northwind.Converters.BooleanToIntegerConverter
    EntityPropertyDataType: Boolean
    DataColumnDataType: Integer

The Csprojs/Persistence section allows you to list the references to the assemblies which contain the implementation of the value converters

The PersistenceConverters section allows you to define the different converters. Each converter definition must contain the following information:

  • Name: The display name of the value converter
  • Type: The full name of the class representing the value converter
  • EntityPropertyDataType: The data type of the EntityProperty
  • DataColumnDataType: The data type of the DataColumn

How to configure an entity property to use a value converter

You can assign a value converter to an EntityProperty by selecting it from the list available in the database group box:

Then you must change the type of the DataColumn to match the provider data type of the converter:

Note
  • A complete example of using value converters is available in the Northwind application at the Converters module level.