Conversions de valeursValue Conversions

Note

Cette fonctionnalité est une nouveauté dans EF Core 2.1.This feature is new in EF Core 2.1.

Convertisseurs de valeur autorisent les valeurs de propriété à convertir lors de la lecture ou de l’écriture dans la base de données.Value converters allow property values to be converted when reading from or writing to the database. Cette conversion peut être d’une valeur à un autre du même type (par exemple, les chaînes de chiffrement) ou à partir d’une valeur d’un type avec une valeur d’un autre type (par exemple, lors de la conversion valeurs enum vers et à partir de chaînes dans la base de données.)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.)

Notions de baseFundamentals

Convertisseurs de valeurs sont spécifiées en termes d’un ModelClrType et un ProviderClrType.Value converters are specified in terms of a ModelClrType and a ProviderClrType. Le type de modèle est le type .NET de la propriété dans le type d’entité.The model type is the .NET type of the property in the entity type. Le type de fournisseur est le type .NET interprété par le fournisseur de base de données.The provider type is the .NET type understood by the database provider. Par exemple, pour enregistrer les enums sous forme de chaînes dans la base de données, le type de modèle est le type de l’énumération, et le type de fournisseur est String.For example, to save enums as strings in the database, the model type is the type of the enum, and the provider type is String. Ces deux types peuvent être identiques.These two types can be the same.

Conversions sont définies à l’aide de deux Func arborescences d’expression : un dans ModelClrType à ProviderClrType et l’autre de ProviderClrType à ModelClrType.Conversions are defined using two Func expression trees: one from ModelClrType to ProviderClrType and the other from ProviderClrType to ModelClrType. Arborescences d’expression sont utilisées afin qu’ils peuvent être compilés dans le code d’accès de base de données pour les conversions efficace.Expression trees are used so that they can be compiled into the database access code for efficient conversions. Pour les conversions complexes, l’arborescence d’expression peut être un simple appel à une méthode qui effectue la conversion.For complex conversions, the expression tree may be a simple call to a method that performs the conversion.

Configuration d’un convertisseur de valeursConfiguring a value converter

Conversions de valeurs sont définies sur les propriétés de la OnModelCreating de votre DbContext.Value conversions are defined on properties in the OnModelCreating of your DbContext. Par exemple, considérez un type enum et l’entité défini en tant que :For example, consider an enum and entity type defined as:

public class Rider
{
    public int Id { get; set; }
    public EquineBeast Mount { get; set; }
}

public enum EquineBeast
{
    Donkey,
    Mule,
    Horse,
    Unicorn
}

Puis les conversions peuvent être définies dans OnModelCreating pour stocker les valeurs enum sous forme de chaînes (par exemple) « Âne », « Chevaux »,...) dans la base de données :Then conversions can be defined in OnModelCreating to store the enum values as strings (e.g. "Donkey", "Mule", ...) in the database:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder
        .Entity<Rider>()
        .Property(e => e.Mount)
        .HasConversion(
            v => v.ToString(),
            v => (EquineBeast)Enum.Parse(typeof(EquineBeast), v));
}

Note

A null valeur ne sera jamais passée à un convertisseur de valeurs.A null value will never be passed to a value converter. Cela facilite l’implémentation de conversions et leur permet d’être partagées entre les propriétés acceptant les valeurs NULL et non nullable.This makes the implementation of conversions easier and allows them to be shared amongst nullable and non-nullable properties.

La classe ValueConverterThe ValueConverter class

Appel de HasConversion comme indiqué ci-dessus va créer un ValueConverter de l’instance et la définir sur la propriété.Calling HasConversion as shown above will create a ValueConverter instance and set it on the property. Le ValueConverter peut être créée à la place explicitement.The ValueConverter can instead be created explicitly. Exemple :For example:

var converter = new ValueConverter<EquineBeast, string>(
    v => v.ToString(),
    v => (EquineBeast)Enum.Parse(typeof(EquineBeast), v));

modelBuilder
    .Entity<Rider>()
    .Property(e => e.Mount)
    .HasConversion(converter);

Cela peut être utile lorsque plusieurs propriétés d’utilisent la même conversion.This can be useful when multiple properties use the same conversion.

Note

Il n’existe actuellement aucun moyen de spécifier au même endroit que toutes les propriétés d’un type donné doivent utiliser le même convertisseur de valeur.There is currently no way to specify in one place that every property of a given type must use the same value converter. Cette fonctionnalité sera utilisée pour une version ultérieure.This feature will be considered for a future release.

Convertisseurs intégrésBuilt-in converters

Est de base EF fourni avec un ensemble de prédéfinis ValueConverter classes, de la Microsoft.EntityFrameworkCore.Storage.ValueConversion espace de noms.EF Core ships with a set of pre-defined ValueConverter classes, found in the Microsoft.EntityFrameworkCore.Storage.ValueConversion namespace. Ces équivalents sont :These are:

  • BoolToZeroOneConverter -Bool à zéro et unBoolToZeroOneConverter - Bool to zero and one
  • BoolToStringConverter -Bool pour les chaînes telles que « Y » et « N »BoolToStringConverter - Bool to strings such as "Y" and "N"
  • BoolToTwoValuesConverter -Bool toutes les deux valeursBoolToTwoValuesConverter - Bool to any two values
  • BytesToStringConverter -Tableau d’octets chaîne codée en Base64BytesToStringConverter - Byte array to Base64-encoded string
  • CastingConverter -Les conversions qui nécessitent uniquement une conversion CsharpCastingConverter - Conversions that require only a Csharp cast
  • CharToStringConverter -Char en chaîne de caractères uniqueCharToStringConverter - Char to single character string
  • DateTimeOffsetToBinaryConverter -DateTimeOffset valeur codée en binaire de 64 bitsDateTimeOffsetToBinaryConverter - DateTimeOffset to binary-encoded 64-bit value
  • DateTimeOffsetToBytesConverter -DateTimeOffset en tableau d’octetsDateTimeOffsetToBytesConverter - DateTimeOffset to byte array
  • DateTimeOffsetToStringConverter -DateTimeOffset en chaîneDateTimeOffsetToStringConverter - DateTimeOffset to string
  • DateTimeToBinaryConverter -DateTime en valeur 64 bits, y compris DateTimeKindDateTimeToBinaryConverter - DateTime to 64-bit value including DateTimeKind
  • DateTimeToStringConverter -DateTime en stringDateTimeToStringConverter - DateTime to string
  • DateTimeToTicksConverter -DateTime en graduationsDateTimeToTicksConverter - DateTime to ticks
  • EnumToNumberConverter -Enum nombre sous-jacentEnumToNumberConverter - Enum to underlying number
  • EnumToStringConverter -Enum chaîneEnumToStringConverter - Enum to string
  • GuidToBytesConverter -Guid en tableau d’octetsGuidToBytesConverter - Guid to byte array
  • GuidToStringConverter -Guid en chaîneGuidToStringConverter - Guid to string
  • NumberToBytesConverter -N’importe quelle valeur numérique en tableau d’octetsNumberToBytesConverter - Any numerical value to byte array
  • NumberToStringConverter -N’importe quelle valeur numérique en chaîneNumberToStringConverter - Any numerical value to string
  • StringToBytesConverter -Chaîne UTF-8 octetsStringToBytesConverter - String to UTF8 bytes
  • TimeSpanToStringConverter -TimeSpan en chaîneTimeSpanToStringConverter - TimeSpan to string
  • TimeSpanToTicksConverter -Intervalle de temps en graduationsTimeSpanToTicksConverter - TimeSpan to ticks

Notez que EnumToStringConverter est inclus dans cette liste.Notice that EnumToStringConverter is included in this list. Cela signifie qu’il n’est pas nécessaire de spécifier la conversion explicite, comme indiqué ci-dessus.This means that there is no need to specify the conversion explicitly, as shown above. Utilisez simplement le convertisseur intégré :Instead, just use the built-in converter:

var converter = new EnumToStringConverter<EquineBeast>();

modelBuilder
    .Entity<Rider>()
    .Property(e => e.Mount)
    .HasConversion(converter);

Notez que tous les convertisseurs intégrés sont sans état et par conséquent, une seule instance peut être partagée en toute sécurité par plusieurs propriétés.Note that all the built-in converters are stateless and so a single instance can be safely shared by multiple properties.

Conversions prédéfiniesPre-defined conversions

Pour les conversions courantes pour lesquelles il existe un convertisseur intégré, il est inutile de spécifier le convertisseur explicitement.For common conversions for which a built-in converter exists there is no need to specify the converter explicitly. Au lieu de cela, simplement configurer le type de fournisseur doit être utilisé et EF utilisent automatiquement le convertisseur de build approprié.Instead, just configure which provider type should be used and EF will automatically use the appropriate build-in converter. Énumération pour les conversions de chaînes sont utilisées comme exemple ci-dessus, mais EF réellement fait automatiquement si le type de fournisseur est configuré :Enum to string conversions are used as an example above, but EF will actually do this automatically if the provider type is configured:

modelBuilder
    .Entity<Rider>()
    .Property(e => e.Mount)
    .HasConversion<string>();

La même chose peut être obtenue en spécifiant explicitement le type de colonne.The same thing can be achieved by explicitly specifying the column type. Par exemple, si le type d’entité est défini comme donc :For example, if the entity type is defined like so:

public class Rider
{
    public int Id { get; set; }

    [Column(TypeName = "nvarchar(24)")]
    public EquineBeast Mount { get; set; }
}

Ensuite, les valeurs enum seront enregistrés sous forme de chaînes dans la base de données sans aucune configuration supplémentaire dans OnModelCreating.Then the enum values will be saved as strings in the database without any further configuration in OnModelCreating.

LimitationsLimitations

Il existe quelques limitations actuelles connues du système de conversion de valeur :There are a few known current limitations of the value convertion system:

  • Comme indiqué précédemment, null ne peut pas être converti.As noted above, null cannot be converted.
  • Il n’existe actuellement aucun moyen pour répartir une conversion d’une propriété à plusieurs colonnes, ou vice versa.There is currently no way to spread a conversion of one property to multiple columns or vice-versa.
  • Utilisation des conversions de valeurs peut affecter la capacité de EF Core à traduire des expressions SQL.Use of value conversions may impact the ability of EF Core to translate expressions to SQL. Un avertissement sera consigné pour ces cas.A warning will be logged for such cases. La suppression de ces limitations est envisagée pour une version ultérieure.Removal of these limitations is being considered for a future release.