Conversions de valeursValue Conversions

Note

Cette fonctionnalité est une nouveauté d’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 écriture à 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 à l’autre du même type (par exemple, les chaînes de chiffrement) ou à partir d’une valeur d’un type à une valeur d’un autre type (par exemple, 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 des 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 : un dans ModelClrType à ProviderClrType et l’autre à partir 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’expressions 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 dans le OnModelCreating de votre DbContext.Value conversions are defined on properties in the OnModelCreating of your DbContext. Par exemple, considérez un type enum et une 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
}

Conversions peuvent être défini dans OnModelCreating pour stocker les valeurs d’énumération sous forme de chaînes (par exemple, « Donkey », « Chevaux »,...) dans la base de données :Then conversions can be defined in OnModelCreating to store the enum values as strings (for example, "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

Un null valeur ne sera jamais passée à un convertisseur de valeur.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 des propriétés nullables 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 HasConversion comme indiqué ci-dessus créera un ValueConverter de l’instance et le définir sur la propriété.Calling HasConversion as shown above will create a ValueConverter instance and set it on the property. Le ValueConverter à la place peuvent être créés 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 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 chaque propriété d’un type donné doive utiliser le même convertisseur de valeurs.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 considérée pour une version ultérieure.This feature will be considered for a future release.

Convertisseurs intégrésBuilt-in converters

EF Core est fourni avec un ensemble de prédéfinis ValueConverter classes, figurant dans le 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 aux deux valeursBoolToTwoValuesConverter - Bool to any two values
  • BytesToStringConverter -Tableau d’octets en chaîne codée en Base64BytesToStringConverter - Byte array to Base64-encoded string
  • CastingConverter -Les conversions qui requièrent uniquement un cast de typeCastingConverter - Conversions that require only a type cast
  • CharToStringConverter -Char en chaîne de caractères uniqueCharToStringConverter - Char to single character string
  • DateTimeOffsetToBinaryConverter -DateTimeOffset par rapport à la valeur de 64 bits codée en binaireDateTimeOffsetToBinaryConverter - DateTimeOffset to binary-encoded 64-bit value
  • DateTimeOffsetToBytesConverter -DateTimeOffset en tableau d’octetsDateTimeOffsetToBytesConverter - DateTimeOffset to byte array
  • DateTimeOffsetToStringConverter -DateTimeOffset par rapport à la chaîneDateTimeOffsetToStringConverter - DateTimeOffset to string
  • DateTimeToBinaryConverter -DateTime en valeur 64 bits, y compris DateTimeKindDateTimeToBinaryConverter - DateTime to 64-bit value including DateTimeKind
  • DateTimeToStringConverter -DateTime en chaîneDateTimeToStringConverter - 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 est inutile de spécifier la conversion explicitement, comme indiqué ci-dessus.This means that there is no need to specify the conversion explicitly, as shown above. Au lieu de cela, 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 donc 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, il suffit de configurer le type de fournisseur doit être utilisé et Entity Framework l’utilisera automatiquement le convertisseur intégré approprié.Instead, just configure which provider type should be used and EF will automatically use the appropriate built-in converter. Énumération pour les conversions de chaîne sont utilisés comme un exemple ci-dessus, mais EF permettra de faire cela 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; }
}

Puis 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 conversion system:

  • Comme indiqué ci-dessus, null ne peut pas être converti.As noted above, null cannot be converted.
  • Il n’existe actuellement aucun moyen de se propager 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 de conversions de valeurs peut impacter la capacité d’EF Core pour traduire des expressions to SQL.Use of value conversions may impact the ability of EF Core to translate expressions to SQL. Un avertissement est enregistré dans ces cas.A warning will be logged for such cases. Suppression de ces limitations est envisagée pour une version ultérieure.Removal of these limitations is being considered for a future release.